CLI API
~~~~~~~

1. Introduction

CLI API requires your script to communicate trough its stdio in a synched
manner. The protocol is a simple line based text protocol. Calls are 
nested with a "finish" command at the end of each nested session. Both
GPMI side and the script side should do the calls and parsing recursively
to avoid confusion. 

This document discusses how the final script is set up by GPMI and the
details of communication protocol.

2. Setup

File cli.conf has 3 columns: name of the language, a "before" script and
an "after" script. When GPMI loads CLI with a given language and script file
name, CLI will look up the requested language in this file. If found, it
will take the "before" script, append the user's script file and finally
append the "after" script. This way the user's script is wrapped in the
interface script.

The interface script should run a specific part of the user's script first
(the initial part) then it should inplement a main loop that calls the
recursive GPMI message parser (see later).

If the script can't create new functions on the fly, it also should
support a GPMI command wrapper (see later).


3. Communication protocol

Every message is a single line. The first word is the command.

3.1. GPMI -> script communication

Commands the script must implement:
 Event    - call the event handler for the event name given as the first word
            of the parameter. The rest of the parameters are the event
            parameters, they should be passed. When done, write
            "###GPMI_FIN### Event" to stdout.  Return.
 RunTick  - call the user script's runtick function, pass all parameters. When
            it returns, write "###GPMI_FIN### RunTick" to stdout. Return.
 RunData  - call the user script's rundata function, pass all parameters. When
            it returns, write "###GPMI_FIN### RunData" to stdout. Return.
 Rehash   - replace the current process with the new one given in the
            parameters, if possible. 
 Quit     - clean up, write "###GPMI_FIN### Quit" to stdout and exit.
 Nop      - do nothing. Return.
 Result   - store the parameters in a variable so that the caller in the
            user script can access it. Write "###GPMI_FIN### Result $result"
            to stdout ($result is the parameter list). Return in a way that
            the caller knows the last command parsed was a "Result".
 Fin      - return.

The above parser should be implemented in a function that is callable
from any other function. We will refer to this function as gpmi_parse().

gpmi_parse should read one line of the standard input, parse it and return.

3.2. script -> GPMI communication

The script can run GPMI commands by writing "###GPMI### command parameters"
to its stdout. After running a gpmi command, it must keep on calling
gpmi_parse() until gpmi_parse() returns in a way that indicates it parsed
a "Result". NOTE: as gpmi_parse() may run further script functions which
would then call further gpmi commands which would wait for subsequent 
results. Since we implemented the script in a recursive manner, this
won't cause a problem: the inner caller will receive the inner result.

3.3. other notes

If the languages allows, the wrapper script should be implemented so
that the user functions for RunTick, RunData and the initial part
could be omitted without warnings. If this is not possible, the documentation
should explicitly warn the user that he must implemnet these functions,
even if they will be empty.

There is a cli_print function ("###GPMI### cli_print") which can be
used to debug the script. When not disabled in the CLI module, it will
print debug messages among with the debug messages from the CLI module
itself so that it's easy to trace the run. The script should implement
a cli_print() and/or cli_dprint() function to make it easier using this
feature.

The main loop of the script should be infinite since the script exits
in the parser when processing a "Quit" or "Rehash" command.