field_edits
Certain types of text files are tabular in nature, with field separators (e.g.
: or ,). The passwd and group files are classic examples of tabular
files, but there are many ways to use this feature. For example, editing a
string:
VARIABLE="one two three"
View this line as a tabular line separated by " and with sub-separator given by the space.
Field editing allows us to edit tabular files in a unique way, adding and removing data from addressable fields.
bundle agent example
{
vars:
"userset" slist => { "one-x", "two-x", "three-x" };
files:
"/tmp/passwd"
create => "true",
edit_line => SetUserParam("mark","6","/set/this/shell");
"/tmp/group"
create => "true",
edit_line => AppendUserParam("root","4","@(userset)");
}
The promise in this example assumes a parameterizable model for editing the fields of such files.
bundle edit_line SetUserParam(user,field,val)
{
field_edits:
"$(user):.*"
# Set field of the file to parameter
edit_field => col(":","$(field)","$(val)","set");
}
bundle edit_line AppendUserParam(user,field,allusers)
{
vars:
"val" slist => { @(allusers) };
field_edits:
"$(user):.*"
# Set field of the file to parameter
edit_field => col(":","$(field)","$(val)","alphanum");
}
First you match the line with a regular expression. The regular expression must match the entire line; that is, it is anchored.
body edit_field col(split,col,newval,method)
{
field_separator => "$(split)";
select_field => "$(col)";
value_separator => ",";
field_value => "$(newval)";
field_operation => "$(method)";
extend_fields => "true";
}
Then a field_edits body describes the separators for fields and
one level of sub-fields, along with policies for editing these fields,
ordering the items within them.
Attributes
edit_field
Type: body edit_field
Example:
body edit_field col(split, col, newval, method)
{
field_separator => "$(split)";
select_field => "$(col)";
value_separator => ",";
field_value => "$(newval)";
field_operation => "$(method)";
extend_fields => "true";
allow_blank_fields => "true";
start_fields_from_zero => "true";
}
Common Body Attributes
Common body attributes are available to all body types. Full details for common body attributes can be found in the Common Body Attributes section of the Promise Types and Attributes page. The common attributes are as follows:
inherit_from
meta
allow_blank_fields
Description: Setting allow_blank_fields defines how blank fields in a line are handled.
When editing a file using the field or column model, blank fields, especially
at the start and end, are generally discarded. If allow_blank_fields is set
to true, CFEngine will retain the blank fields and print the appropriate
number of field separators.
Type: boolean
Default value: false
Example:
body edit_field example
{
allow_blank_fields => "true";
}
extend_fields
Description: Setting extend_fields can add new fields, to avoid
triggering an error.
If a user specifies a field that does not exist, because there are not so many fields, this allows the number of fields to be extended. Without this setting, CFEngine will issue an error if a non-existent field is referenced. Blank fields in a tabular file can be eliminated or kept depending in this setting. If in doubt, set this to true.
Type: boolean
Default value: false
Example:
body edit_field example
{
extend_fields => "true";
}
field_operation
Description: Menu option policy for editing subfields.
The method by which to edit a field in multi-field/column editing of tabular files.
Type: (menu option)
Allowed input range:
append
Append the specified value to the end of the field/column, separating
(potentially) multiple values with value_separator
prepend
Prepend the specified value at the beginning of the field/column, separating
(potentially) multiple values with value_separator
alphanum
Insert the specified value into the field/column, keeping all the values
(separated by value_separator) in alphanumerically sorted order
set
Replace the entire field/column with the specified value.
Delete the specified value (if present) in the specified field/column.
Default value: append
Example:
body edit_field example
{
field_operation => "append";
}
field_separator
Description: The regular expression used to separate fields in a line.
Most tabular files are separated by simple characters, but by allowing a general regular expression one can make creative use of this model to edit all kinds of line-based text files.
Type: string
Allowed input range: .*
Default value: none
Example:
body edit_field example
{
field_separator => ":";
}
field_value
Description: Set a field to a constant value.
For example, reset the value to a constant default, empty the field, or set it fixed list.
Type: string
Allowed input range: .*
Example:
body edit_field example(s)
{
field_value => "$(s)";
}
select_field
Description: Sets the index of the field required, see also start_fields_from_zero.
Type: int
Allowed input range: 0,99999999
Example:
body field_edits example
{
select_field => "5";
}
start_fields_from_zero
Description: The numbering of fields is a matter for consistency and convention. Arrays are usually thought to start with first index equal to zero (0), but the first column in a file would normally be 1. By setting this option, you can tell CFEngine that the first column should be understood as number 0 instead, for consistency with other array functions.
Type: boolean
History: Version 3.1.0b1,Nova 2.0.0b1 (2010)
value_separator
Description: Defines the character separator for subfields inside the selected field.
For example, elements in the group file are separated by a colon (':'), but the lists of users in these fields are separated by a comma (',').
Type: string
Allowed input range: ^.$
Default value: none
Example:
body field_edit example
{
value_separator => ",";
}