From 50b37d4a27d3295a29afca2286f1a5a086142cec Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 11:49:46 +0200 Subject: Adding upstream version 3.2.1+dfsg. Signed-off-by: Daniel Baumann --- doc/antora/modules/unlang/pages/type/index.adoc | 117 ++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 doc/antora/modules/unlang/pages/type/index.adoc (limited to 'doc/antora/modules/unlang/pages/type/index.adoc') diff --git a/doc/antora/modules/unlang/pages/type/index.adoc b/doc/antora/modules/unlang/pages/type/index.adoc new file mode 100644 index 0000000..7d0d70f --- /dev/null +++ b/doc/antora/modules/unlang/pages/type/index.adoc @@ -0,0 +1,117 @@ += Data Types + +Unlang supports a number of data types. These data types are used in +conditional expressions or when assigning a value to an attribute. + +== Using Data Types + +The server support a wide range of data types, as given in the +xref:unlang/type/all_types.adoc[list of data types] page. The choice +of which data type applies is determined by the context in which that +data type is used. This context is usually taken from an attribute +which is being assigned a value. + +The `unlang` interpreter uses pre-defined attributes which are defined +in dictionaries. The dictionaries define both a name, and a data type +for the attributes. In the interpreter, then, attributes can be +assigned a value or compared to a value, without specifying the data +type. The interpreter knows how to parse the value by using the data +type assigned to the attribute. + +The result is that in most cases, it is not necessary to know the name +of the data types. It is possible to write values in the format you +expect, and he server will do "the right thing" when interpreting the +values. + +.Attributes with Different Data Types +[source,unlang] +---- +Framed-IP-Address = 192.0.2.1 +Framed-IPv6-Address = 2001:db8:: +Reply-Message = "This is a reply" +Port-Limit = 5 +Boolean = true +Octets-Thing = 0xabcdef0102030405 +MAC-Address = 00:01:02:03:04:05 +---- + +== Parsing Data Types + +The interpreter is flexible when parsing data types. So long as the +value can be parsed as the given data type without error, the value +will be accepted. + +For example, a particular attribute may be of data type `ipaddr` in +order to store IPv4 addresses. The interpreter will then accept the +following strings as valid IPv4 addresses: + +`192.168.0.2`:: xref:type/string/unquoted.adoc[Unquoted text], interpreted as the data type + +`'192.168.0.2'`:: xref:type/string/single.adoc[Single-quoted string], the contents of the string are parsed as the data type. ++ +The single-quoted string form is most useful when the data type +contains special characters that may otherwise confuse the parser. + +`"192.168.0.2"`:: xref:type/string/double.adoc[Double-quoted string]. ++ +The contents of the string are dynamically expanded as described in +the xref:unlang/xlat/index.adoc[dynamic expansion] page. The +resulting output is then interpreted as the given data type. + +`{backtick}/bin/echo 192.168.0.2{backtick}`:: xref:type/string/backticks.adoc[backtick-quoted string]. +Run a script, and parse the resulting string as the data type. + +Similar processing rules are applied when parsing assignments and +comparisons, for all attributes and data types. + +=== Casting Data Types + +In some cases, it is necessary to parse values which do not refer to +attributes. This situation usually occurs when two values need to be +compared, as in the following example: + +[source,unlang] +---- +if ("%{sql:SELECT ipaddress FROM table WHERE user=%{User-Name}}" == 192.0.2.1) } + .... +} +---- + +Since there is no attribute on either side of the `==` operator, the +interpreter has no way of knowing that the string `192.0.2.1` is an IP +address. There is unfortunately no way of automatically parsing +strings in order to determine the data type to use. Any such +automatic parsing would work most of the time, but it would have +error cases where the parsing was incorrect. + +The solution is to resolve these ambiguities by allowing the values to +be cast to a particular type. Casting a value to a type tells the +interpreter how that value should be parsed. Casting is done by +prefixing a value with the type name, surrounded by angle brackets; +`<...>`. + +.Syntax +---- +<...>value +---- + +We can add a cast to the above example, as follows: + +[source,unlang] +---- +if ("%{sql:SELECT ipaddress FROM table WHERE user=%{User-Name}}" == 192.0.2.1) } + .... +} +---- + +In this example, we prefix the IP address with the string ``. +The interpreter then knows that the value `192.0.2.` should be +interpreted as the data type `ipaddr`, and not as the literal string +`"192.0.2."`. + +For a full list of data types which can be used in a cast, please see +the xref:unlang/type/all_types.adoc[list of data types] page, and the +"Basic Type Types" section. + +// Copyright (C) 2020 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Development of this documentation was sponsored by Network RADIUS SAS. -- cgit v1.2.3