field_edits

Table of Contents

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 => ",";
     }