Language Reference

Agents following the introduced hierarchical state machine architecture can be completely described in the XABSL language.

The XABSL language design ensures:

• The scalability of agent behavior solutions. Agent behaviors are easy to extend.
• High validation and compile speed resulting in a short change-compile-test cycle.
• XML export allows the interoperability with existing XML editors and tools.

Modularity

An XABSL agent behavior specification is distributed over many files. This helps to keep an overview over larger agents and to work in parallel.

An XABSL agent behavior consists of the following files

• Symbol files contain the definitions of symbols. These symbols are used in the options.
• Basic behavior files contain prototypes for basic behaviors and their parameters. They are referenced from states which have a subsequent basic behavior.
• Option files contain a single option.
• "agents.xabsl" includes a list of all the option files. Agents and their root options can be defined here.

Common Language Elements

Almost all language elements can be provided with describing texts which are used in generated documentations. Such descriptions are defined in the following syntax:

<doc comment> ::=
  /** <describing text> */

In all XABSL files, comments, that are to be ignored during compilation, can be added using // for a single line of comment or by surrounding a code block with /* and */ for a comment block which can span multiple lines of code.

When symbols, options, or basic behaviors are referenced, a list of parameters can be specified. This is always done according to the following syntax:

<parameter list> ::=
  (
    <parameter> = <decimal expression> | <boolean expression> | <enumerated expression>
    { , <parameter> = <decimal expression> | <boolean expression> | <enumerated expression> }
  )

• "parameter": Name of a parameter. The value of the parameter is set to the value of the given expression. The expression must be of the same type as the parameter. If not all parameters of a symbol, option, or basic behavior are set, the executing engine sets the remaining parameter values to zero.

Symbol Definitions

All symbols that are used inside options have to be defined before in separate symbol definition files. For example the file "my_symbols.xabsl" can look like this:

/** My most used symbols */
namespace my_symbols("My Symbols") {

  /** A boolean symbol */
  bool input something_wrong;

  /** A decimal symbol */
  float input foo "mm";

  /** The absolute value of a number */
  float input abs (
    /** The value for that the absolute value shall be calculated */
    float value;
  );

  /** Pets */
  enumeration type_of_pet {
    dog,
    cat,
    guinea_pig
  };

  /** Which pet was seen by the robot */
  enum type_of_pet input type_of_recognized_pet;

  /** Operation modes */
  enumeration op_mode {
  	slow,
  	fast
  	very_fast
  };

  /** The mode how fast the robot shall act */
  enum op_mode output op_mode;

  /** The value of pi */
  float const pi = 3.14 "rad";

  ...
}

Syntax of a symbols definition file:

<symbol definition file> ::=
  { include "<include file>"; }
  [<doc comment>] namespace <id>("<title>")
  {
    { <enumeration> | <input symbol> | <output symbol> | <internal symbol> | <constant> }
  }

• "id": An id for the symbol collection. Must be identical to the file name without extension.
• "title": A title needed for documentation.
• "include file": Filename of a symbol definition file to be included. Included files could contain enumeration definitions referenced by symbol definitions.

There are five different symbol definitions allowed inside a symbols definition file:

<enumeration> ::=
  [<doc comment>] enum <name> [internal]
  {
    <enum-element>
    { , <enum-element> }
  };

<input symbol> ::=
  [<doc comment>]
  [float] [input] <name> [[<range>]] ["<measure>"] | bool [input] <name> | enum <enumeration> [input] <name>
  [
  (
    { <parameter> }
  )
  ]
  ;

<parameter> ::=
  [<doc comment>] [float] <name> [[<range>]] ["<measure>"] | bool <name> | enum <enumeration> <name>
  ;

<output symbol> ::=
  [<doc comment>]
  [float] output <name> [[<range>]] ["<measure>"] | bool output <name> | enum <enumeration> output <name>
  ;

<internal symbol> ::=
  [<doc comment>]
  [float] internal <name> [[<range>]] ["<measure>"] | bool internal <name> | enum <enumeration> internal <name>
  ;

<constant> ::=
  [<doc comment>] [float] const <name> = <value> ["<measure>"]
  ;

Basic Behavior Prototypes

For each basic behavior (they are written in C++), a prototype has to be declared. An example basic behavior file "my_basic_behaviors.xabsl" can look like this:

/** My common basic behaviors */
namespace my_basic_behaviors("My Basic Behaviors") {
  /** Lets the agent move to a point */
  behavior move_to {
    /** X of destination position */
    float x [-1000..1000] "mm";
    /** Y of destination position */
    float x [-1000..1000] "mm";
  };
}

Syntax of a basic behavior definition file:

<basic behavior definition file> ::=
  { include "<include file>"; }
  [<doc comment>] namespace <id>("<title>")
  {
    { <behavior> }
  }

• "id": An id for the basic behavior collection. Must be identical to the file name without extension.
• "title": A title needed for documentation.
• "include file": Filename of a symbol definition file to be included. Included files could contain enumeration definitions referenced by basic behavior parameter definitions.

The syntax of the definition of basic behavior prototypes is as follows:

<behavior> ::=
  [<doc comment>] behavior <name>
  [
  {
    { <parameter> }
  }
  ]
  ;

• "name": The name of the basic behavior.

<parameter> ::=
  [<doc comment>]
  [float] <name> [[<range>]] ["<measure>"] | bool <name> | enum <enumeration> <name>
  ;

• "name": The name of the parameter.
• "range": The valid range of the decimal parameter value. Used for documentation.
• "measure": The measure of the decimal parameter value. Used for documentation.
• "enumeration": In case the type of the parameter is enumerated, the name of the corresponding enumeration has to be specified.

Options

Each option has to be defined in a seperate file, e.g. "Options/foo.xabsl":

include "../my_symbols.xabsl"
include "../my_basic_behaviors.xabsl"

/** Some option */
option foo {
  initial state first_state {
    ...
  }

  state second_state {
    ...
  }
}

An option file must have the following syntax:

<option file> ::=
  { include "<include file>"; }
  [<doc comment>] option <name>
  {
    { <parameter> }
    [ <common decision tree> ]
    <state>
    { <state> }
  }

• "name": The name of the option. Must be identical to the file name without extension.
• "include file": Filename of an included file. Included files can contain required symbol, basic behavior, or option definitions.

Options can have parameters which are defined in the same way as input symbol parameters. The name of an option parameter has to start with @ in order to be distinguished from an input symbol:

<parameter> ::=
  [<doc comment>]
  [float] @<name> [[<range>]] ["<measure>"] | bool @<name> | enum <enumeration> @<name>
  ;

• "name": The name of the option parameter without the leading @.
• "range": The valid range of the decimal parameter value. Used for documentation.
• "measure": The measure of the decimal parameter value. Used for documentation.
• "enumeration": In case the type of the parameter is enumerated, the name of the corresponding enumeration has to be specified.

At the start of an option definition optionally a common decision tree can be defined with the following syntax:

<common decision tree> ::=
  common decision
  {
    [<doc comment>] if ( <boolean expression> ) <decision tree>
    {
      [<doc comment>] else   [<doc comment>] if ( <boolean expression> )   <decision tree> |
      [<doc comment>] else { [<doc comment>] if ( <boolean expression> ) } <decision tree>
    }
  }

If there are transitions with the same conditions in each state, these conditions can be put into this common decision tree. It is carried out before the decision tree of the active state. If no condition of the common decision tree evaluates true, the decision tree of the active state is carried out. That is also the reason why there must be no else statement which is not followed by another if statement.

If the common decision tree uses expressions that are specific for a state (state_time, action_done), these expressions refer to the state that is currently active.

The elements boolean expression and decision tree are the same as in the normal decision tree of a state, which is explained later in this document.

Besides and after the optional common decision tree each option has to have at least one state definition, which is described in the next section.

States

The state definition represents a single state of an option's state machine, as shown in this example:

initial target state first_state {
  decision {
    if (foo < 14 )
      goto second_state;
    else
      goto first_state;
  }
  action {
    move_to(x = 42);
    op_mode = fast;
  }
}

It has the following syntax:

<state> ::=
  [initial] [target] state <name> {
    decision
    {
      [ else ] <decision tree>
    }
    action
    {
      { <action definition> }
    }
  }

• If "initial" is specified, the state is marked as the initial state of the option. This must be set for exactly one state in the option.
• If "target" is specified, this state is marked as a target state. In an option containing a state with this option as subsequent behavior, it can be queried if the subsequent option reached this marked target state.
• "name": The name of the state.
• The "decision tree" defines the transitions of the state. It is described in the next section. The leading else before the decision tree must be specified if and only if the option has a common decision tree. This reflects the fact, that when the option has a common decision tree, the decision tree of a state is only executed when no transition was selected by the common decision tree.
• An "action definition" defines an action to be executed when the state is active. Each state can have any number of action definitions.

Decision Trees

Each state has a decision tree. The task of this decision tree is to determine a transition to another state depending on the input symbols. The syntax of a decision tree is as follows:

<decision tree> ::=
    { <decision tree> }
  |
    [<doc comment>] if ( <boolean expression> ) <decision tree> [<doc comment>] else <decision tree>
  |
    goto <state>;
  |
    stay;

A decision tree contains either an if/else block or a transition to a state.

The if/else element consists of a boolean expression and two decision trees. The first one is executed if the expression evaluates to true, the second one otherwise. This recursive definition allows for complex nested expressions.

• "goto state;": A transition to the specified state.
• "stay;": A transition to the current state. When this transition is executed, the active state of the option remains unchanged in the current execution cycle.

Action definitions

Each state has a number of action definitions. These definitions specify which actions are to be executed when a state is active. The syntax is as follows:

<action definition> ::=
    <output symbol> | <internal symbol>
    =
    <decimal expression> | <boolean expression>    | <enumerated expression>
    ;
  |
    <option>  [ <parameter list> ] ;
  |
    <basic behavior> [ <parameter list> ] ;

• "output"/"internal symbol": Name of an output or internal symbol to be set in this state. When the state is active, the value of the symbol is set to the value of the given expression. The expression must be of the same type as the symbol. It may happen that an option which becomes activated lower in the option graph overwrites the symbol value.
• "option"/"basic behavior: Name of an subsequent option or basic behavior to be executed when this state is active.

Boolean Expressions

A boolean expression can be of the following syntax:

<boolean expression> ::=
    ( <boolean expression> )
  |
    !<boolean expression>
  |
    <boolean expression> && <boolean expression>
  |
    <boolean expression> || <boolean expression>
  |
    <qualified enumerated expression> == <enumerated expression>
  |
    <decimal expression> == <decimal expression>
  |
    <qualified enumerated expression> != <enumerated expression>
  |
    <decimal expression> != <decimal expression>
  |
    <decimal expression> < <decimal expression>
  |
    <decimal expression> <= <decimal expression>
  |
    <decimal expression> > <decimal expression>
  |
    <decimal expression> >= <decimal expression>
  |
    <boolean input symbol> [ <parameter list> ]
  |
    <boolean output symbol>
  |
    <boolean internal symbol>
  |
    @<boolean option parameter>
  |
    true
  |
    false
  |
    action_done

• "!": Boolean not operator. Inverts a boolean expression.
• "&&" and "||": Boolean and/or operator. Combines two boolean expressions.
• "==" and "!=": Compares two decimal or enumerated expressions. Please note that in case of enumerated the expression the left-hand side expression must be qualified, i.e. it must specify the enumeration. Enumerated expressions are described below in this document.
• "<", ">", "<=", ">=": Compares two decimal expressions.
• "boolean input symbol": References a boolean input symbol. Optionally parameters can be specified.
• "boolean output symbol": References a boolean output symbol. This queries the value set to the output symbol previously.
• "boolean internal symbol": References a boolean internal symbol. This queries the value set to the internal symbol previously.
• "boolean option parameter": References a boolean option parameter.
• "action_done": This expression becomes true, when
  • the current state has an subsequent option, and
  • the active state of the subsequent option is marked as a target state.
  Otherwise this statement is false.

Decimal Expressions

A decimal expression can be used inside some boolean expressions, for parameterizing symbols, options, and basic behaviors, and for the assignment of decimal output symbols. It has the following syntax:

<decimal expression> ::=
    ( <decimal expression> )
  |
    <decimal expression> + <decimal expression>
  |
    <decimal expression> - <decimal expression>
  |
    <decimal expression> * <decimal expression>
  |
    <decimal expression> / <decimal expression>
  |
    <decimal expression> % <decimal expression>
  |
    <boolean expression> ? <decimal expression> : <decimal expression>
  |
    <decimal input symbol> [ <parameter list> ]
  |
    <decimal output symbol>
  |
    <decimal internal symbol>
  |
    @<decimal option parameter>
  |
    <constant>
  |
    <decimal value>
  |
    state_time
  |
    option_time

• "+","-","*","/" and "%": Arithmetic +, -, *, / and % operators.
• "boolean expression"?"decimal expression":"decimal expression": Defines a conditional expression, which works such as an ANSI C question mark operator. If the boolean expression is true, the left-hand side decimal expression, otherwise the right-hand side decimal expression, is returned.
• "decimal input symbol": References a decimal input symbol. Optionally parameters can be specified.
• "decimal output symbol": References a decimal output symbol. This queries the value set to the output symbol previously.
• "decimal internal symbol": References a decimal internal symbol. This queries the value set to the internal symbol previously.
• "decimal option parameter": References a decimal option parameter.
• "constant": References a constant defined in a symbol definition file.
• "decimal value": A decimal value, e.g. "3.14".
• "state_time": This expression returns the duration in seconds for which the current state of the option is active. Whenever a state change occurs this time is set to zero.
• "option_time": This expression returns the duration in seconds for which the current option is active.

Enumerated Expressions

An enumerated expression can be used inside some boolean expressions, for parameterizing symbols, options, and basic behaviors, and for the assignment of enumerated output symbols. For the left-hand side of the comparison of two enumerated expressions in a boolean expression a special enumerated expression, a so-called qualified enumerated expression, is required which implicitly defines its associated enumeration. Particularly a reference to an enumeration element cannot be used, since enumeration elements are not necessarily unique. E.g. the boolean expression "dog == type_of_recognized_pet" would be illegal, "type_of_recognized_pet == dog" must be used instead.

Enumerated expressions follow this syntax:

<qualified enumerated expression> ::=
    ( <qualified enumerated expression> )
  |
    <enumerated input symbol> [ <parameter list> ]
  |
    <enumerated output symbol>
  |
    <enumerated internal symbol>
  |
    @<enumerated option parameter>
  |
    <boolean expression> ? <qualified enumerated expression> : <qualified enumerated expression>

<enumerated expression> ::=
    <qualified enumerated expression>
  |
    <boolean expression> ? <enumerated expression> : <enumerated expression>
  |
    <enumeration element>

• "enumerated input symbol": References an enumerated input symbol. Optionally parameters can be specified.
• "enumerated output symbol": References an enumerated output symbol. This queries the value set to the output symbol previously.
• "enumerated internal symbol": References an enumerated internal symbol. This queries the value set to the internal symbol previously.
• "enumerated option parameter": References an enumerated option parameter.
• "boolean expression"?"enumerated expression":"enumerated expression": Defines a conditional expression, which works such as an ANSI C question mark operator. If the boolean expression is true, the left-hand side enumerated expression, otherwise the right-hand side enumerated expression, is returned.
• "enumeration element": References an enumeration element.

Agents

The file "agents.xabsl" is the root document of an XABSL behavior specification. It includes all the options and defines agents. An example "agents.xabsl" file may look like this:

/***
  Title: My XABSL behavior application
  Platform: My robot/agent platform.
  Software-Environment: My software platform
*/

include "Options/foo.xabsl";
include "Options/bla.xabsl";

/** The default agent */
agent default_agent("Default", foo);

/** A test environment for the option bla */
agent test_behavior("Test", bla);

The "agents.xabsl" has the following syntax:

<agents definition file> ::=
  /***
  Title: <title>
  Platform: <platform>
  Software-Environment: <software-environment>
  */
  { include "<include file>"; }
  [<doc comment>] agent <id>("<agent-title>", <root-option>);
  { [<doc comment>] agent <id>("<agent-title>", <root-option>); }

The title, platform, and software-environment elements are only used for generating the HTML documentation.

In an XABSL behavior, the option graph doesn't need to be completely connected. So it is difficult to determine a single root option of the graph. Instead a sub-graph that is spanned by an option and all it's subsequent options and basic behaviors can be declared as an agent. So an agent defines a starting point into the option graph.

Included files must contain option definitions for options to be used as agent root options.

There has to be at least one agent element inside the agents definition file. It contains the following elements:

• "id": The id of the agent. This id must be used to select that agent at the engine.
• "agent-title": A title needed for the documentation.
• "root-option": The name of the root option of the agent.