specification files for plugins

I just want to put some documentation about the current state of the
pluc development here.

The plugin compiler is not yet finished, but
the most important functionality is already done.


0. introduction
----------------

The specification of a plugin consists of several files.
The files all have a similar syntax.
They consist of blocks that are enclosed in curly braces.
All literals must be enclosed in quotation marks.
Literals can span multiple lines, whitespace is preserved.

I'm now going to describe all files.

1. plugin spec
---------------

The "top-level" file is the plugin spec (ends with .psp).
The format is really simple, here an example:

<<
 > cat number.psp

  plugin number
  {
    description = "Some stuff"
  }

  files
  {
    "number.lsp"
    "kalkulon.usp"
  }
 >>

This file lists all units and links that are defined in the plugin (in 
the "files" block).


2. unit spec
-------------

The format of a unit spec (.usp) file is again best shown with an
example:

<<
 > cat kalkulon.usp
  unit kalkulon
  {
    author        = "Georg"
    version       = "1.0"
    icon          = "kalkulon.xpm"
    deterministic = "true"
    description   = "This is a simple adder for two numbers."
  }

  port in_x
  {
    spec
      {
        io          = "in"
        linktype    = "number:1"
        strong_dep  = "true"
        description = "left summand"
      }
    options
      {
        name       = "x"
        widget     = "unbounded_selector"
        default    = "0"
      }
  }
  [...]
 >>

The first block (starting with "unit kalkulon") contains general
information about the unit. All shown keys, except "icon" must
be set.

After that, there is one block for every port of the unit.
A "port" block consists of a "spec" block with mandatory
information about the port followed by an "options" block
which contains additional information.


3. link spec
-------------

Links are described in link spec files (.lsp).

Example:

<<
 > cat number.lsp
link number
{
   author      = "Georg"
   version     = "1.0"
   description = "Number Link (double precision)"
   interface   = "
     double get_value() : const method;
     void   set_value(in double newValue) : method;

     double trim_double(in double min, in double max) : const method;
     int    trim_int(in int min, in int max) : const method;
     bool   trim_bool() : const method;"
}
 >>

The most important part is the "interface" key.
The "version" must have the form [0-9]+"."[0-9]+.


4. what does pluc produce?
---------------------------

pluc will produce all the glue code of the plugin s.t. the plugin
author only needs to write an update function for each unit
and the implementation of the links int the language that
he chooses.

It will also produce an automake file for the plugin.


5. how does pluc work?
-----------------------

pluc creates language independent interface files and calls
idlc on them to create the actual code for the chosen
language (will be C++ and C in the beginning).


6. details
-----------

For details please look at the sources in pluc/src.


Georg