SITPLUS script syntax
=====================
Cesar Mauri <cesar@crea-si.com>


This document the syntax of the scripting language used by the SITPLUS 
project. These scripts usually have the .sp and .sps extensions.

Comments
--------

Line comments start with '#'. 

Blank lines are ignored.

Commands
--------

*`type <id>`*::
	Sets the name which identifies the component class that is being 
	defined. Used when creating (see create below) instances of this component.

*`name <name>`*::

	Name given to the component. Must appear at the very beginning	
	of the script, otherwise parsing will fail. It is usually used as a title 	
	for GUI elements.
	
*`args <arguments_declaration>`*::
	Allows to declare the formal parameters that the component expects. Each
	parameter name must begin with a dash `-`. Once declared an argument
	can be used inside the script by just enclosing its name between `$` 
	symbols. That is, if the argument is called `-v`, you can	instantiate it by
	writing `$-v$`. When an argument is instantiated it is	simply replaced by
	its value.
	
	Parameters are passed when the component is created (see `create` command	below) and all expected arguments are mandatory.;;
	
	Apart from the formal parameters, the parameter `$SP_DATA_DIR$` is always 	available an is replaced by the absolute path in which data files are	supposed to be.;;

	See `sp/examples/arguments` for more information and examples.;;


*`create <component type> <name> [args]`*::
	Creates a new component of a given type with the given name.
	The type can refer a core registered type, a subcomponent or an imported
	component. The name must be unique within the same scope.
	args are optional and component dependent.

*`connect <src component> <src_pin> <dst component> <dst_pin>`*::
	Connects src_pin of src component to dst_pin of dst component.

*`export_ipin <component> <pin name> [<new name> [<new type>]]`*

*`export_opin <component> <pin name> [<new name> [<new type>]]`*::
	Registers the input/output pin of a certain component as if where part of
	this component and optionally rename it. NOTE: renaming the pin 
	actually means that	the pin name also changes for the original component.
	If parameter new type is passed tries to change the type of the pin. 
	The new type must be only of the types registered in the core.
	Note that changing the type is only possible for type "any" pins.

	As a rule of thumb always put the exportation statement at the end of the script or the subcomponent.;;

*`import <file-name>`*::
	Imports a component which is defined in an external file.

Defining subcomponents
----------------------

Subcomponents allow to define new types of components which are 
composed of other components. Use
	
	`subcomponent`

keyword to begin a subcomponent definition and end it with

	`subcomponent_end`

GUI layout
----------

Each component inside a graph could provide a GUI panel. The layout definition
allows to arrange those panels to build a consistent user interface.

GUI layout commands
~~~~~~~~~~~~~~~~~~~

The full layout definition must be enclosed between the commands
`begin_gui_layout` and `end_gui_layout`.
	
The layout definition is composed of layout managers and components:

*`layout_begin <arg>`*::
	Begins a layout manager. `arg` can be:
	
		- `hbox [name]`
			Horizontal box layout, if name is provided, a surrounding 
			box with the name is painted around the enclosed GUI elements.
		- `vbox [name]` 
			Vertical box layout.
		- `book` 
			Notebook layout.
		- `book_page` 
			Notebook layout page.
		- `collapsible` 
			Panel which can be shown/hidden by pressing a button.

*`layout_end`*::
	Ends a layout manager. Each layout_begin must have its corresponding
	`layout_end`.

*`component <name>`*::
	Places a component panel.
	
See `sp/` directory for more information and examples.
