Edit of Documentation/Tutorial - Writing Agent Script

''Table of Contents''
#contents

* Overview [#j92e773b]
An ''agent script'' is a script stored in a file named *.agent which can include the other agent scripts.

The agent script system is under-construction; which will be updated frequently.

* Grammar [#i81f9e14]
In the following guide, a CAPITAL WORD denotes a parameter, and the others are keywords.

** Comment [#e3443b55]
Characters followed by "//" are parsed as a comment.
#codeh(cpp){{
// THIS IS A COMMENT
module MAVFTable avf_table  // THIS IS A COMMENT
}}

** Modular Manipulation [#ja7d2616]
In order to instantiate a module, write as follows:
#codeh(cpp){{
module MODULE_TYPE INSTANCE_NAME
}}
- MODULE_TYPE : Name of module type.
- INSTANCE_NAME : Identifier of instance.

In order to connect two ports, write as follows:
#codeh(cpp){{
connect  FROM_MODULE.FROM_PORT , TO_MODULE.TO_PORT
}}
- FROM_MODULE : Departing module.
- FROM_PORT : Departing port (a signal port or an in port).
- TO_MODULE : Destination module.
- TO_PORT : Destination port (a slot port or an out port).

A module can be removed as follows:
#codeh(cpp){{
remove INSTANCE_NAME
}}
- INSTANCE_NAME : Identifier of the module.

In order to disconnect the ports, write as follows:
#codeh(cpp){{
disconnect  FROM_MODULE.FROM_PORT , TO_MODULE.TO_PORT
}}
- FROM_MODULE : Departing module.
- FROM_PORT : Departing port (a signal port or an in port).
- TO_MODULE : Destination module.
- TO_PORT : Destination port (a slot port or an out port).

** Parameter Manipulation [#Parameter_Manipulation]
In order to assign into parameters in a configuration box of a module, write as follows:
#codeh(cpp){{
MODULE_ID.config ={
    ASSIGN_STATEMENTS
  }
}}
- MODULE_ID : Identifier of the module.
- ASSIGN_STATEMENTS : Refer to [[#Assign_Sentence]].

Similarly, assign into a memory box by:
#codeh(cpp){{
MODULE_ID.memory ={
    ASSIGN_STATEMENTS
  }
}}
- MODULE_ID : Identifier of the module.
- ASSIGN_STATEMENTS : Refer to [[#Assign_Sentence]].

If we omit MODULE_ID., we can assign into parameters of the configuration/memory box of the context module (in global, the context module is the agent class).
#codeh(cpp){{
config ={
    ASSIGN_STATEMENTS
  }
memory ={
    ASSIGN_STATEMENTS
  }
}}
** Composite Module [#a90c0a0c]
We can define a ''composite module'' as a new module type, which can include any number of the other modules, and can be used like a module written in C++.
We refer to an included module as a ''sub-module''.
The composite module is defined as follows:
#codeh(cpp){{
composite CMODULE_NAME
{
  STATEMENTS_IN_CMP
}
}}
- CMODULE_NAME : Identifier of the composite module.
- STATEMENTS_IN_CMP : module, remove, connect, disconnect, inherit, inherit_prv, export-statements, and STATEMENTS_IN_EDIT are available.

Note that, a composite module can include the other composite modules.

In default, a new composite module has no ports, no configuration parameters, and no memory parameters.  These are added by ''exporting'' those of the sub-modules.
#codeh(cpp){{
export MODULE_ID.config.PARAM_ID as_is
export MODULE_ID.config.PARAM_ID as EXPORT_NAME
export MODULE_ID.memory.PARAM_ID as_is
export MODULE_ID.memory.PARAM_ID as EXPORT_NAME
export MODULE_ID.PORT_ID as_is
export MODULE_ID.PORT_ID as EXPORT_NAME
}}
The export with .config or .memory exports the configuration or the memory parameter of the sub-module; otherwise, it exports the port.  By specifying as_is, the same identifier of parameter or port is used; using as+EXPORT_NAME, we can specify the exporting name.
- MODULE_ID : Identifier of the sub-module.
- PARAM_ID : Identifier of the parameter.
- PORT_ID : Identifier of the port.
- EXPORT_NAME : Exported with this name.

If a parameter of a sub-module is not exported, the only way to modify the parameter from outside is using the edit statement:
#codeh(cpp){{
edit CMODULE_ID
{
  STATEMENTS_IN_EDIT
}
}}
- CMODULE_ID : Identifier of the composite-module instance.
- STATEMENTS_IN_EDIT : include, include_once, dump1, dump2, print, destroy, [[#Control_Statement]], [[#Parameter_Manipulation]], and [[#Function_Call]] are available.

A composite module can be inherited from the other composite module(s).
#codeh(cpp){{
inherit CMODULE_NAME
inherit_prv CMODULE_NAME
}}
Using inherit keeps the export configuration of the parent module, while using inherit_prv removes the every export configuration.
- CMODULE_NAME : Name of the parent composite module (not an instance identifier).

** Function Definition [#r26a9e51]
A function can be defined as follows:
#codeh(cpp){{
def FUNCTION_NAME(PARAMETER_LIST)
{
  STATEMENTS_IN_DEF
}
}}
- FUNCTION_NAME : Name of the function.
- PARAMETER_LIST : List of the parameters.
- STATEMENTS_IN_DEF : composite, linclude, return, and STATEMENTS_IN_CMP are available.

A function can return a value as follows:
#codeh(cpp){{
return EXPRESSION_BLOCK
}}
- EXPRESSION_BLOCK : Refer to [[#Assign_Sentence]].

** Function Call [#Function_Call]
Defined function can be called as:
#codeh(cpp){{
FUNCTION_NAME(ARGUMENT_LIST)
}}
FUNCTION_NAME : Name of the function.
ARGUMENT_LIST : List of arguments.  Each argument is a EXPRESSION_BLOCK (refer to [[#Assign_Sentence]]).

** Control Statement [#Control_Statement]
In the current implementation, only the ''if'' statement is defined.
#codeh(cpp){{
if(EXPRESSION_BLOCK)
{
  STATEMENTS_TRUE
}
else
{
  STATEMENTS_FALSE
}
}}
- EXPRESSION_BLOCK : Condition; if true, STATEMENTS_TRUE are executed, otherwise, STATEMENTS_FALSE are executed.

** System Operation [#o690664e]
statement_include
statement_include_once
statement_linclude
statement_dump1
statement_dump2
statement_print
statement_destroy
#codeh(cpp){{
}}

** Assign Sentence [#Assign_Sentence]
The following statements are available in ASSIGN_STATEMENTS.

statement_print
statement_starting_with_identifier
statement_primitive_assign
statement_composite_assign
statement_elemental_assign
statement_elemental_primitive_assign
statement_elemental_composite_assign
statement_push
statement_push_primitive
statement_push_composite
statement_fill_all
statement_fill_all_primitive
statement_fill_all_composite
statement_function_call
statement_unexpected
#codeh(cpp){{
}}

EXPRESSION_BLOCK

Do not change timestamp