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

Return type: slist

Description: Splits the file filename into separated values and returns the list.

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 : File name to read, in the range "?(/.*)
  • comment : Unanchored regex matching comments, in the range .*
  • split : Unanchored regex to split data, in the range .*
  • maxentries : Maximum number of entries to read, in the range 0,99999999999
  • maxbytes : Maximum bytes to read, in the range 0,99999999999

Example:

Prepare:

printf "one\ntwo\nthree\n"           > /tmp/list.txt
printf " # commented line\n"        >> /tmp/list.txt
printf "1\n2\n3\n"                  >> /tmp/list.txt
printf "# another commented line\n" >> /tmp/list.txt
printf "Not a commented # line\n"   >> /tmp/list.txt
printf "1.0\n2.0\n3.0"              >> /tmp/list.txt

Run:

bundle agent example_readstringlist
{
  vars:
      "my_list_of_strings"
        slist => readstringlist( "/tmp/list.txt", # File to read
                              "^\s*#[^\n]*",      # Exclude hash comment lines lines
                              "\n",               # Split on newlines
                              inf,                # Maximum number of entries
                              inf);               # Maximum number of bytes to read

  reports:
      "my_list_of_strings includes '$(my_list_of_strings)'";
}
bundle agent __main__
{
  methods: "example_readstringlist";
}

Output:

R: my_list_of_strings includes 'one'
R: my_list_of_strings includes 'two'
R: my_list_of_strings includes 'three'
R: my_list_of_strings includes '1'
R: my_list_of_strings includes '2'
R: my_list_of_strings includes '3'
R: my_list_of_strings includes 'Not a commented # line'
R: my_list_of_strings includes '1.0'
R: my_list_of_strings includes '2.0'
R: my_list_of_strings includes '3.0'

See also: readintlist(), readreallist()