deb-mbse/lib/Diesel.doc

                            T U R B O D I E S E L
         Template-based Uncomplicated Report-Building Oriented Dumb 
             Interpretively Evaluated String Expression Language

This is a  modified version of diesel  language.  Diesel is a  interpreted 
macro language, used in AutoCAD and released to public domain by AutoDesk.

Modified  version by Redy Rodriguez,  for use in mbsebbs.  Original diesel
language can be found at http://www.fourmilab.ch/diesel.
 
This  "Dumb  Interpretively  Executed  String  Expression Language" is the
kernel of a macro  language  you  can  customise  by  adding  C  code  and
embedding it into your program.

It is short, written in portable C, and is  readily  integrated  into  any
program.  It is useful primarily to programs which need a very rudimentary
macro expansion facility without the complexity of a full language such as
Lisp or FORTH.

DIESEL  copies  its  input directly to the output until a macro character,
"@" or quoted string is  encountered.   Quoted  strings  may  be  used  to
suppress  evaluation  of  sequences of characters which would otherwise be
interpreted as macros.  Quote marks may be included in quoted  strings  by
two adjacent quote marks.  For example:

    "@(if,1,True,False)="""@(if,1,True,False)""""

Status  retrieval,  computation,  and  display  are  performed  by  DIESEL
functions.   The  available  functions  are  as   follows.    User-defined
functions are not implemented; what you see is all you've got.  Naturally,
if you embed DIESEL in your application, you'll add functions that provide
access  to  information  and  actions  within  your own program.  DIESEL's
arithmetic functions accept either floating point  or  integer  arguments,
and perform all calculations in floating point.

TURBODIESEL facilities
----------------------

If a line begin with # then will be not evaluated, and any output is done.

If a line begin with @! any output is done, but evaluation is performed.

If a line begin with @{<expresion>} produces  output only if expression is
TRUE (Any non-zero numeric value).

To easily format output, you can use one-char variable names as follow:

   @A will be replaced by result of evaluate @(GETVAR,A).

   @A_____ will be replaced by result of evaluate @(GETVAR,A) truncated or
padded with spaces to complete same lenght of '@A_____' (7 in that case).  

   You can use > or < to especify alignement rigth or left:
   
   @A_____>         @A_____< 
   

TURBODIESEL String Functions
----------------------------

    @(+,<val1>,<val2>,...<valn>)
	The  sum  of  the  numbers <val1>, <val2>, ...<valn> is returned.

    @(-,<val1>,<val2>,...<valn>)
	The  result  of subtracting the numbers <val2> through <valn> from
	<val1> is returned.

    @(*,<val1>,<val2>,...<valn>)
	The result of multiplying the numbers  <val1>,<val2>,...<valn>	is
	returned.

    @(/,<val1>,<val2>,...<valn>)
	The  result of dividing the number <val1> by <val2>,...  <valn> is
	returned.

    @(=,<val1>,<val2>)
	If the	numbers  <val1>  and  <val2>  are  equal  1  is  returned,
	otherwise 0 is returned.

    @(<,<val1>,<val2>)
	If  the number <val1> is less than <val2> 1 is returned, otherwise
	0 is returned.

    @(>,<val1>,<val2>)
	If the number  <val1>  is  greater  than  <val2>  1  is  returned,
	otherwise 0 is returned.

    @(!=,<val1>,<val2>)
	If  the  numbers  <val1>  and  <val2> are not equal 1 is returned,
	otherwise 0 is returned.

    @(<=,<val1>,<val2>)
	If the number <val1>  is  less	than  or  equal  to  <val2>  1	is
	returned, otherwise 0 is returned.

    @(>=,<val1>,<val2>)
	If  the  number  <val1>  is  greater  than or equal to <val2> 1 is
	returned, otherwise 0 is returned.

    @(AND,<val1>,<val2>,...<valn>)
	The bitwise logical AND of the integers <val1> through	<valn>	is
	returned.

    @(EQ,<val1>,<val2>)
	If the strings <val1> and <val2>  are  identical  1  is  returned,
	otherwise 0.

    @(EVAL,<str>)
	The  string <str> is passed to the DIESEL evaluator and the result
	of evaluating it is returned.

    @(FIX,<value>)
	The real number <value> is truncated to an integer  by	discarding
	any fractional part.

    @(IF,<expr>,<dotrue>,<dofalse>)
	If  <expr>  is	nonzero,  <dotrue>  is	evaluated  and	 returned.
	Otherwise,  <dofalse>  is  evaluated  and returned.  Note that the
	branch not chosen by <expr> is not evaluated.

    @(INDEX,<which>,<string>)
	<string> is assumed to contain one or more values delimited by the
	macro argument separator character, comma.  <which> selects one of
	these values to be extracted, with the first item  numbered  zero.

*   @(LOWER,<string>)
	The  <string> is returned converted to lower case according to the
	rules of the current locale.

    @(NTH,<which>,<arg0>,<arg1>,<argN>)
	Evaluates  and	returns  the  argument	selected  by  <which>.	If
	<which> is 0, <arg0> is returned, and so on.  Note the	difference
	between  @(NTH)  and  @(INDEX);  @(NTH) returns one of a series of
	arguments to the function while @(INDEX) extracts a value  from  a
	comma-delimited string passed as a single argument.  Arguments not
	selected by <which> are not evaluated.

    @(OR,<val1>,<val2>,...<valn>)
	The  bitwise  logical  OR of the integers <val1> through <valn> is
	returned.

*   @(STRCMP,<str1>,<str2>)
	Compare strings and returns -1 if <str1> is less than <Str2>, 0 if 
	both are equals, or 1 if <str1> is greater than <str2> .

    @(STRFILL,<string>,<ncopies>)
	Returns the result of concatenating <ncopies> of <string>.

    @(STRLEN,<string>)
	Returns the length of <string> in characters.

*   @(STRSTR,<str1>,<str2>) 
	Find first apparition of <str2> in <str1>, and return the position
	or 0 if not found.

    @(SUBSTR,<string>,<start>,<length>)
	Returns  the  substring  of <string> starting at character <start>
	and extending for <length> characters.	Characters in  the  string
	are numbered from 1.  If <length> is omitted, the entire remaining
	length of the string is returned.

    @(UPPER,<string>)
	The  <string> is returned converted to upper case according to the
	rules of the current locale.

    @(XOR,<val1>,<val2>,...<valn>)
	The bitwise logical XOR of the integers <val1> through	<valn>	is
	returned.

Variable Extensions
-------------------

The  base-line DIESEL includes no user-defined variables.  This allows
DIESEL to avoid allocating any local memory  and  renders  it  totally
reentrant.   If you compile DIESEL with the tag VARIABLES defined, the
following additional functions are  included  which  provide  variable
definition  and  access.   Note that these functions call malloc() and
strdup() and thus consume heap storage.

Variable names are case sensitive. 

If you want easily format output you  must use one-char variable names
then you  can format output as @V_____, @X_____< or @k___>. See above.

    @(GETVAR,varname)
	Returns  the value stored in <varname>.  If no  variable  with  
	the name <varname> exists, a bad argument error is reported.

    @(SETVAR,varname,value)
    	Stores  the  string  <value>  into  <varname>.  If no variable 
	called <varname> exists, a new variable is created.

*   @(CLEAR)
        Clear all variables.

Unix Extensions
---------------

If you compile DIESEL with the tag UNIXTENSIONS defined, the following
additional functions will be available:

@(GETENV,varname)
    Returns  the  variable <varname> from the environment.  If no such
    variable is defined, returns the null string.

@(TIME)
    Returns the current time in Unix fashion, as the number of seconds
    elapsed since 00:00:00 GMT January 1, 1970.

@(EDTIME,<time>,<picture>)
    Edit  the  Unix  time <time> to format <picture>.  If <time> is 0,
    the current date and time is edited (this is  just  shorthand  for
    the equivalent "@(EDTIME,@(TIME),<picture>)".).

    Assume the date is: Thursday, 2 September 1993 4:53:17

    Format phrases:
        D               2
        DD              02
        DDD             Thu
        DDDD            Thursday
        M               9
        MO              09
        MON             Sep
        MONTH           September
        YY              93
        YYYY            1993
        H               4
        HH              04
        MM              53
        SS              17
        AM/PM           AM
        am/pm           am
        A/P             A
        a/p             a

    If  any  of the "AM/PM" phrases appear in the picture, the "H" and
    "HH" phrases will edit the time according to  the  12  hour  civil
    clock  (12:00-12:59-1:00-11:59)  instead  of  the  24  hour  clock
    (00:00-23:59).

TURBODIESEL Mechanics
---------------------

Generally, if you mess something up in a DIESEL expression it's pretty
obvious  what  went  wrong.   DIESEL embeds an error indication in the
output stream depending on the nature of the error:

    @?              Syntax error (usually a missing right  parenthesis
                    or runaway string).

    @(<func>,??)    Incorrect arguments to <func>.

    @(<func>)??     Unknown function <func>.

    @++             Output string too long--evaluation truncated.


Using TURBODIESEL
-----------------

You invoke TURBODIESEL within your program by calling:

    int status;
    char instring[<whatever>], outstring[MAXSTR + 1];

    outstring = ParseMacro(instring, &status);

The  output  from  the  evaluation  will  be  stored in outstring when
control is returned to your  program.   If  no  errors  were  detected
during  evaluation,  status  will be zero.  Otherwise status gives the
character position within instring at which the  error  was  detected.
If an error  occurs, TURBODIESEL  will  include  an error  diagnostic,
documented above, in outstring.

    To set single-char variables you can use:
    
    MacroVars(<string-names>,<string-types>,<value1>,...,<valueN>);

    string-names -> Variable names
    string-types -> Variable types 
                    (s: string, c: char, d: integer, f: float).
    Both strings  must be same  lenght, and the number of values  must 
    match with lenght and types.
    
    Sample:
    
    MacroVars("ABCDE","sscdf","A String","Another String",'C',5,4.67);

    To clear all variables you can use:
    
    MacroClear();