Prototype: data_readstringarray(filename, comment, split, maxentries, maxbytes)

Return type: data

Description: Returns a data container (map) with up to maxentries-1 fields from the first maxbytes bytes of file filename. The first field becomes the key in the map.

One dimension is separated by the regex split, the other by the lines in the file. The array key (the first field) must be unique; if you need to allow duplicate lines use data_readstringarrayidx().

The comment field is a multiline regular expression and will strip out unwanted patterns from the file being read, leaving unstripped characters to be split into fields. Using the empty string ("") indicates no comments.

Arguments:

  • filename: string, in the range: "?(/.*)
  • comment: string, in the range: .*
  • split: string, in the range: .*
  • maxentries: int, in the range: 0,99999999999
  • maxbytes: int, in the range: 0,99999999999

Example:

Prepare:

echo a,b,c > /tmp/cfe_array
echo "# This is a comment" >> /tmp/cfe_array
echo d,e,f >> /tmp/cfe_array
echo g,h,i >> /tmp/cfe_array
echo "# This is another comment" >> /tmp/cfe_array
echo j,k,l >> /tmp/cfe_array

Run:

body common control
{
      bundlesequence => { "example" };
}

bundle agent example
{
  vars:
      # The comment regex warrents an explination:
      # # matches the character # literally
      # [^\n]* match a single character not including the newline character
      # between zero and unlimited times, as many times as possible
      "bykey" data => data_readstringarray("/tmp/cfe_array","#[^\n]*",",",10,400);
      "byint" data => data_readstringarrayidx("/tmp/cfe_array","#[^\n]*",",",10,400);

      "bykey_str" string => format("%S", bykey);
      "byint_str" string => format("%S", byint);
  reports:
      "By key: $(bykey_str)";
      "specific element by key a, offset 0: '$(bykey[a][0])'";
      "By int offset: $(byint_str)";
      "specific element by int offset 2, 0: '$(byint[2][0])'";

}

Output:

R: By key: {"a":["b","c"],"d":["e","f"],"g":["h","i"],"j":["k","l"]}
R: specific element by key a, offset 0: 'b'
R: By int offset: [["a","b","c"],["d","e","f"],["g","h","i"],["j","k","l"]]
R: specific element by int offset 2, 0: 'g'

See also: data_readstringarrayidx(), data

History:

  • Added in CFEngine 3.6.0