Update documentation

refs #9105

doc/18-language-reference.md

@@ -813,6 +813,22 @@ The `continue` and `break` keywords can be used to control how the loop is execu
 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
 breaks out of the loop.
 
+## <a id="constructor"></a> Constructors
+
+In order to create a new value of a specific type constructor calls may be used.
+
+Example:
+
+    var pd = PerfdataValue()
+    pd.label = "test"
+    pd.value = 10
+
+You can also try to convert an existing value to another type by specifying it as an argument for the constructor call.
+
+Example:
+
+    var s = String(3) /* Sets s to "3". */
+
 ## <a id="throw"></a> Exceptions
 
 Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions
@@ -824,6 +840,12 @@ Example:
 
 There is currently no way for scripts to catch exceptions.
 
+## <a id="breakpoints"></a> Breakpoints
+
+The `debugger` keyword can be used to insert a breakpoint. It may be used at any place where an assignment would also be a valid expression.
+
+By default breakpoints have no effect unless Icinga is started with the `--script-debugger` command-line option. When the script debugger is enabled Icinga stops execution of the script when it encounters a breakpoint and spawns a console which lets the user inspect the current state of the execution environment.
+
 ## <a id="types"></a> Types
 
 All values have a static type. The `typeof` function can be used to determine the type of a value:

doc/19-library-reference.md

@@ -17,7 +17,7 @@ bool(value)                     | Converts the value to a bool.
 random()                        | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
 log(value)                      | Writes a message to the log. Non-string values are converted to a JSON string.
 log(severity, facility, value)  | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
-typeof(value)                   | Returns the type object for a value.
+typeof(value)                   | Returns the [Type](19-library-reference.md#type-type) object for a value.
 get_time()                      | Returns the current UNIX timestamp.
 parse_performance_data(pd)      | Parses a performance data string and returns an array describing the values.
 dirname(path)                   | Returns the directory portion of the specified path.
@@ -510,6 +510,8 @@ Returns a copy of the string in reverse order.
 
 ## <a id="object-type"></a> Object type
 
+This is the base type for all types in the Icinga application.
+
 ### <a id="object-clone"></a> Object#clone
 
 Signature:
@@ -520,9 +522,77 @@ Returns a copy of the object. Note that for object elements which are
 reference values (e.g. objects such as arrays or dictionaries) the entire
 object is recursively copied.
 
+## <a id="object-to-string"></a> Object#to_string
+
+Signature:
+
+    function to_string();
+
+Returns a string representation for the object. Unless overridden this returns a string
+of the format "Object of type '<typename>'" where <typename> is the name of the
+object's type.
+
+Example:
+
+    [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
+
+## <a id="object-type-field"></a> Object#type
+
+Signature:
+
+    String type;
+
+Returns the object's type name. This attribute is read-only.
+
+Example:
+
+    get_host("localhost").type /* Returns "Host" */
+
+## <a id="type-type"></a> Type type
+
+Inherits methods from the [Object type](19-library-reference.md#object-type).
+
+The `Type` type provides information about the underlying type of an object or scalar value.
+
+All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
+
+### <a id="type-base"></a> Type#base
+
+Signature:
+
+    Type base;
+
+Returns a reference to the type's base type. This attribute is read-only.
+
+Example:
+
+    Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
+
+### <a id="type-name"></a> Type#name
+
+Signature:
+
+    String name;
+
+Returns the name of the type.
+
+### <a id="type-prototype"></a> Type#prototype
+
+Signature:
+
+    Object prototype;
+
+Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists there. If it does that attribute's value is returned.
+
+The prototype functionality is used to implement methods.
+
+Example:
+
+    3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
+
 ## <a id="array-type"></a> Array type
 
-Inherits methods from the [object type](19-library-reference.md#object-type).
+Inherits methods from the [Object type](19-library-reference.md#object-type).
 
 ### <a id="array-add"></a> Array#add
 
@@ -616,7 +686,7 @@ Returns a new array with all elements of the current array in reverse order.
 
 ## <a id="dictionary-type"></a> Dictionary type
 
-Inherits methods from the [object type](19-library-reference.md#object-type).
+Inherits methods from the [Object type](19-library-reference.md#object-type).
 
 ### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone
 

doc/6-object-types.md

@@ -1468,15 +1468,7 @@ Configuration Attributes:
 
 # <a id="value-types"></a> Value Types
 
-In addition to [expressions](18-language-reference.md#expressions)
-used in object attribute assignments such as
-
-* [Numeric](18-language-reference.md#numeric-literals), [duration](18-language-reference.md#duration-literals), [string](18-language-reference.md#string-literals) and [boolean](18-language-reference.md#boolean-literals) literals
-* [Array](18-language-reference.md#array)
-* [Dictionary](18-language-reference.md#dictionary)
-
-Icinga 2 uses the following value types for runtime attributes
-exposed via the [Icinga 2 API](9-icinga2-api.md#icinga2-api).
+In addition to [configuration objects](6-object-types.md) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](9-icinga2-api.md#icinga2-api).
 
 ## <a id="value-types-checkresult"></a> CheckResult
 
@@ -1498,8 +1490,7 @@ exposed via the [Icinga 2 API](9-icinga2-api.md#icinga2-api).
 
 ## <a id="value-types-perfdatavalue"></a> PerfdataValue
 
-Icinga 2 parses performance data strings and exposes
-the object to external interfaces (e.g. [GraphiteWriter](6-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](9-icinga2-api.md#icinga2-api)).
+Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](6-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](9-icinga2-api.md#icinga2-api)).
 
   Name                      | Type          | Description
   --------------------------|---------------|-----------------

doc/9-icinga2-api.md

@@ -13,6 +13,12 @@ Make sure to restart Icinga 2 to enable the changes you just made:
 
     # service icinga2 restart
 
+If the prefer to set up the API manually you will have to perform the following steps:
+
+* Set up X.509 certificates for Icinga 2
+* Enable the `api` feature (`icinga2 feature enable api`)
+* Create an `ApiUser` object for authentication
+
 The next chapter provides a quick overview of how you can use the API.
 
 ## <a id="icinga2-api-introduction"></a> Introduction
@@ -39,9 +45,9 @@ traffic remains encrypted.
 
 By default the Icinga 2 API listens on port `5665` which is shared with
 the cluster stack. The port can be changed by setting the `bind_port` attribute
-in the [ApiListener](6-object-types.md#objecttype-apilistener)
-configuration object in the `/etc/icinga2/features-available/api.conf`
-file.
+for the [ApiListener](6-object-types.md#objecttype-apilistener)
+object in the `/etc/icinga2/features-available/api.conf`
+configuration file.
 
 Supported request methods:
 
@@ -58,25 +64,6 @@ All requests apart from `GET` require that the following `Accept` header is set:
 
 Each URL is prefixed with the API version (currently "/v1").
 
-### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
-
-The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
-including error codes.
-
-When an error occurs, the response body will contain additional information
-about the problem and its source.
-
-A status code between 200 and 299 generally means that the request was
-successful.
-
-Return codes within the 400 range indicate that there was a problem with the
-request. Either you did not authenticate correctly, you are missing the authorization
-for your requested action, the requested object does not exist or the request
-was malformed.
-
-A status in the range of 500 generally means that there was a server-side problem
-and Icinga 2 is unable to process your request.
-
 ### <a id="icinga2-api-responses"></a> Responses
 
 Successful requests will send back a response body containing a `results`
@@ -101,17 +88,24 @@ The output will be sent back as a JSON object:
 > should gracefully handle fields it is not familiar with, for example by
 > ignoring them.
 
-### <a id="icinga2-api-requests-method-override"></a> Request Method Override
+### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
 
-`GET` requests do not allow to send a request body. In case you cannot pass everything as URL parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override` header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
+The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
+including error codes.
 
-Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
+When an error occurs, the response body will contain additional information
+about the problem and its source.
 
-    $ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts'
+A status code between 200 and 299 generally means that the request was
+successful.
 
-Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
+Return codes within the 400 range indicate that there was a problem with the
+request. Either you did not authenticate correctly, you are missing the authorization
+for your requested action, the requested object does not exist or the request
+was malformed.
 
-    $ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: DELETE' -X POST 'https://localhost:5665/v1/objects/hosts/icinga.org'
+A status in the range of 500 generally means that there was a server-side problem
+and Icinga 2 is unable to process your request.
 
 ### <a id="icinga2-api-authentication"></a> Authentication
 
@@ -239,6 +233,18 @@ Here are the exact same query parameters as a JSON object:
 
     { "filter": "match(\"icinga2-node1.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] }
 
+### <a id="icinga2-api-requests-method-override"></a> Request Method Override
+
+`GET` requests do not allow to send a request body. In case you cannot pass everything as URL parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override` header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
+
+Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
+
+    $ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts'
+
+Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
+
+    $ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: DELETE' -X POST 'https://localhost:5665/v1/objects/hosts/icinga.org'
+
 ### <a id="icinga2-api-filters"></a> Filters
 
 #### <a id="icinga2-api-simple-filters"></a> Simple Filters