From 99a0ca9360e85eade331d1a4885d501e8fb78288 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 10:22:10 -0400
Subject: [PATCH 01/13] classesmatching() docs

---
 reference/functions/classesmatching.markdown | 55 ++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 reference/functions/classesmatching.markdown

diff --git a/reference/functions/classesmatching.markdown b/reference/functions/classesmatching.markdown
new file mode 100644
index 000000000..96c367618
--- /dev/null
+++ b/reference/functions/classesmatching.markdown
@@ -0,0 +1,55 @@
+---
+layout: default
+title: classesmatching
+categories: [Reference, Functions, classesmatching]
+published: true
+alias: reference-functions-classesmatching.html
+tags: [reference, functions, classesmatching]
+---
+
+### Function classesmatching
+
+**Synopsis**: classesmatching(arg1) returns type **slist**
+
+  
+ *arg1* : Regular expression, *in the range* .\*   
+
+Return the defined classes matching regex arg1
+
+**Example**:  
+   
+
+```cf3
+body common control
+{
+      bundlesequence => { run };
+}
+
+bundle agent run
+{
+  vars:
+      "all" slist => classesmatching(".*");
+      "c" slist => classesmatching("cfengine");
+  reports:
+      "All classes = $(all)";
+      "Classes matching 'cfengine' = $(c)";
+}
+
+```
+
+**Notes**:  
+   
+This function searches for the regular expression in the list of
+currently defined classes (hard, then soft, then local to the current
+bundle).
+
+This function replaces the `allclasses.txt` static file available
+in older versions of CFEngine.
+
+regex
+
+A regular expression matching zero or more classes in the current list
+of defined classes. The regular expression is not anchored
+(See [Anchored vs. unanchored regular expressions](#Anchored-vs_002e-unanchored-regular-expressions)).
+
+The function returns the list of classes matched.

From 15b4378bd4b8707fa97b072f38432ed011e6baec Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 10:31:53 -0400
Subject: [PATCH 02/13] filestat() docs

---
 reference/functions/filestat.markdown | 44 +++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 reference/functions/filestat.markdown

diff --git a/reference/functions/filestat.markdown b/reference/functions/filestat.markdown
new file mode 100644
index 000000000..345f1c13a
--- /dev/null
+++ b/reference/functions/filestat.markdown
@@ -0,0 +1,44 @@
+---
+layout: default
+title: filestat
+categories: [Reference, Functions, filestat]
+published: true
+alias: reference-functions-filestat.html
+tags: [reference, functions, filestat]
+---
+
+### Function filestat
+
+**Synopsis**: filestat(arg1, arg2) returns type **string**
+
+  
+ *arg1* : File object name, *in the range* "?(/.\*)   
+ *arg2* : Name of field to retrieve, *in the range*
+size,gid,uid,ino,nlink,ctime,atime,mtime,mode,modeoct,permstr,permoct,type,devno,dev_minor,dev_major,basename,dirname   
+
+Returns the requested file field
+
+**Example**:  
+   
+
+```cf3
+bundle agent fileinfo(f)
+{
+  vars:
+      "fields" slist => splitstring("size,gid,uid,ino,nlink,ctime,atime,mtime,mode,modeoct,permstr,permoct,type,devno,dev_minor,dev_major,basename,dirname", ",", 999);
+
+      "stat[$(f)][$(fields)]" string => filestat($(f), $(fields));
+
+  reports:
+      "$(this.bundle): file $(f) has $(fields) = $(stat[$(f)][$(fields)])";
+}
+```
+
+**Notes**:  
+   
+The list of fields may be extended as needed.
+
+*History*: Was introduced in version 3.5.0,Enterprise 3.1 (2013)
+
+If the file object does not exist, the function call fails and the
+variable does not expand.

From 04dec34ded4b19352eaf0684428b677d7b7a0a36 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 10:48:36 -0400
Subject: [PATCH 03/13] ifelse() docs

---
 reference/functions/ifelse.markdown | 104 ++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 reference/functions/ifelse.markdown

diff --git a/reference/functions/ifelse.markdown b/reference/functions/ifelse.markdown
new file mode 100644
index 000000000..a85440654
--- /dev/null
+++ b/reference/functions/ifelse.markdown
@@ -0,0 +1,104 @@
+---
+layout: default
+title: ifelse
+categories: [Reference, Functions, ifelse]
+published: true
+alias: reference-functions-ifelse.html
+tags: [reference, functions, ifelse]
+---
+
+### Function ifelse
+
+**Synopsis**: ifelse(...) returns type **string**
+
+  
+
+Requires an odd number of arguments.  Evaluate each pair of arguments up to the last one as a (class, value) tuple, returning the value if the class is true.  If none are true, returns the last argument.
+
+**Example**:  
+   
+
+```cf3
+body common control
+
+{
+bundlesequence  => { "example" };
+}
+
+###########################################################
+
+bundle agent example
+
+{     
+  classes:
+      "myclass" expression => "any";
+      "myclass2" expression => "any";
+      "secondpass" expression => "any";
+  vars:
+      # we need to use the secondpass class because on the first pass,
+      # myclass and myclass2 are not defined yet
+
+    secondpass::
+
+      # result: { "1", "single string parameter", "hardclass OK", "bundle class OK", "5 parameters OK" }
+
+      "mylist" slist => {
+                          ifelse(1),
+                          ifelse("single string parameter"),
+                          ifelse("cfengine", "hardclass OK", "hardclass broken"),
+                          ifelse("myclass.myclass2", "bundle class OK", "bundle class broken"),
+                          ifelse("this is not true", "5 parameters broken",
+                                 "this is also not true", "5 parameters broken 2",
+                                 "5 parameters OK"),
+                        };
+
+  reports:
+      "ifelse result list: $(mylist)";
+}
+```
+
+**Notes**:  
+   
+The `ifelse` function is like a multi-level if-else statement.  It was
+inspired by Oracle's `DECODE` function.  It must have an odd number of
+arguments (from 1 to N).  The last argument is the default value, like
+the `else` clause in standard programming languages.  Every pair of
+arguments before the last one are evaluated as a pair.  If the first
+one evaluates true (as if you had used it in a class `expression`, so
+it can be more than just a class name, it's a whole context like
+`Tuesday.linux.!verbose`) then the second one is returned.
+
+Generally, if `ifelse` were called with arguments `(a1, a2, b1,
+b2, c)`, the behavior expressed as pseudo-code is:
+
+```
+if a1 then return a2
+else-if b1 then return b2
+else return c
+```
+
+(But again, note that any odd number of arguments is supported.)
+
+The `ifelse` function is extremely useful when you want to avoid
+explicitly stating the negative of all the expected cases; this
+problem is commonly seen like so:
+
+```cf3
+  class1.class2::
+    "myvar" string => "x";
+
+  class3.!class2::
+    "myvar" string => "y";
+
+  !((class1.class2)||class3.!class2)::
+    "myvar" string => "z";
+```
+
+That's hard to read and error-prone (do you know how `class2` will
+affect the default case?).  Here's the alternative with `ifelse`:
+
+```cf3
+    "myvar" string => ifelse("class1.class2", "x",
+                             "class3.!class2", "y",
+                             "z");
+```

From 6a0b1de4bbbeb54f97019296ebc35721fb876634 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:17:02 -0400
Subject: [PATCH 04/13] maparray() docs

---
 reference/functions/maparray.markdown | 65 +++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 reference/functions/maparray.markdown

diff --git a/reference/functions/maparray.markdown b/reference/functions/maparray.markdown
new file mode 100644
index 000000000..7cf3508a6
--- /dev/null
+++ b/reference/functions/maparray.markdown
@@ -0,0 +1,65 @@
+---
+layout: default
+title: maparray
+categories: [Reference, Functions, maparray]
+published: true
+alias: reference-functions-maparray.html
+tags: [reference, functions, maparray]
+---
+
+### Function maparray
+
+**Synopsis**: maparray(arg1,arg2) returns type **slist**
+
+  
+ *arg1* : Pattern based on \$(this.k) and \$(this.v) as original text, *in the range* .\*
+  
+ *arg2* : The name of the array variable to map, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Return a list with each element modified by a pattern based on \$(this.k) and \$(this.v)
+
+**Example**:  
+   
+
+```cf3
+body common control
+{
+      bundlesequence => { run };
+}
+
+bundle agent run
+{
+  vars:
+      "todo[1]" string => "2";
+      "todo[one]" string => "two";
+      "todo[3999]" slist => { "big", "small" };
+      "map" slist => maparray("yes $(this.k) $(this.v)", "todo");
+
+  reports:
+    cfengine::
+      "Hello $(map)";
+}
+
+```
+
+Output:
+
+```
+Hello yes 1 2
+Hello yes one two
+Hello yes 3999 big
+Hello yes 3999 small
+```
+
+**Notes**:  
+
+The `this.k` and `this.v` variables will be available for expansion in
+the string scope, similar to the way `this` is available for
+`maplist`.
+
+If a value in the array is an slist, you'll get one result for each
+value (implicit looping).
+
+The order of the array keys is not guaranteed.  Use the `sort`
+function if you need order in the resulting output.

From 482947ab1d3679a4843e8d18d4a7e6b2c8f1ca38 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:17:12 -0400
Subject: [PATCH 05/13] strftime() docs

---
 reference/functions/strftime.markdown | 292 ++++++++++++++++++++++++++
 1 file changed, 292 insertions(+)
 create mode 100644 reference/functions/strftime.markdown

diff --git a/reference/functions/strftime.markdown b/reference/functions/strftime.markdown
new file mode 100644
index 000000000..b7bdc138b
--- /dev/null
+++ b/reference/functions/strftime.markdown
@@ -0,0 +1,292 @@
+---
+layout: default
+title: strftime
+categories: [Reference, Functions, strftime]
+published: true
+alias: reference-functions-strftime.html
+tags: [reference, functions, strftime]
+---
+
+### Function strftime
+
+**Synopsis**: strftime(arg1,arg2) returns type **string**
+
+  
+ *arg1* : Mode, *in the range* gmtime,localtime   
+ *arg2* : Format string, *in the range* .\*   
+ *arg3* : Unix epoch time *in the range* \d+
+
+Interprets a time and date format string at a particular point in GMT or local time using Unix epoch time.
+
+**Example**:  
+   
+
+```cf3
+body common control
+{
+  bundlesequence  => { "example" };
+}
+
+###########################################################
+
+bundle agent example
+
+{     
+  vars:
+      "time" int => now();
+      "now" string => strftime("localtime", "%F %T", now());
+      "then" string => strftime("localtime", "%F %T", 0);
+
+      "gmt_now" string => strftime("gmtime", "%F %T", now());
+      "gmt_then" string => strftime("gmtime", "%F %T", 0);
+
+  reports:
+      "time $(time); now $(now); then $(then)";
+      "time $(time); GMT now $(now); GMT then $(then)";
+}
+
+```
+
+**Notes**:  
+   
+
+Note that `strftime` is a standard C function and you should
+consult its reference to be sure of the specifiers it allows.  The below
+is from the documentation of the standard `strftime` implementation
+in the glibc manual at http://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#Formatting-Calendar-Time
+
+This function takes a *mode*, a *template* and a *time*.
+
+The *mode* is either `gmtime` (to get GMT times and dates) or
+`localtime` (to get times and dates according to the local
+timezone, usually specified by the `TZ` environment variable).
+
+The conversion specifications that can appear in the format template
+*template* are specialized for printing components of the date and
+time according to the system locale.  The *time* is simply an
+integer (Unix epoch time); you can get the current time with the
+`now` function.
+
+Ordinary characters appearing in the *template* are copied to the
+output.  Conversion specifiers are introduced by a `%` character
+and end with a format specifier taken from the following list.  The
+whole `%` sequence is replaced in the output string as follows:
+
+* `%a`
+The abbreviated weekday name according to the current locale.
+
+* `%A`
+The full weekday name according to the current locale.
+
+* `%b`
+The abbreviated month name according to the current locale.
+
+* `%B`
+The full month name according to the current locale.
+
+Using `%B` together with `%d` produces grammatically
+incorrect results for some locales.
+
+* `%c`
+The preferred calendar time representation for the current locale.
+
+* `%C`
+The century of the year.  This is equivalent to the greatest integer not
+greater than the year divided by 100.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%d`
+The day of the month as a decimal number (range `01` through `31`).
+
+* `%D`
+The date using the format `%m/%d/%y`.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%e`
+The day of the month like with `%d`, but padded with blank (range
+` 1` through `31`).
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%F`
+The date using the format `%Y-%m-%d`.  This is the form specified
+in the *ISO 8601* standard and is the preferred form for all uses.
+
+This format was first standardized by *ISO C99* and by *POSIX.1-2001*.
+
+* `%g`
+The year corresponding to the ISO week number, but without the century
+(range `00` through `99`).  This has the same format and value
+as `%y`, except that if the ISO week number (see `%V`) belongs
+to the previous or next year, that year is used instead.
+
+This format was first standardized by *ISO C99* and by *POSIX.1-2001*.
+
+* `%G`
+The year corresponding to the ISO week number.  This has the same format
+and value as `%Y`, except that if the ISO week number (see
+`%V`) belongs to the previous or next year, that year is used
+instead.
+
+This format was first standardized by *ISO C99* and by *POSIX.1-2001*
+but was previously available as a GNU extension.
+
+* `%h`
+The abbreviated month name according to the current locale.  The action
+is the same as for `%b`.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%H`
+The hour as a decimal number, using a 24-hour clock (range `00` through
+`23`).
+
+* `%I`
+The hour as a decimal number, using a 12-hour clock (range `01` through
+`12`).
+
+* `%j`
+The day of the year as a decimal number (range `001` through `366`).
+
+* `%k`
+The hour as a decimal number, using a 24-hour clock like `%H`, but
+padded with blank (range ` 0` through `23`).
+
+This format is a GNU extension.
+
+* `%l`
+The hour as a decimal number, using a 12-hour clock like `%I`, but
+padded with blank (range ` 1` through `12`).
+
+This format is a GNU extension.
+
+* `%m`
+The month as a decimal number (range `01` through `12`).
+
+* `%M`
+The minute as a decimal number (range `00` through `59`).
+
+* `%n`
+A single `\n` (newline) character.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%p`
+Either `AM` or `PM`, according to the given time value; or the
+corresponding strings for the current locale.  Noon is treated as
+`PM` and midnight as `AM`.  In most locales
+`AM`/`PM` format is not supported, in such cases `%p`
+yields an empty string.
+
+* `%P`
+Either `am` or `pm`, according to the given time value; or the
+corresponding strings for the current locale, printed in lowercase
+characters.  Noon is treated as `pm` and midnight as `am`.  In
+most locales `AM`/`PM` format is not supported, in such cases
+`%P` yields an empty string.
+
+This format is a GNU extension.
+
+
+* `%r`
+The complete calendar time using the AM/PM format of the current locale.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+In the POSIX locale, this format is equivalent to `%I:%M:%S %p`.
+
+* `%R`
+The hour and minute in decimal numbers using the format `%H:%M`.
+
+This format was first standardized by *ISO C99* and by *POSIX.1-2001*
+but was previously available as a GNU extension.
+
+* `%s`
+The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
+Leap seconds are not counted unless leap second support is available.
+
+This format is a GNU extension.
+
+* `%S`
+The seconds as a decimal number (range `00` through `60`).
+
+* `%t`
+A single `\t` (tabulator) character.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%T`
+The time of day using decimal numbers using the format `%H:%M:%S`.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%u`
+The day of the week as a decimal number (range `1` through
+`7`), Monday being `1`.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%U`
+The week number of the current year as a decimal number (range `00`
+through `53`), starting with the first Sunday as the first day of
+the first week.  Days preceding the first Sunday in the year are
+considered to be in week `00`.
+
+* `%V`
+The *ISO 8601:1988* week number as a decimal number (range `01`
+through `53`).  ISO weeks start with Monday and end with Sunday.
+Week `01` of a year is the first week which has the majority of its
+days in that year; this is equivalent to the week containing the year's
+first Thursday, and it is also equivalent to the week containing January
+4.  Week `01` of a year can contain days from the previous year.
+The week before week `01` of a year is the last week (`52` or
+`53`) of the previous year even if it contains days from the new
+year.
+
+This format was first standardized by *POSIX.2-1992* and by *ISO C99*.
+
+* `%w`
+The day of the week as a decimal number (range `0` through
+`6`), Sunday being `0`.
+
+* `%W`
+The week number of the current year as a decimal number (range `00`
+through `53`), starting with the first Monday as the first day of
+the first week.  All days preceding the first Monday in the year are
+considered to be in week `00`.
+
+* `%x`
+The preferred date representation for the current locale.
+
+* `%X`
+The preferred time of day representation for the current locale.
+
+* `%y`
+The year without a century as a decimal number (range `00` through
+`99`).  This is equivalent to the year modulo 100.
+
+* `%Y`
+The year as a decimal number, using the Gregorian calendar.  Years
+before the year `1` are numbered `0`, `-1`, and so on.
+
+* `%z`
+*RFC 822*/*ISO 8601:1988* style numeric time zone (e.g.,
+`-0600` or `+0100`), or nothing if no time zone is
+determinable.
+
+This format was first standardized by *ISO C99* and by *POSIX.1-2001*
+but was previously available as a GNU extension.
+
+In the POSIX locale, a full *RFC 822* timestamp is generated by the format
+`%a, %d %b %Y %H:%M:%S %z` (or the equivalent
+`%a, %d %b %Y %T %z`).
+
+* `%Z`
+The time zone abbreviation (empty if the time zone can't be determined).
+
+* `%%`
+A literal `%` character.
+
+According to *POSIX.1* every call to `strftime` checks the contents
+of the environment variable `TZ` before any output is produced.

From 070bdfc36905a1378a4f9523531511f7c45d4121 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:24:31 -0400
Subject: [PATCH 06/13] every(), some(), and none() docs

---
 reference/functions/every.markdown | 59 ++++++++++++++++++++++++++++++
 reference/functions/none.markdown  | 59 ++++++++++++++++++++++++++++++
 reference/functions/some.markdown  | 59 ++++++++++++++++++++++++++++++
 3 files changed, 177 insertions(+)
 create mode 100644 reference/functions/every.markdown
 create mode 100644 reference/functions/none.markdown
 create mode 100644 reference/functions/some.markdown

diff --git a/reference/functions/every.markdown b/reference/functions/every.markdown
new file mode 100644
index 000000000..4a4bb7c23
--- /dev/null
+++ b/reference/functions/every.markdown
@@ -0,0 +1,59 @@
+---
+layout: default
+title: every
+categories: [Reference, Functions, every]
+published: true
+alias: reference-functions-every.html
+tags: [reference, functions, every]
+---
+
+### Function every
+
+**Synopsis**: every(arg1,arg2) returns type **class**
+
+  
+ *arg1* : Regular expression to find, *in the range* .\*
+  
+ *arg2* : The name of the list variable to check, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Return true if every element of the list matches the regular expression.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  classes:
+      "every1" expression => every(".*", "test");
+      "every2" expression => every(".", "test");
+
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+  reports:
+      "The test list is $(test)";
+    every1::
+      "every() test 1 passed";
+    !every1::
+      "every() test 1 failed";
+    every2::
+      "every() test 2 failed";
+    !every2::
+      "every() test 2 passed";
+}
+```
+
+**Notes**:  
+   
+See also `filter`, `some`, and `none`.
+
+The regular expression is unanchored.
diff --git a/reference/functions/none.markdown b/reference/functions/none.markdown
new file mode 100644
index 000000000..b1fafd5d8
--- /dev/null
+++ b/reference/functions/none.markdown
@@ -0,0 +1,59 @@
+---
+layout: default
+title: none
+categories: [Reference, Functions, none]
+published: true
+alias: reference-functions-none.html
+tags: [reference, functions, none]
+---
+
+### Function none
+
+**Synopsis**: none(arg1,arg2) returns type **class**
+
+  
+ *arg1* : Unanchored regular expression to find, *in the range* .\*
+  
+ *arg2* : The name of the list variable to check, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Return true if no element of the list matches the regular expression.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  classes:
+      "none1" expression => none("jebadiah", "test");
+      "none2" expression => none("2", "test");
+
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+  reports:
+      "The test list is $(test)";
+    none1::
+      "none() test 1 passed";
+    !none1::
+      "none() test 1 failed";
+    none2::
+      "none() test 2 failed";
+    !none2::
+      "none() test 2 passed";
+}
+```
+
+**Notes**:  
+   
+See also `filter`, `every`, and `some`.
+
+The regular expression is unanchored.
diff --git a/reference/functions/some.markdown b/reference/functions/some.markdown
new file mode 100644
index 000000000..bf5d7a1b5
--- /dev/null
+++ b/reference/functions/some.markdown
@@ -0,0 +1,59 @@
+---
+layout: default
+title: some
+categories: [Reference, Functions, some]
+published: true
+alias: reference-functions-some.html
+tags: [reference, functions, some]
+---
+
+### Function some
+
+**Synopsis**: some(arg1,arg2) returns type **class**
+
+  
+ *arg1* : Unanchored regular expression to find, *in the range* .\*
+  
+ *arg2* : The name of the list variable to check, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Return true if any element of the list matches the regular expression.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  classes:
+      "some1" expression => some("long string", "test");
+      "some2" expression => some("none", "test");
+
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+  reports:
+      "The test list is $(test)";
+    some1::
+      "some() test 1 passed";
+    !some1::
+      "some() test 1 failed";
+    some2::
+      "some() test 2 failed";
+    !some2::
+      "some() test 2 passed";
+}
+```
+
+**Notes**:  
+   
+See also `filter`, `every`, and `none`.
+
+The regular expression is unanchored.

From 775f96aedd546066284bd1839c4f6fc439a75146 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:32:05 -0400
Subject: [PATCH 07/13] filter() docs

---
 reference/functions/filter.markdown | 67 +++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 reference/functions/filter.markdown

diff --git a/reference/functions/filter.markdown b/reference/functions/filter.markdown
new file mode 100644
index 000000000..e40cd6e0e
--- /dev/null
+++ b/reference/functions/filter.markdown
@@ -0,0 +1,67 @@
+---
+layout: default
+title: filter
+categories: [Reference, Functions, filter]
+published: true
+alias: reference-functions-filter.html
+tags: [reference, functions, filter]
+---
+
+### Function filter
+
+**Synopsis**: filter(arg1,arg2,arg3,arg4,arg5) returns type **slist**
+
+  
+ *arg1* : Anchored regular expression or static string to find, *in the range* .\*
+  
+ *arg2* : The name of the list variable to check, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+ *arg3* : Boolean: treat arg1 as a regular expression or as a static string. *in the range* true,false
+
+ *arg4* : Boolean: Invert filter. *in the range* true,false
+
+ *arg5* : Maximum number of elements to return *in the range* 0,999999999
+
+Return list of up to arg5 elements of arg2 that match the specified filtering rules.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "one", "two", "three",
+                      };
+
+      "test_grep" slist => filter("[0-9]", "test", "true", "false", 999);
+      "test_exact1" slist => filter("one", "test", "false", "false", 999);
+      "test_exact2" slist => filter(".", "test", "false", "false", 999);
+      "test_invert" slist => filter("[0-9]", "test", "true", "true", 999);
+      "test_max2" slist => filter(".*", "test", "true", "false", 2);
+      "test_max0" slist => filter(".*", "test", "true", "false", 0);
+      "grep" slist => grep("[0-9]", "test");
+
+  reports:
+      "The test list is $(test)";
+      "The grepped list is $(grep)";
+      "The filter-grepped list is $(test_grep)";
+      "The filter-exact list, looking for 'one' is $(test_exact1)";
+      "This line should not appear: $(test_exact2)";
+      "The filter-invert list, looking for non-digits, is $(test_invert)";
+      "The filter-bound list, matching at most 2 items, is $(test_max2)";
+      "This line should not appear: $(test_max0)";
+}
+```
+
+**Notes**:  
+
+This is a generic filtering function to transform a list into a subset thereof.
+
+See also `grep`, `every`, `some`, and `none`.

From 222711fb37a371f349966d3e1f1443fe5dce2588 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:43:34 -0400
Subject: [PATCH 08/13] sublist() docs

---
 reference/functions/sublist.markdown | 62 ++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 reference/functions/sublist.markdown

diff --git a/reference/functions/sublist.markdown b/reference/functions/sublist.markdown
new file mode 100644
index 000000000..409497a82
--- /dev/null
+++ b/reference/functions/sublist.markdown
@@ -0,0 +1,62 @@
+---
+layout: default
+title: sublist
+categories: [Reference, Functions, sublist]
+published: true
+alias: reference-functions-sublist.html
+tags: [reference, functions, sublist]
+---
+
+### Function sublist
+
+**Synopsis**: sublist(arg1,arg2,arg3) returns type **slist**
+
+ *arg1* : The name of the list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+ *arg2* : Whether to extract elements from the beginning or from the end. *in the range* head,tail
+
+ *arg3* : Maximum number of elements to return *in the range* 0,999999999
+
+Return list of up to arg3 elements of arg1, obtained from head or tail depending on arg2.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                      };
+
+      "test_head9999" slist => sublist("test", "head", 9999);
+      "test_head1" slist => sublist("test", "head", 1);
+      "test_head0" slist => sublist("test", "head", 0);
+
+      "test_tail9999" slist => sublist("test", "tail", 9999);
+      "test_tail10" slist => sublist("test", "tail", 10);
+      "test_tail2" slist => sublist("test", "tail", 2);
+      "test_tail1" slist => sublist("test", "tail", 1);
+      "test_tail0" slist => sublist("test", "tail", 0);
+
+  reports:
+      "The test list is $(test)";
+      "This line should not appear: $(test_head0)";
+      "The head(1) of the test list is $(test_head1)";
+      "The head(9999) of the test list is $(test_head9999)";
+      "This line should not appear: $(test_tail0)";
+      "The tail(1) of the test list is $(test_tail1)";
+      "The tail(10) of the test list is $(test_tail10)";
+      "The tail(2) of the test list is $(test_tail2)";
+      "The tail(9999) of the test list is $(test_tail9999)";
+}
+```
+
+**Notes**:  
+

From cf471739c36067936b79decba0696eecaaca3168 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:43:44 -0400
Subject: [PATCH 09/13] unique() docs

---
 reference/functions/unique.markdown | 47 +++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 reference/functions/unique.markdown

diff --git a/reference/functions/unique.markdown b/reference/functions/unique.markdown
new file mode 100644
index 000000000..bdb4bf03d
--- /dev/null
+++ b/reference/functions/unique.markdown
@@ -0,0 +1,47 @@
+---
+layout: default
+title: unique
+categories: [Reference, Functions, unique]
+published: true
+alias: reference-functions-unique.html
+tags: [reference, functions, unique]
+---
+
+### Function unique
+
+**Synopsis**: unique(arg1) returns type **slist**
+
+ *arg1* : The name of the list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+
+Return list of unique elements of arg1.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+      "test_str" string => join(",", "test");
+      "test_unique" slist => unique("test");
+      "unique_str" string => join(",", "test_unique");
+
+  reports:
+      "The test list is $(test_str)";
+      "The unique elements of the test list: $(unique_str)";
+}
+```
+
+**Notes**:  
+

From f59bd389eeddf973180658eba638950828f33de8 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:45:26 -0400
Subject: [PATCH 10/13] nth() docs

---
 reference/functions/nth.markdown | 54 ++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 reference/functions/nth.markdown

diff --git a/reference/functions/nth.markdown b/reference/functions/nth.markdown
new file mode 100644
index 000000000..3b190ebe0
--- /dev/null
+++ b/reference/functions/nth.markdown
@@ -0,0 +1,54 @@
+---
+layout: default
+title: nth
+categories: [Reference, Functions, nth]
+published: true
+alias: reference-functions-nth.html
+tags: [reference, functions, nth]
+---
+
+### Function nth
+
+**Synopsis**: nth(arg1,arg2) returns type **string**
+
+ *arg1* : The name of the list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+ *arg2* : Zero-based position of element to extract *in the range* 0,999999999
+
+Return the element of arg1 at zero-based position arg2.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+      "nth" slist => { 1, 2, 6, 10, 11, 1000 };
+
+      "test[$(nth)]" string => nth("test", $(nth));
+      "test[0]" string => nth("test", 0);
+
+  reports:
+      "The test list is $(test)";
+      "element #$(nth) of the test list: $(test[$(nth)])";
+      "element #0 of the test list: $(test[0])";
+}
+```
+
+**Notes**:  
+
+If an invalid position (under 0 or over the size of the list minus 1)
+is requested, this function does not return a valid value.
+
+See also `length`.

From 1dd5532ab7f6ea22e9b11ccad579636cc0084c8e Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:47:48 -0400
Subject: [PATCH 11/13] length() docs

---
 reference/functions/length.markdown | 46 +++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 reference/functions/length.markdown

diff --git a/reference/functions/length.markdown b/reference/functions/length.markdown
new file mode 100644
index 000000000..0678c2379
--- /dev/null
+++ b/reference/functions/length.markdown
@@ -0,0 +1,46 @@
+---
+layout: default
+title: length
+categories: [Reference, Functions, length]
+published: true
+alias: reference-functions-length.html
+tags: [reference, functions, length]
+---
+
+### Function length
+
+**Synopsis**: length(arg1) returns type **int**
+
+ *arg1* : The name of the list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Return the length of list arg1.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "test" slist => {
+                        1,2,3,
+                        "one", "two", "three",
+                        "long string",
+                        "four", "fix", "six",
+                        "one", "two", "three",
+                      };
+
+      "length" int => length("test");
+      "test_str" string => join(",", "test");
+
+  reports:
+      "The test list is $(test_str)";
+      "The test list has $(length) elements";
+}
+```
+
+**Notes**:  
+
+See also `nth`.

From ec036a8af4c74f3cdc3d14175c0c490984acaebf Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 11:57:34 -0400
Subject: [PATCH 12/13] intersection() and difference() docs

---
 reference/functions/difference.markdown   | 47 +++++++++++++++++++++++
 reference/functions/intersection.markdown | 47 +++++++++++++++++++++++
 2 files changed, 94 insertions(+)
 create mode 100644 reference/functions/difference.markdown
 create mode 100644 reference/functions/intersection.markdown

diff --git a/reference/functions/difference.markdown b/reference/functions/difference.markdown
new file mode 100644
index 000000000..0fd9c572d
--- /dev/null
+++ b/reference/functions/difference.markdown
@@ -0,0 +1,47 @@
+---
+layout: default
+title: difference
+categories: [Reference, Functions, difference]
+published: true
+alias: reference-functions-difference.html
+tags: [reference, functions, difference]
+---
+
+### Function difference
+
+**Synopsis**: difference(arg1,arg2) returns type **slist**
+
+ *arg1* : The name of the base list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+ *arg2* : The name of the subtracted list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Returns the unique elements in arg1 that are not in arg2.
+
+**Example**:  
+   
+
+```cf3
+bundle agent test
+
+{
+  vars:
+      "a" slist => { 1,2,3,"x" };
+      "b" slist => { "x" };
+
+      "listname1" slist => { "a", "b" };
+      "listname2" slist => { "a", "b" };
+      "$(listname1)_str" string => join(",", $(listname1));
+
+      "diff_$(listname1)_$(listname2)" slist => difference($(listname1), $(listname2));
+      "diff_$(listname1)_$(listname2)_str" string => join(",", "diff_$(listname1)_$(listname2)");
+
+  reports:
+      "The difference of list '$($(listname1)_str)' with '$($(listname2)_str)' is '$(diff_$(listname1)_$(listname2)_str)'";
+}
+```
+
+**Notes**:  
+
+See also `intersection`.
diff --git a/reference/functions/intersection.markdown b/reference/functions/intersection.markdown
new file mode 100644
index 000000000..8cb82e6f7
--- /dev/null
+++ b/reference/functions/intersection.markdown
@@ -0,0 +1,47 @@
+---
+layout: default
+title: intersection
+categories: [Reference, Functions, intersection]
+published: true
+alias: reference-functions-intersection.html
+tags: [reference, functions, intersection]
+---
+
+### Function intersection
+
+**Synopsis**: intersection(arg1,arg2) returns type **slist**
+
+ *arg1* : The name of the base list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+ *arg2* : The name of the intersected list variable, *in the range*
+[a-zA-Z0-9\_\$(){}\\[\\].:]+   
+
+Returns the unique elements in arg1 that are also in arg2.
+
+**Example**:  
+   
+
+```cf3
+undle agent test
+
+{
+  vars:
+      "a" slist => { 1,2,3,"x" };
+      "b" slist => { "x" };
+
+      "listname1" slist => { "a", "b" };
+      "listname2" slist => { "a", "b" };
+      "$(listname1)_str" string => join(",", $(listname1));
+
+      "int_$(listname1)_$(listname2)" slist => intersection($(listname1), $(listname2));
+      "int_$(listname1)_$(listname2)_str" string => join(",", "int_$(listname1)_$(listname2)");
+
+  reports:
+      "The intersection of list '$($(listname1)_str)' with '$($(listname2)_str)' is '$(int_$(listname1)_$(listname2)_str)'";
+}
+```
+
+**Notes**:  
+
+See also `difference`.

From 35f309a5b1776eea51a2acb6f47204839a1459c2 Mon Sep 17 00:00:00 2001
From: Ted Zlatanov <tzz@lifelogs.com>
Date: Wed, 29 May 2013 12:02:47 -0400
Subject: [PATCH 13/13] format() docs

---
 reference/functions/format.markdown | 57 +++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 reference/functions/format.markdown

diff --git a/reference/functions/format.markdown b/reference/functions/format.markdown
new file mode 100644
index 000000000..199dc2f8e
--- /dev/null
+++ b/reference/functions/format.markdown
@@ -0,0 +1,57 @@
+---
+layout: default
+title: format
+categories: [Reference, Functions, format]
+published: true
+alias: reference-functions-format.html
+tags: [reference, functions, format]
+---
+
+### Function format
+
+**Synopsis**: format(...) returns type **string**
+
+  
+
+Applies sprintf-style formatting to a given string, taking enough parameters to match the format.
+
+**Example**:  
+   
+
+```cf3
+body common control
+{
+      bundlesequence => { run };
+}
+
+bundle agent run
+{
+  vars:
+      "v" string => "2.5.6";
+      "vlist" slist => splitstring($(v), "\.", 3);
+      "padded" string => format("%04d%04d%04d", nth("vlist", 0), nth("vlist", 1), nth("vlist", 2));
+      "a" string => format("%10.10s", "x");
+      "b" string => format("%-10.10s", "x");
+      "c" string => format("%04d", 1);
+      "d" string => format("%07.2f", 1);
+      "e" string => format("hello %s, my IP is %s", $(sys.policy_hub), $(sys.ipv4));
+
+  reports:
+      "version $(v) => padded $(padded)";
+      "%10.10s on 'x' => '$(a)'";
+      "%-10.10s on 'x' => '$(b)'";
+      "%04d on '1' => '$(c)'";
+      "%07.2f on '1' => '$(d)'";
+      "hello my IP is... => '$(e)'";
+}
+```
+
+**Notes**:  
+   
+This function will fail if it doesn't have enough arguments; if any
+format *specifier* contains the *modifiers* `hLqjzt`; or if any format
+*specifier* is not one of `doxfs`.
+
+In other words, this function will format numbers (`o`, `x`, `d` and
+`f`) or strings (`s`) but not potentially dangerous things like
+individual characters or pointer offsets.