From bcbc3ceff7b40cbee5c30403b68dd1c8727372ac Mon Sep 17 00:00:00 2001
From: Gunnar Beutner <gunnar.beutner@netways.de>
Date: Wed, 19 Mar 2014 20:00:05 +0100
Subject: [PATCH] Update documentation.

Refs #5789
---
 doc/1-about.md                  |  2 +-
 doc/4.1-configuration-syntax.md | 90 +++++++++++++++++++++------------
 2 files changed, 59 insertions(+), 33 deletions(-)

diff --git a/doc/1-about.md b/doc/1-about.md
index cf04f6156..067ba11e1 100644
--- a/doc/1-about.md
+++ b/doc/1-about.md
@@ -39,7 +39,7 @@ the support overview page at [https://support.icinga.org].
 
 #### Changes
 * {host,service}_dependencies attributes have been changed to [Dependency](#objecttype-dependency)
-objects supporting new attributes: `disable_checks`, 'disable_notifications`, `state_filter`,
+objects supporting new attributes: `disable_checks`, `disable_notifications`, `state_filter`,
 `period`. For better readability, there is `parent_service` and `child_service` for example.
 
 > **Note**
diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md
index cd0b33136..56823b111 100644
--- a/doc/4.1-configuration-syntax.md
+++ b/doc/4.1-configuration-syntax.md
@@ -27,6 +27,11 @@ Each object is uniquely identified by its type (`Host`) and name
 property declarations. The following data types are available for
 property values:
 
+### Expressions
+
+The following expressions can be used in the right-hand side of dictionary
+values.
+
 #### <a id="numeric-literals"></a> Numeric Literals
 
 A floating-point number.
@@ -140,10 +145,61 @@ Example:
 > An array may simultaneously contain values of different types, such as
 > strings and numbers.
 
-### <a id="operators"></a> Operators
+#### <a id="constant-expressions"></a> Operators
+
+The following operators are supported in expressions:
+
+Operator | Examples (Result)                             | Description
+---------|-----------------------------------------------|--------------------------------
+!, ~     | ~true (false)                                 | Bitwise negation of the operand
++        | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
+-        | 3 - 1 (2)                                     | Subtracts two numbers
+*        | 5m * 10 (3000)                                | Multiplies two numbers
+/        | 5m / 5 (60)                                   | Divides two numbers
+&        | 7 & 3 (3)                                     | Binary AND
+\|       | 2 \| 3 (3)                                    | Binary OR
+<        | 3 < 5 (true)                                  | Less than
+>        | 3 > 5 (false)                                 | Greater than
+<=       | 3 <= 3 (true)                                 | Less than or equal
+>=       | 3 >= 3 (true)                                 | Greater than or equal
+<<       | 4 << 8 (1024)                                 | Left shift
+>>       | 1024 >> 4 (64)                                | Right shift
+==       | "hello" == "hello" (true), 3 == 5 (false)     | Equal to
+!=       | "hello" != "world" (true), 3 != 3 (false)     | Not equal to
+in       | "foo" in [ "foo", "bar" ] (true)              | Element contained in array
+!in      | "foo" !in [ "bar", "baz" ] (true)             | Element not contained in array
+()       | (3 + 3) * 5                                   | Groups sub-expressions
+
+Constants may be used in constant expressions:
+
+    const MyCheckInterval = 10m
+
+    ...
+
+    {
+      check_interval = MyCheckInterval / 2.5
+    }
+
+#### Function Calls
+
+Functions can be called using the `()` operator:
+
+    const MyGroups = [ "test1", "test" ]
+
+    {
+      check_interval = len(MyGroups) * 1m
+    }
+
+Function             | Description
+---------------------|-----------------------
+regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
+match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
+len(value)           | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
+
+### <a id="operators"></a> Dictionary Operators
 
 In addition to the `=` operator shown above a number of other operators
-to manipulate configuration objects are supported. Here's a list of all
+to manipulate dictionary elements are supported. Here's a list of all
 available operators:
 
 #### <a id="operator-assignment"></a> Operator =
@@ -312,36 +368,6 @@ Constants cannot be changed once they are set.
 > in order to provide compatibility with older versions. Their use is
 > deprecated.
 
-### <a id="constant-expressions"></a> Constant Expressions
-
-Simple calculations can be performed using the constant expression syntax:
-
-    {
-      check_interval = 30 + 60
-    }
-
-Valid operators include ~, !, +, -, *, /, >, >=, <, <=, ==,  !=, in and !in. The default precedence rules can be
-overridden by grouping expressions using parentheses:
-
-    {
-      check_interval = (30 + 60) / 2
-    }
-
-Global constants may be used in constant expressions.
-
-    var MyCheckInterval = 10m
-
-    ...
-
-    {
-      check_interval = MyCheckInterval / 2.5
-    }
-
-> **Note**
->
-> Constant expressions in attributes and variable definitions are evaluated as
-> soon as they're encountered in the configuration file.
-
 ### <a id="apply"></a> Apply
 
 The `apply` keyword can be used to associate a template with another group of