LIL: A Little Interpreted Language
==================================


0. Contents
-----------
  1. About
  2. LIL syntax
  3. LIL functions
     3.1. Standard LIL functions
     3.2. Command line interpreter LIL functions
  4. Integrating LIL in C programs
     4.1. Initialize LIL
     4.2. Execute LIL code
     4.3. Raise an error and obtain information about errors
     4.4. Convert values between C and LIL
     4.5. Register native functions
     4.6. Other LIL library functions
     4.7. LIL callback summary
     4.8. Using LIL as a DLL
  5. Integrating LIL in non-C programs
  6. Contact


1. About
--------
   LIL (Little Interpreted Language) is a small C library in just a pair of
 .c and .h files which provide a compact yet very dynamic scripting
 language inspired by Tcl and the UNIX shell.  LIL can be used in a wide
 range of situations, from simple configuration files to full extendability
 via scripting.
 
   The source code of LIL consists of a pair of .c and .h files (lil.c and
 lil.h) of ANSI C90 with some extensions from C99 (mostly the use of 64bit
 integers) which most modern compilers provide. The code has been tested to
 compile and work with the following compilers:
 
     * GNU C/C++ Compiler 3.x and 4.x
     * OpenWatcom C/C++ Compiler 1.9
     * LLVM Clang
     * Digital Mars C/C++ Compiler 8.42n
     * Tiny C Compiler 0.9.25
     * Microsoft Visual C++ 2010 Express (see below for older versions)
     * Borland's free C/C++ Compiler 5.5.1 (needs special Makefile)
 
 Users of older versions of Microsoft Visual C++ need to use a stdint.h
 file provided by external sources.  A commonly used one stdint.h file for
 MSVC is http://msinttypes.googlecode.com/svn/trunk/stdint.h.  Alternatively
 the global macro LILINT_INT64 can be used so that LIL will use __int64 for
 integers instead of stdint.h's int64_t.

 If the compiler doesn't use long long int nor __int64 for 64bit integers,
 then the global macro LILINT_CUSTOM must be defined and a type definition
 for lilint_t must exist before the inclusion of lil.h (including inside the
 lil.c file).
 
 As a side note, LIL has nothing to do with the "Little Implementation
 Language" for PDP (which i learned about months after i chose the name
 LIL for my library).  Apparently that LIL was made during the same time as
 the UNIX system and the C language by P.J.  Plauger.  If you are interested
 in this historical language you can read about it here:
 
     http://www.ultimate.com/phil/lil/


2. LIL syntax
-------------
   The syntax of LIL is very simple: the script is made up of "commands"
 and each command is a series of "words" separated by space, like:
 
     word1 word2 word3 ... wordn
 
   Words can be enclosed in quotes, double quotes and brackets which allow
 for special handling.  Quotes and double quotes, for example, can be used
 to include spaces or special characters (by escaping them with the \
 prefix as in C).  Square brackets are used to call inline commands and
 substitute the inlined command with its result.  Curly brackets are used
 to refer to a string without further processing (except counting the
 brackets inside them so that they can be nested).  A dollar in front of
 a word will replace itself and the word with the value of the variable
 that has the same name as the word (or with nothing if there is no such
 variable).
 
   When LIL needs to execute a command, it looks for a function with the
 same name as the first word of the command.  The function is executed
 using the rest of the words as its arguments (or parameters).  For example
 the following command
 
     print hello fred
 
 will execute the function "print" using the two words "hello" and "fred"
 as the first and second argument.  Using quotes one can combine the two
 words like
 
     print "hello fred"
 
 in which case LIL will execute the function "print" with the single word
 "hello fred" (note that a "word" in LIL can have any character, including
 spaces and even special characters by escaping them).  Since the words are
 separated before LIL decides which is function and which not, technically
 you can use functions with spaces, like
 
     "hello fred" print
     
 which will execute the function "hello fred" with the single word "print"
 as its argument.  In practice this should be avoided, at least for names
 that the script writer will use directly.
 
   As mentioned above the quotes can be used to escape characters, so you
 can write
 
     print "hello \"fred\""
   
   An alternative would be to use the single quotes (to avoid the need of
 using the escape character for double quotes) like
 
     print 'hello "fred"'
   
 or use curly braces like
 
     print {hello "fred"}
     
   Curly braces aren't always an alternative to single and double quotes:
 unlike them, curly braces do not do any further processing (except to
 count the curly braces inside so they can know where they end).  So this
 command
 
     print {hello \"fred\"}
 
 will include the \ character while this command
 
     print 'hello \"fred\"'
 
 will not because \" will be converted to ".
 
   Quotted strings can contain escape characters. These are characters
 which you either can't use or special characters you can't (or don't want)
 to type in the code.  As shown above, an escaped character starts with
 the \ character (the "escape character") and followed by another character
 which defines which character will be inserted at that point.  The escape
 characters LIL recognizes as special characters are
 
     b - inserts the backspace character
     t - inserts the horizontal tab character
     n - inserts the newline character
     v - inserts the vertical tab character
     f - inserts the formfeed character
     r - inserts the carriage return character
     a - inserts the bell character
 
 any other character will be included as-is without the \ character.  For
 example the string "hello\nworld" will insert a newline character between
 "hello" and "world".  The string "is this good\?" will be equal to the
 string "is this good?" and the string "hello \[world\]" will be equal
 to "hello [world]" (however LIL will not try to evaluate "world" as a
 command - see below).
 
   As mentioned above, square braces are used to replace (substitute) the
 command inside them with the result of that command.  In LIL this is used
 to access the result of a function.  As an example consider mathematical
 expressions: LIL does not have special expression handling.  To use math
 you have to type the expression as one or more arguments to the "expr"
 function which will combine all arguments, parse the expression as a
 single string and return the result.  So the command
 
     expr 4 + 4
 
 will have the result "8".  This result will not be shown anywhere - it is
 just the result of the command.  To access this result you use the square
 brackets with some other command.  For example to display the command with
 the print function use the expression inside the brackets like
 
     print [expr 4 + 4]
 
 this will print "8".  Here LIL actually sees two words, not five: the first
 word is the "print" word and the second word is the result of the command
 inside the brackets: when LIL sees the brackets, it scans its contents for
 an inline command.  Then it executes that command (which in turn might
 contain other inline commands) and considers the word as the executed
 command's result instead of the brackets' contents.  Note that if you
 typed
 
     print expr 4 + 4
 
 the word would be "print", "expr", "4", "+", "4" and the print function
 would simply display "expr 4 + 4" because without the square brackets
 there is not any special meaning for "expr".

   A very important function for LIL (beyond expr) is the "set" function.
 This function can be used to set values to variables.  For example when
 you execute
 
     set foo bar
 
 you set the value of the "foo" variable to the string "bar".  As you might
 have guessed if type
 
     set "foo bar" "moo mew"
 
 you will set the value of the "foo bar" variable to the string "moo mew":
 LIL can use any valid character as a name, as long as you can express it
 as a string.  The set function can be used with zero or more arguments.
 For each pair, a variable named as the first word of the pair will be set
 to the second word of the pair.  If there is an odd number of arguments,
 the result of the set function is the value of the variable that has the
 same name as the last word.  So for example the command
 
     set name

 will have a result equal with the value of the variable "name" and thus
 the command
 
     print [set name]
 
 will print the value of the variable "name".  Since accessing variables is
 something very common LIL provides a shortcut: a dollar in front of a word
 is the same as calling set with that word as a single argument.  So the
 command above could be written as
 
     print $name
 
 Note two important things however: first, the name of the variable is NOT
 "$name".  It is "name".  The dollar is used as a shortcut for "[set name]".
 And second, it *really* is a shortcut: the "set" function will be called
 even if you don't type it (so if you override it, the overridden function
 will be called).  You can also change the behavior of $ by setting another
 function to be called with "reflect dollar-prefix" (see section 3 for
 details).
 
   Remember the part about curly brackets above? Well, if you type
   
     print "hello $user"
   
 the result will be to display "hello " followed with whatever the value of
 the variable "user" is (so for example if "user" was set to "fred" the
 displayed string would be "hello fred").  However if you type
 
     print {hello $user}
 
 the displayed string will be "hello $user" because curly brackets really
 do not process whatever is inside.  This can be used to define new
 functions because the function's code is, like anything else in LIL, a
 plain old string.  And since you don't want to process that string's
 contents directly, you need curly brackets.

   The definition of a new function is done using the "func" function.  This
 function accepts zero or more arguments (when zero arguments are given,
 the function does nothing and returns an empty string).  When three
 arguments are given (the most common case) they are considered as the name
 the argument list and the code/body of the function.  For example
 
     func foo {a b} { print $a $b }
 
 defines a function named "foo" with the argument list "a b" and as code
 the string "print $a $b".  The argument list is a LIL list (a space
 separated list of words using similar rules as the separation of words for
 commands - which in turn can include other sublists but escaping their
 words, etc - with the exception that a LIL list value can include newline
 characters) where each word in the list specifies an argument and the code
 is the code that will be executed when the function is evaluated.  Before
 LIL evaluates a function, it stores in local variables with the same name
 as those specified in the argument list the arguments passed to the
 function in the same order as they appear in the argument list.  So for
 example when evaluating the above function LIL will save the first
 argument passed to the function in "a" and the second argument in "b".  If
 more arguments are given these are lost and if less arguments are given,
 the rest of the expected arguments are set to empty strings (so for
 example if "foo 32" is given the "b" variable will be an empty string).
 
   To use an unknown number of variables use the special name "args" as the
 only word in the argument list.  LIL will store all passed arguments in
 the "args" argument as a list which you can access either directly or via
 the list functions (index, count, foreach, etc).  For example:
 
     func foo args { foreach $args { print arg: $i } }
 
 which when used like
 
     foo apple orange cake
 
 will display
 
     arg: foo
     arg: apple
     arg: orange
     arg: cake
 
 (when the special "args" name is used, the first word in the list will
 always be the function's name)
 
   The "func" function can also be used with two or even one argument.
 This use allows the definition of anonymous (or actually, randomly named)
 functions.  In the two arguments format, the first argument is the
 arguments list as previously and the second argument is the function's
 code.  For example
 
     func {a b} { return [expr $a + $b] }
 
 returns an anonymous function which accepts two arguments and returns
 their sum.  In the one argument format, the only argument is the
 function's code and the arguments are stored in the "args" variable as if
 you used the special "args" name.  For example
 
     func { foreach $args { print $i is good } }
 
 returns an anonymous function which prints "... is good" for each one of
 the arguments LIL passes to it.
 
   So how are anonymous functions used? Remember the basic syntax of LIL
   
     word1 word2 word3 ... wordn
     
 and that that when LIL wants to execute the command the first word is the
 name of the function? Well, word1 is no different than word2, word3, etc
 and can be a variable reference too.  So if you type
 
     set foo print
     $foo hello
 
 LIL will replace "$foo" with "print" as normal and then will execute the
 function "print" because that happens to be the first word.  So you use
 anonymous functions in the same way: anonymous functions aren't really that
 anonymous but they have a generated name.  That name is what "func"
 returns.  So if you type
 
     set foo [func {a b} { return [expr $a + $b] }]
     print [$foo 3 2]
 
 LIL will define a randomly named function with the argument list "a b" and
 code "return [expr $a + $b]", set its random name to the "foo" variable
 and - in the next line - call it with the arguments 3 and 2 and pass the
 result to print which in turn will display it - "5".

   LIL itself does not require the use of anonymous functions, but they can
 be handy in more advanced scripts and situations.  An example would be a
 function which returns another function which is composed using the
 arguments to the first function.

   When using functions you should keep in mind variable scope: variables
 are defined in global scope (visible and accessible from everywhere) and
 local scope.  Local scope has variables defined from within the function
 itself.  When you access a variable for reading it (like when using it
 with the dollar) LIL looks in the local environment (where the variables
 are stored) and then the global environment.  When you use the "set"
 function to set the value of a variable LIL always look first in the
 local environment and if the variable isn't found, it looks in the global
 environment.  If no variable is found, a new variable in the local
 environment will be created.  To force a global variable to be set or
 created, put the special "global" word as the first argument to the set
 function, like
 
     set global level 32
 
 which sets the value of the global variable "level" to "32".  Functions
 that create variables always provide this special "global" first argument
 to force the assignment of global variables.  Note that the use of
 "global" is only needed for code that runs from functions.  Code that is
 executed outside a function always uses the global environment.  To
 force a local variable, you need to create an empty local variable first
 by calling the "local" function, like

    local level
    set level 32

 which first creates a local variable (even if a global with the same name
 exists) with an empty value and then it sets its value to 32 (since the
 set function first looks in the local environment, it will find the one
 just made and will ignore any variable that may be in the global one).

   The last note on LIL's syntax is word concatenation.  This is really
 simple (and technically is not concatenation at all but it is easier to
 think it like this): if two words are not separated by space they are
 combined to a single word.  So for example the command
 
     print "hello "world
 
 is made up of two words: "print" and "hello world".  Similarly the command
 
     print "is it "[expr 3 + 2]?
 
 is made up of two words again: "print" and "is it six?".  This happens
 because the "is it ", [expr 3 + 2] and ? parts are combined together and
 not separated by a space.
 
   LIL commands are separated by newlines (each command takes a whole line)
 or the ; character.  For example, for LIL the code
 
     print hello ; print world
 
 is the same as
 
     print hello
     print world
     
   Finally you can put comments in the code using the # character.  Any
 characters after # until the end of the line will be ignored by the LIL
 interpreter.


   For more information and details on LIL's syntax, check the .lil example
 files that come with the source code distribution.  And of course the C
 code itself is clean and compact which makes it easy to read and, if
 needed, modify.

3. LIL functions
----------------

3.1. Standard LIL functions
     ----------------------

   Here is a summary of the functions that LIL provides by default to all
 LIL scripts (in order of appearance in the lil.c file):
 
     reflect
       reflect information about the LIL runtime and the program
 
     reflect version
       returns the LIL_VERSION_STRING
 
     reflect args <func>
       returns a list with the argument names for the given function
     
     reflect body <func>
       returns the code of the given function
     
     reflect func-count
       returns the number of the known functions
     
     reflect funcs
       returns a list with all the known function names
     
     reflect vars
       returns a list with all the known variable names (includes global
       and local variables)
     
     reflect globals
       returns a list with all the known global variable names

     reflect has-func <name>
       returns a true value (non-zero, non-empty value) if a function with
       the given name is known
     
     reflect has-var <name>
       returns a true value (non-zero, non-empty value) if a variable with
       the given name is known
     
     reflect has-global <name>
       returns a true value (non-zero, non-empty value) if a global
       variable with the given name is known
     
     reflect error
       returns the last error message or an empty string if there is no
       error condition active (this is usually used with the try function)

     reflect dollar-prefix [prefix]
       if [prefix] is specified, then this changes the dollar prefix.  If no
       arguments are given, the current dollar prefix is returned.  The dollar
       prefix is the command to be executed for dollar expansions (like $foo).
       The word after the dollar prefix is appended immediately after the
       prefix and the whole is executed.  The default dollar prefix is 'set '
       (notice the space which will separate the call to "set" from the word
       following)

     reflect this
       returns the code of the current local environment.  This will return
       the currently executed function's body, the current root (top-level)
       code or the current catcher code (if the current environment is a
       catcher environment)

     reflect name
       returns the name of the currently executed function or an empty string
       if the code is executed at root level (or the name of the current
       function is unknown)
     
     func [name] [argument list | "args"] <code>
       register a new function.  See the section 2 for more information

     rename <oldname> <newname>
       rename an existing function.  Note that the "set" function is used to
       access variables using the $ prefix so if the "set" function is
       renamed, variables will only be accessible using the new name.  The
       function returns the <oldname>

     unusedname [part]
       return an unused function name.  This is a random name which has the
       form !!un![part]!<some number>!nu!!.  The [part] is optional (if not
       provided "unusedname" will be used)
     
     quote [...]
       return the arguments as a single space-separated string
     
     set ["global"] [name [value] ...]
       set the variable "name" to the "value".  If there is an odd number of
       arguments, the function returns the value of the variable which has
       the same name as the last argument.  Otherwise an empty value is
       returned.  See section 2 for details
     
     local [...]
       make each variable defined in the arguments a local one.  If the
       variable is already defined in the local environment, nothing is done.
       Otherwise a new local variable will be introduced.  This is useful
       for reusable functions that want to make sure they will not modify
       existing global variables

     write [...]
       write the arguments separated by spaces to the program output.  By
       default this is the standard output but a program can override this
       using the LIL_CALLBACK_WRITE callback
     
     print [...]
       like write but adds a newline at the end
     
     eval [...]
       combines the arguments to a single string and evaluates it as LIL
       code.  The function returns the result of the LIL code

     topeval [...]
       combines the arguments to a single string and evaluates it as LIL
       code in the topmost (global) environment.  This can be used to execute
       code outside of any function's environment that affects the global
       one

     upeval [...]
       combines the arguments to a single string and evaluates it as LIL
       code in the environment above the current environment (the parent
       environment).  For functions this is usually the function caller's
       environment.  This can be used to access local variables (for read
       and write purposes) of a function's caller or to affect its flow
       (like causing a caller function to return).  The function can be
       used to provide most of the functionality that other languages
       provide via the use of macros but at the program's runtime and with
       full access to the program's state
     
     downeval [...]
       downeval complements upeval. It works like eval, but the code is
       evaluated in the environment where the most recent call to upeval was
       made.  This also works with topeval

     enveval [invars] [outvars] <code>
       the <code> will be executed in its own environment.  The environment
       will be similar to a function's environment.  If invars is provided,
       it is assumed to be a list with variable names to be copied from the
       current environment to the new environment.  If outvars is provided, it
       is assumed to be a list with variable names to be copied from the new
       environment back to the current one (global variables will remain
       global).  If invars is provided but not outvars, the variables in
       invars will be copied back as if outvars was provided with the same
       variable names.  To make the variables "one way" (that is, to copy
       nothing back) just use an empty list for the outvars argument.  From
       inside enveval both return and an immediate value can be used to
       return a value.  Calling return will not cause the calling function
       to exit

     jaileval ["clean"] <code>
       the <code> will be executed in its own LIL runtime.  Unless "clean"
       is specified, the new LIL runtime will get a copy of the currently
       registered native functions.  The <code> can use "return" to return
       a value (which is returned by jaileval)
     
     count <list>
       returns the number of items in a LIL list
     
     index <list> <index>
       returns the <index>-th item in a LIL list.  The indices begin from
       zero (so 0 is the first index, 1 is the second, etc)

     indexof <list> <value>
       returns the index of the first occurence of <value> in a LIL list.  If
       the <value> does not exist indexof will return an empty string.  The
       indices begin from zero (so 0 is the first index, 1 is the second,
       etc)

     filter [varname] <list> <expression>
       filters the given list by evaluating the given expression for each
       item in the list.  If the expression equals to true (is a non-zero
       number and a non-empty string), then the item passes the filter.
       Otherwise the filtered list will not include the item.  For each
       evaluation, the item's value is stored in the [varname] variable
       (or in the "x" variable if no [varname] was given).  The function
       returns the filtered list

     list [...]
       returns a list with the arguments as its items
     
     append ["global"] <list> <value>
       appends the <value> value to the variable containing the <list>
       list (or creates it if the variable is not defined).  If the "global"
       special word is used, the list variable is assumed to be a global
       variable
     
     slice <list> <from> [to]
       returns a slice of the given list from the index <from> to the index
       [to]-1 (that is, the [to]-th item is not includd).  The indices are
       clamped to be within the 0..<list length> range.  If [to] is not
       given, the slice contains all items from the <from> index up to the
       end of the list

     subst [...]
       perform string substitution to the arguments.  For example the code
       
         set foo bar
         set str {foo$foo}
         print [substr $str]
       
       will print "foobar"
     
     concat [...]
       substitutes each argument as a list, converts it to a string and
       returns all strings combined into one
     
     foreach [name] <list> <code>
       for each item in the <list> list, stores it to a variable named "i"
       and evalues the code in <code>.  If [name] is provided, this will be
       used instead of "i".  The results of all evaluations are stored in a
       list which is returned by the function
     
     return [value]
       stops the execution of a function's code and uses <value> as the
       result of that function (note that normally the result of a function
       is the result of the last command of that function).  The result of
       return is always the passed value

     result [value]
       sets or returns the current result value of a function but unlike
       the return function, it doesn't stop the execution.  If no argument
       is given, the function simply returns the current result value - if
       no previous call to result was made, then this will return an empty
       value even if other calls were made previously.  The result of this
       function when an argument is given, is simply the given argument
       itself
     
     expr [...]
       combines all arguments into a single string and evaluates the
       mathematical expression in that string.  The expression can use the
       following operators (in the order presented):
       
          (a)        - parentheses
       
          -a         - negative sign
          +a         - positive sign
          ~a         - bit inversion
          !a         - logical negation
       
          a * b      - multiplication
          a / b      - floating point division
          a \ b      - integer division
          a % b      - modulo
       
          a + b      - addition
          a - b      - subtraction
       
          a << b     - bit shifting
          a >> b
       
          a <= b     - comparison
          a >= b
          a < b
          a > b
       
          a == b     - equality comparison
            or
          a != b
          
          a & b      - bitwise AND
          
          a || b     - logical OR
          a && b     - logical AND
     
     inc <name> [value]
       numerically add [value] to the variable "name".  If [value] is not
       provided, 1 will be added instead
     
     dec <name> [value]
       numerically subtract [value] to the variable "name".  If [value] is
       not provided, 1 will be subtracted instead
     
     read <name>
       reads and returns the contents of the file <name>.  By default LIL
       will look for the file in the host program's current directory, but
       the program can override this using LIL_CALLBACK_READ.  If the
       function failed to read the file it returns an empty value (note,
       however than a file can also be empty by itself)
     
     store <name> <value>
       stores the <value> value in the file <name>.  By default LIL will
       create the file in the host program's current directory, but the
       program can override ths using LIL_CALLBACK_STORE.  The function will
       always return <value>
     
     if ["not"] <value> <code> [else-code]
       if value <value> evaluates to true (non-zero, non-empty string), LIL
       will evaluate the code in <code>.  Otherwise (and if provided) the
       code in [else-code] will be evaluated.  If the "not" special word is
       used, the check will be reversed.  The function returns the result of
       whichever code is evaluated
     
     while ["not"] <expr> <code>
       as long as <expr> evaluates to a true (or false if "not" is used)
       value, LIL will evaluate <code>.  The function returns the last
       result of the evaluation of <code> or an empty value if no
       evaluation happened (note, however that the last evaluation can
       also return an empty value)
     
     for <init> <expr> <step> <code>
       the loop will begin by evaluating the code in <init> normally.  Then
       as long as the expression <expr> evaluates to a true value, the
       code in <code> will be evaluated followed by the code in <step>.  The
       function returns the result of the last evaluation of <code>
     
     char <code>
       returns the character with the given code as a string.  Note that the
       character 0 cannot be used in the current implementation of LIL since
       it depends on 0-terminated strings.  If 0 is passed, an empty string
       will be returned instead
     
     charat <str> <index>
       returns the character at the given index of the given string.  The index
       begins with 0.  If an invalid index is given, an empty value will be
       returned
     
     codeat <str> <index>
       returns the character code at the given index of the given string.  The
       index begins with 0.  If an invalid index is given, an empty value will
       be returned
     
     substr <str> <start> [length]
       returns the part of the given string beginning from <start> and for
       [length] characters.  If [length] is not given, the function will
       return the string from <start> to the end of the string.  The indices
       will be clamped to be within the string boundaries
     
     strpos <str> <part> [start]
       returns the index of the string <part> in the string <str>.  If
       [start] is provided, the search will begin from the character at
       [start], otherwise it will begin from the first character.  If the
       part is not found, the function will return -1
     
     length [...]
       the function will return the sum of the length of all arguments

     trim <str> [characters]
       removes any of the [characters] from the beginning and ending of a
       string until there are no more such characters.  If the [characters]
       argument is not given, the whitespace characters (space, linefeed,
       newline, carriage return, horizontal tab and vertical tab) are used

     ltrim <str> [characters]
       like "trim" but removes only the characters from the left side of the
       string (the beginning)

     rtrim <str> [characters]
       like "trim" but removes only the characters from the right side of the
       string (the ending)

     strcmp <a> <b>
       compares the string <a> and <b> - if <a> is lesser than <b> a
       negative value will be returned, if <a> is greater a positive an
       if both values are equal zero will be returned (this is just a
       wrap for C's strcmp() function)
     
     streq <a> <b>
       returns a true value if both strings are equal
     
     repstr <str> <from> <to>
       returns the string <str> with all occurences of <from> replaced with
       <to>
     
     split <str> [sep]
       split the given string in substrings using [sep] as a separator and
       return a list with the substrings.  If [sep] is not given, the space
       is used as the separator.  If [sep] contains more than one characters,
       all of them are considered as separators (ie. if ", " is given, the
       string will be splitted in both spaces and commas).  If [sep] is an
       empty string, the <str> is returned unchanged
     
     try <code> [handler]
       evaluates the code in <code> normally and returns its result.  If an
       error occurs while the code in <code> is executed, the execution
       stops and the code in [handler] is evaluated, in which case the
       function returns the result of [handler].  If [handler] is not
       provided the function returns 0
     
     error [msg]
       raises an error.  If [msg] is given the error message is set to <msg>
       otherwise no error message is set.  The error can be captured using
       the try function (see above)
     
     exit [code]
       requests from the host program to exit.  By default LIL will call the
       C function exit() but the host program can override this using the
       LIL_CALLBACK_EXIT callback.  If [code] is given it will be provided
       as a potential exit code (but the program can use another if it
       provides a LIL_CALLBACK_EXIT callback)
     
     source <name>
       read and evaluate LIL source code from the file <name>.  The result
       of the function is the result of the code evaluation.  By default LIL
       will look for a text file in the host program's current directory
       but the program can override that by using LIL_CALLBACK_SOURCE
     
     lmap <list> <name1> [name2 [name3 ...]]
       map the values in the list to variables specified by the rest of the
       arguments.  For example the command
       
         lmap [5 3 6] apple orange pear
         
       will assign 5 to variable apple, 3 to variable orange and 6 to
       variable pear
     
     rand
       returns a random number between 0.0 and 1.0
       
     catcher [code]
       sets, removes or returns the current catcher code.  The code can be
       used to "catch" calls of unknown functions and is executed inside
       its own environment as if an anonymous function without specified
       arguments was called.  This means that the code can access the name
       and the arguments of the function call using the "args" list -
       however unlike anonymous functions which get a random name, the zero
       index of the args list contains the unknown function's name.  The
       code can also use "return" to return some value.  If the catcher code
       calls an unknown function, it will be called again - however to avoid
       infinite loops a limit on the nested calls to the catcher code is set
       using the MAX_CATCHER_DEPTH constant (which by default is set to
       16384).
       
       This function can be used to implement small embedded DSLs in LIL code
       or provide some sort of shell (as in UNIX shell) functionality by
       delegating the unknown function calls to some other function/command
       handler (like executing an external program).
       
       If catcher is called with an empty string, the catcher code is removed
       and LIL will resume raising errors when an unknown function is called
       (which is the default behavior before any call to catcher is made).
       
       If catcher is called without arguments it will return the current
       catcher code.  This can be used to temporary save the current catcher
       code when changing the catcher code temporarily.  For example
       
         set previous-catcher [catcher]
         catcher {print Call failed: $args}
         # do something
         catcher $previous-catcher
         
       When using catcher for DSLs it is recommended to save the previous
       catcher.  For an example of catcher with comments see the catcher.lil
       source file.

3.2. Command line interpreter LIL functions
     --------------------------------------
   The functions shown below are only available to the command line LIL
 interpreter (the "lil" executable).

     writechar code
       writes the character defined by the given code (usually ASCII code)
       to the standard output

     system <args>
       executes the system command defined by <args> and returns the data
       placed in the command's standard output

     readline
       reads a string from the standard input until the end of file or end
       of line mark/character is found and returns it


4. Integrating LIL in C programs
--------------------------------
   To integrate LIL in C programs you have two options:
   
     1. Use the liblil.a library (for Clang and GCC) or liblil.lib (for
        OpenWatcom) as a static library from your project, or
     
     2. Put the lil.c and lil.h files directly in your project
   
   Whichever method you choose, the rest is the same.  Please note that
 the LIL interface should not be considered as frozen at this point.  The
 library is under constant development and might change.  In the future a
 frozen API will be provided but even that will only be guaranteed to
 survive major versions.

4.1. Initialize LIL
     --------------
   You can have several "LILs" running: each one can be separate from the
 others and have its own definitions.  A LIL runtime is stored in the lil_t
 C type that basically specifies an object.  To construct a lil_t object
 use lil_new() and to destroy it use lil_free().  For example:
 
     lil_t lil = lil_new();
     ...
     lil_free(lil);
 
   Before running LIL code you might want to override some of LIL's default
 functionality.  This can be done using the lil_callback() function which
 has the following signature:
 
     void lil_callback(lil_t lil,
                       int cb,
                       lil_callback_proc proc)
     
   The cb is one of the LIL_CALLBACK_* constants defined in the lil.h file
 and the proc is a function with the same signature as the
 lil_callback_*_proc_t type defined in lil.h, casted back to
 lil_callback_proc_t.  For example to define a callback for the "exit"
 function (something you probably want to do in most programs) use the
 following code
 
     void handl_exit(lil_t lil, lil_value_t arg)
     {
         ...
     }
     
     ...

     lil_callback(lil, LIL_CALLBACK_EXIT, (lil_callback_proc_t)handl_exit);
 
4.2. Execute LIL code
     ----------------
   To execute LIL code use the lil_parse() function.  This function has the
 following signature:
 
     lil_value_t lil_parse(lil_t lil,
                           const char* code,
                           size_t codelen,
                           int funclevel)

   If 0 is given for codelen, LIL will simply use strlen for it.  Funclevel
 should always be 1, unless the evaluated code is supposed to be executed
 inside the current environment.  Setting funclevel to 1 will reset (clear)
 the breakrun flag (which is set by return to stop executing code in
 lil_parse, lil_parse_value and loops).
 
   The function will return a LIL value which must be released by calling
 lil_free_value().  The LIL value is the code's result.

   An alternative to lil_parse is lil_parse_value which can be used to
 parse code which is stored in a LIL value.  The signature is
 
     lil_value_t lil_parse_value(lil_t lil,
                                 lil_value_t val,
                                 int funclevel)

4.3. Raise an error and obtain information about errors
     ----------------------------------------------
   You can raise an error (similar to an exception but all errors in LIL
 are "united" under the same umbrella - runtime errors, syntax errors, etc)
 using the lil_set_error() function which has the following signature
 
     void lil_set_error(lil_t lil,
                        const char* msg)
 
 where msg is the message of the error.  The LIL script can use the "try"
 function to catch the error or, if the error is not catched, the host
 program can use lil_error() to obtain information about it.  The
 lil_error() function will return a non-zero value if there is an error
 message available.  The signature of the function is
 
     int lil_error(lil_t lil,
                   const char** msg,
                   size_t* pos)
 
 the msg pointer will receive the error message and pos will receive the
 position where the message occured (note that the position is usually
 local to the executed command, not the whole script).

4.4. Convert values between C and LIL
     --------------------------------
   LIL uses the lil_value_t type for its own values.  To convert from C to
 lil_value_t you use the following functions:
 
     lil_value_t lil_alloc_string(const char* str)
     lil_value_t lil_alloc_double(double num)
     lil_value_t lil_alloc_integer(lilint_t num)
 
   Note that "alloc" here really means allocate: the values will allocate
 memory on the heap for their contents.  You are responsible for releasing
 the memory using lil_free_value() with the exception of function results
 (see next).
 
   To convert a lil_value_t to a C type use one of the following functions:

     const char* lil_to_string(lil_value_t val)
     double lil_to_double(lil_value_t val)
     lilint_t lil_to_integer(lil_value_t val)
     int lil_to_boolean(lil_value_t val)

   You can also clone a value using lil_clone_value() and append characters
 at the end of existing values using one of the following functions:

     lil_value_t lil_clone_value(lil_value_t src)
     int lil_append_char(lil_value_t val, char ch)
     int lil_append_string(lil_value_t val, const char* s)
     int lil_append_val(lil_value_t val, lil_value_t v)

   Using the following functions you can manipulate LIL lists:

     lil_list_t lil_alloc_list(void)
     void lil_free_list(lil_list_t list)
     void lil_list_append(lil_list_t list, lil_value_t val)
     size_t lil_list_size(lil_list_t list)
     lil_value_t lil_list_get(lil_list_t list, size_t index)
     lil_value_t lil_list_to_value(lil_list_t list, int do_escape)

 the last function will convert a lil_list_t to a LIL value.  Unless you are
 sure that escaping is not needed, you should always use a non-zero value
 for do_escape.  The reverse can be performed with

     lil_list_t lil_subst_to_list(lil_t lil, lil_value_t code)
 
 and combining the two with 

     lil_value_t lil_subst_to_value(lil_t lil, lil_value_t code)

4.5. Register native functions
     ----------------------------
   To register a new function in LIL use the lil_register() function.  This
 function has the following signature:

     int lil_register(lil_t lil,
                      const char* name,
                      lil_func_proc_t proc)

 and returns a non-zero value if the registration was successful.  The
 native function must have the following signature:
 
     lil_value_t lil_func_proc(lil_t lil,
                               size_t argc,
                               lil_value_t* argv)
 
 where lil is the lil object that issued the function, argc is the number
 of arguments used and argv is an array of "argc" lil_value_t elements with
 the arguments passed to the function.  The function must return a newly
 allocated lil_value_t object or NULL if the function returns nothing (or
 returns an empty string).
 
   An example:
   
     static lil_value_t fnc_hi(lil_t lil, size_t argc, lil_value_t* argv)
     {
         printf("Hi!\n");
         return NULL;
     }
 
     ...
     
     lil_register(lil, "hi", fnc_hi);

4.6. Other LIL library functions
     ---------------------------
   Some other library functions are
   
     lil_var_t lil_set_var(lil_t lil,
                           const char* name,
                           lil_value_t val,
                           int local)

 which can be used to set a variable to a value.  local must be one of
 LIL_SETVAR_LOCAL, LIL_SETVAR_LOCAL_NEW, LIL_SETVAR_LOCAL_ONLY or
 LIL_SETVAR_GLOBAL.  Usually you need LIL_SETVAR_LOCAL or LIL_SETVAR_GLOBAL.
 LIL_SETVAR_LOCAL_NEW will always allocate a new variable in the environment
 and should be used with lil_push_env() and lil_pop_env(). See lil.c for
 details on how to use these.

   LIL_SETVAR_LOCAL_ONLY will make sure that the variable is stored in the
 local environment and can be used to avoid name collisions between variables
 defined inside and outside functions.  It should be used by functions that
 set their own variables to be used by the scripts (for example, foreach uses
 this to avoid name collisions between its index variable and the global
 environment).  When in doubt, use LIL_SETVAR_LOCAL if the variable's name is
 provided by the script and the function is supposed to act on a variable,
 otherwise use LIL_SETVAR_LOCAL_ONLY if the variable name is decided by the
 function (with optional alteration of the name by the script, such as in
 foreach) and the variable is to be reused (so LIL_SETVAR_LOCAL_NEW is not a
 good candidate).
 
     lil_value_t lil_get_var(lil_t lil,
                             const char* name)
     
 which can be used to return the value of a variable.  Alternatively
     
     lil_value_t lil_get_var_or(lil_t lil,
                                const char* name,
                                lil_value_t defvalue)

 which will return "defvalue" if the variable is not found.  These two will
 always use the "current" environment (which will be a local environment if
 the function is called from a native function callback for a native
 function called from a script function).

     lil_value_t lil_eval_expr(lil_t lil,
                               lil_value_t code)

 which can be used to evaluate an expression like the "expr" function.
 
     lil_value_t lil_unused_name(lil_t lil,
                                 const char* part)
 
 which can be used to return an unused LIL name using the given part.
 
   Sometimes you need to associate some piece of data (like an object or a
 script name) with a LIL runtime.  You can use the following functions to
 associate a pointer to a lil_t object and retrieve it:
 
     void lil_set_data(lil_t lil,
                       void* data)
  
  which associates "data" with the given lil object and
  
     void* lil_get_data(lil_t lil)
  
  which returns the associated data with the given lil object.  By default
  this will return NULL if no call to lil_set_data() is made.

4.7. LIL callback summary
     --------------------
   Here is a summary of the LIL_CALLBACK_* constants for use with the
 lil_callback() function:

     LIL_CALLBACK_EXIT
       callback:  lil_exit_callback_proc_t
       signature: void (lil_t lil, lil_value_t arg)
       called:    when the LIL "exit" function is called
       
     LIL_CALLBACK_WRITE:
       callback:  lil_write_callback_proc_t
       signature: void (lil_t lil, const char* msg)
       called:    when the "print" or "write" function is called.  It is
                  expected to parse the newline character \n
     
     LIL_CALLBACK_READ:
       callback:  lil_read_callback_proc_t
       signature: char* (lil_t lil, const char* name)
       called:    to read the file "name" and return its contents
     
     LIL_CALLBACK_SOURCE:
       callback:  lil_source_callback_proc_t
       signature: char* (lil_t lil, const char* name)
       called:    to read the LIL source file "name" and return its code
     
     LIL_CALLBACK_STORE:
       callback:  lil_store_callback_proc_t
       signature: void (lil_t lil, const char* name, const char* data)
       called:    to store "data" in the file "name" as its contents

     LIL_CALLBACK_ERROR:
       callback:  lil_error_callback_proc_t
       signature: void (lil_t lil, size_t pos, const char* msg)
       called:    when an error occurs and is not handled
     
     LIL_CALLBACK_SETVAR:
       callback:  lil_setvar_callback_proc_t
       signature: int (lil_t lil, const char* name, lil_value_t* value)
       called:    when a non-existant variable is assigned in the global
                  environment.  If this returns a negative value, the
                  assignment does not occur.  If this returns a zero, the
                  value originally to be written is assigned to the
                  variable.  If this returns a positive value, the
                  value pointed by "value" is assigned.  This can be used
                  to override or cancel the assignment of a variable
     
     LIL_CALLBACK_GETVAR:
       callback:  lil_getvar_callback_proc_t
       signature: int (lil_t lil, const char* name, lil_value_t* value)
       called:    when a variable is to be read from the global environment.
                  If this function returns a non-zero value, the value
                  pointed to by "value" is used instead of the value that
                  would be normally returned.  Otherwise the original value
                  is used

4.8. Using LIL as a DLL
     ------------------
   The C code of LIL was not written to be used as a DLL, so keep that in
 mind when you decide to use LIL via a DLL.  Using LIL as a DLL requires a
 couple of extra steps to be performed:
 
     * LIL itself and every code that includes lil.h must be compiled with
       the LILDLL conditional defined.  This will cause all public functions
       to be marked as DLL exportable/importable and use the stdcall
       calling convention.  Note that because by default if no LILDLL is
       defined the library will use the compiler's default calling
       convention you shouldn't mix LILDLL with non-LILDLL sources
     * The LILCALLBACK macro must be used for callbacks.  For example this
     
           static lil_value_t fnc_hi(lil_t lil,
                                     size_t argc,
                                     lil_value_t* argv)
       
       must be changed to this

           static LILCALLBACK lil_value_t fnc_hi(lil_t lil,
                                                 size_t argc,
                                                 lil_value_t* argv)
 
   Under the "dll" directory there is an OpenWatcom project file which will
 create a lil.dll file you can use.  Note that it is highly recommended to
 not mix different DLL versions.  The LIL API and binary interface is not
 frozen and the DLL interface might change.
 
 
5. Integrating LIL in non-C programs
------------------------------------
   It is possible to use LIL from non-C programs as long as a method to
 link against C is provided and the language supports the data types used
 by the public LIL interface (only data types are needed, the public
 interface does not use C structs).  Currently under Windows it is
 recommended to use the DLL version of LIL built using the OpenWatcom
 project found under the "dll" directory of the LIL repository (although it
 might be possible to build a compatible version with MinGW or Visual C++,
 i have not checked this).
 
   While you can write the interface yourself, there are some prewritten
 interfaces which you can find at the Import LIL project at:
 
     https://github.com/badsector/implil
     
   Currently the following languages/environments are supported:
   
     * Visual C# / .NET 4
       (will probably work under older versions, might work under Mono)
     * FreePascal (and Lazarus)
       
   Check the above site for further and up-to-date information (might list
 other supported interfaces).
 

6. Contact
----------
  Kostas Michalopoulos
  badsector@runtimelegend.com
  badsectoracula@gmail.com
  
  also see https://github.com/badsector/lil