# -*- text -*-
#
#  $Id$

#
#  This module is useful only for 'xlat'.
#  To use it, add it to the raddb/mods-enabled/ directory.
#
#  Two xlat functions are provided by this module:
#    - unpack
#    - substring
#
#  Both are for use on the right-hand side of a variable assignment.
#
#  unpack
#  ======
#
#  ... = "%{unpack:data 1 integer}"
#
#  The arguments are three fields:
#
#	data
#		Either &Attribute-Name
#		the name of the attribute to unpack.
#		MUST be a "string" or "octets" type.
#
#		or 0xabcdef
#		e.g. hex data.
#
#	1
#		The offset into the string from which
#		it starts unpacking.  The offset starts
#		at zero, for the first attribute.
#
#	integer
#		the data type to unpack at that offset.
#		e.g. integer, ipaddr, byte, short, etc.
#
#  e.g. if we have Class = 0x0000000102030405, then
#
#	%{unpack:&Class 4 short}
#
#  will unpack octets 4 and 5 as a "short", which has
#  value 0x0304.
#
#  This module is used when vendors put multiple fields
#  into one attribute of type "octets".
#
#  The module can also be used to unpack substrings, by specifing a
#  data type of "string(len)" or "octets(len)".  Where "len" is an
#  actual number.  For example:
#
#	%{unpack:&User-Name 1 string(2)}
#
#  When given a User-Name of "hello", it will start taking the
#  substring at offset 1 (i.e. "e"), and it will take two characters
#  from that offset, i.e. "el".
#
#  As a special case, you can unpack an entire string by specifying
#  the offset, and nothing for the length:
#
#	%{unpack:&User-Name 1 string()}
#
#  When "octets(len)" is used, the output is printed as hex.  e.g. for
#  the above example with Class:
#
#	%{unpack:&Class 4 octets(4)}
#
#  Will return the hex string "02030405"
#
#
#  substring
#  =========
#
#  substring will return a substring of a string or attribute using
#  the syntax
#
#	%{substring:data start len}
#
#	data
#		Either an attribute name or string data.  String data
#		can have leading or trailing spaces.  Only a single
#		space before "start" is taken as the separator.
#
#  	start
#		the zero based offset for the start of the substring.
#		A negative value will count in from the end of the
#		string.
#
#	len
#		the number of characters to return.  A Negative value
#		will remove that number of characters from the end.
#		If len is more than the available number of characters
#		then only the available number will be returned.
#
#  Examples:
#
#	"%{substring:foobar 2 3}" == "oba"
#	"%{substring:foobar -3 2}" == "ba"
#	"%{substring:foobar 1 -1}" == "ooba"
#	if User-Name is "foobar" "%{substring:&User-Name 1 -2}" == "oob"
#

unpack {
}