wwlisp Reference Manual

For Interpreter Version 8.2.6 - December 2008

What is wwlisp?	wwlisp is an interpreted programming language for application development and scripting which can be used for developing stand-alone programs, shells scripts or can be embedded in another program. wwlisp is a concise object oriented dialect of the Lisp language very loosely inspired by Common Lisp, Smalltalk, or even C++. wwlisp aims at solving specific categories of problems and hence the implementation does not comprise mechanisms intended to treat all the types of data traditional in Lisp or to implement theoretical concepts of software engineering or facilities dedicated to the management of large projects. Some syntactical forms related to the conservation of memory or the intricacies of the language were abandoned at the profit of a lighter syntax. To learn more on the language, just take a look at the wwlisp Syntax Primer. The wwlisp Project is hosted at SourceForge.net. To download wwlisp, go directly here. The project evolves, so to see what's new about wwlisp, look here.
Applications, Plugins and Tools	Yet another Lisp dialect just for the sake of it would probably not be worth the download, but just with the addition of a few supplementary libraries, the Lisp-like syntax and its peculiar object orientation begin to show quite productive results. Just take a look to the additional specialized libraries: wwlispkdialog dynamically builds a KDE dialog with KDE and Qt widgets, and operates it. wwlisp2dimage adds turtle graphics to GD and creates graphics files.
The Interpreter	The interpreter includes the traditional mechanisms and structures for this type of program. The memory is organized in four spaces: pointerspace - containing the car\|cdr cells, the 64 bits integers (allowing 64 bits arithmetic independently of the 32 or 64 bits processor architecture) and 64 bits floating point, stringspace - containing the names of atoms and the character strings, binaryspace containing structures, buffers, and API objects, and finally the dynamic stack for calling the functions. Pointer, string and binary spaces are pre-allocated at the startup of the interpreter and used gradually in the course of operation, while garbage collector algorithms recover space in case of exhaustion. The car and cdr pointers are full word (32 or 64 bits) variables, making possible the use of the maximum of the addressable space authorized for a process by the operating system and the processor. The version 8 interpreter has about 400 intrinsic compiled functions, as well as a library loaded at startup defining more than 60 additional functions dedicated mostly to debugging and edition. Moreover, the interpreter includes natively the following possibilities: Multi-threading, with independence of the environments of each thread and communication between those; Foreign Function Interface allowing to call C APIs accessible under the form of shared objects or DLL; Possibility of developping C or C++ plugins or extensions to the language which can be loaded and unloaded dynamically; Process Handling and IPC; Streams, Pipes and Sockets handling;
Command Line	Although wwlisp is also suitable to be included as command or scripting interpreter in other applications like CAD-CAM, 3D game engine, etc... it is primarily useable as a command line utility or an interactive program. As command line utility, the interpreter can be used directly or in a normal bash shell script, and be supplied with options to control its initialization and execution, and also with applicative parameters which will be passed to the application program. The interpreter can also be used as shell interpreter replacing bash itself. In that case, all the coding can reside in just one file, the script file. Such a script can be used as cgi-bin for example. How to start the interpreter and dialog with it.
Lexical Conventions	Conventions used in this manual, and special meanings for some characters in the language.
Index of Classes and Classless Functions	The class definitions describe the methods specific to each class. In each class, all the methods defined in its ancestor classes are also callable, but they are not repeated in the documentation. Classless Functions binary class directory file float integer library process readerprinter scalar socket specialchar stream string symbolicsocket symbolicstream symbolicstring thread unsignedinteger
Errors and Diagnostics	Non-fatal errors and usual syntax faults, and ways to correct them. See also the list of the fatal errors of operation and the diagnostics to be posed.

Command Line

The interpreter can be started from a shell prompt by just typing wwlisp, in which case the execution parameters are set by default in function of the most common needs, but it is also possible to change those parameters in order to load and run larger programs, or to use other initialization files. If a file to be executed is not given as last argument in the command line, the intepreter starts in interactive mode, allowing the user to dialog with it.

SYNOPSIS

wwlisp [-bbinaryspacesize] [-C] [-d] [-g] [-G][-hehtsize] [-iinitfile] [-j] [-khistorysize] [-o] [-ppointerspacesize] [-sstringspacesize] [-Sstacksize] [-qmsgqueuesize] [-tmaxstringlength] [-v] [-V] [-x] [file]

DESCRIPTION

Each option letter must be followed directly by the argument value, without intervening space, like in -b20000000 or in -i/usr/local/bin/init.lsp. Options may not be grouped.

-b	binary space size in bytes
-C	check consistency (only valid if compiled with -D_DEBUG)
-d	causes a minidump and thread abort while handling a SIGSEGV, allowing a better debug while running the interpreter as a daemon or service
-g	signal garbage collection by a message on stderr
-G	tells the garbage collector to be more aggressive and recycle also the symbolic atoms which are not bound, have no properties and are not referenced. This is useful when processing large symbolic streams, but still experimental in version 8.2.
-h	size in pointers (32 or 64 bits) of the hash table of the base environment
-i	path and name of the initialization file
-j	jump when abort instead of unwinding the stack
-k	keyboard history size in lines
-o	ignore the stack overflow control, and thus crash if a Stack Overflows
-p	pointer space size in bytes
-s	string space size in bytes
-S	stack space size in bytes
-q	interthread message queue size in 32 or 64 bits words
-t	maximum string length in bytes
-v	verbose initialization
-V	do not install the SIGSEGV handler, and thus crash if a Segmentation Violation occurs
-x	suppress banners, trailers and prompt, allowing a silent use as in a cgi-bin script

ENVIRONMENT VARIABLES

The environment variable LISPINIT, normally defined in the system profile, contains some system-wide defaults, typically: "-i/usr/local/bin/init.lsp". This variable can be modified in order to change the system-wide defaults for wwlisp.

SHELL SCRIPTS

The interpreter can be used as a script interpreter like in the following example, where the file myscript contains:

#!/usr/local/bin/wwlisp -b20000000 -s20000000
(defun testfunc ()
    (print 'Hello-World)
    (print(getargv 0))
    (print(getargv 1))
    (print(getargv 2))
    (print(getargv 3))
    (print(getargv 4))
    )    
(testfunc)

The file is made executable by chmod u+x myscript and invoked by doing ./myscript scriptarg, which gives as result the following display:

Hello-World
"/usr/local/bin/wwlisp"
"-b20000000 -s20000000"
"./myscript"
"scriptarg"
nil

In this case, (getargv 0) retrieves the path to the interpreter itself, (getargv 1) retrieves a string containing all the interpreter arguments given on the first line of the script, (getargv 2) retrieves the script name ./myscript, (getargv 3) retrieves the first of the arguments of the script itself: scriptarg, (getargv 4) retrieves the next argument of the script, which was nothing in this case. In this example the two arguments -b20000000 and -s20000000 will set the binary and string spaces to 20.000.000 bytes each.

How to Start Programming

Start the interpreter at the command prompt, by typing wwlisp. Then, at the interpreter prompt, type (edit hello). The editor will start and show a template of empty function named hello:

(defun hello nil(prog nil))

Then add all the desired forms in the function. Then save the file and quit the editor; the edited file shall be reloaded in the interpreter. By the way, the default editor will be kedit if KDE is the installed desktop environment, and vi otherwise. Any other editor can be chosen by customizing the file /usr/local/bin/init.lsp.

Then the function can be invoked by doing:

(hello)

In case of error, press any key to enter the debugger. For help, just type ? or help or (help) or :help.

To save the program, do (saveall "filename.lsp"), where filename is a file name with a relative or absolute path. That file can be reloaded later on, by doing (load "filename.lsp"). That's it.

Lexical Conventions

Conventions In this Manual

Reserved symbolic atoms, class names, functions and methods, reserved property names, reserved global variables are mentionned in bold in this documentation.

Functions and methods arguments in prototypes are in italic.

In the functions and methods arguments descriptions, all the arguments are enumerated, separated by a commas. All the arguments are by default mandatory (and sometimes this is redundantly mentionned). When an argument is optional, this is always explicitely indicated.

Conventions In the Language

wwlisp is case sensitive; two symbolic atoms of which the names are respectively expressed in lowercase and uppercase are totally different entities; there is no such thing as a 'print-name', ie the name and the symbol are the same thing. Some characters have a special meaning.

(.....)	left and right parenthesis: indicate the beginning and the ending of a list
'	simple quote: is a shorter form of the function (quote <something>), is implemented as a read-macro
"......"	double quotes mark the beginning and the ending of a string; use two double quotes to indicate a double quote in the body of a string
\|......\|	vertical bars mark the beginning and the ending of a weird atom, ie an atom of which the name embeds whitespace characters; use two vertical bars to indicate a vertical bar in the body of a weird atom name
;	semi-colon: indicates that the rest of the line up to the line-feed is a comment and must not be parsed
whitespace	characters like space, horizontal and vertical tab, line-feed, carriage-return, form-feed; they separate atoms except when found inside the body of a weird atom name; they are used as normal characters when found in the body of a string
EOF	when EOF is found when reading a symbolicstream or symbolicsocket, all the pending parenthesis are automatically closed and a useable form is returned
~	tilde: shorter form of (eval <something>)

Errors and Diagnostics

Recoverable Errors

The interpretation errors are recoverable, ie the interpreter remains in control and the user can debug. Most of those errors can be caught by a catch function with a label equal to the symbolic index of the error, except when a recovery would lead to recursion, like stack overflow or segmentation fault or has no meaning like escaped go. catch with a label 'any-condition can intercept all the interceptable errors.

The error messages are stored in a list bound to the symbol *errormessages* and can be changed, translated or augmented at will.

Fatal Errors

Some fatal errors are caused by the exhaustion of a particular resource, like process heap, or pointer, string or binary space, etc... The cures are either to restart the interpreter with different command line parameters, or to change the programs in order to use the resources more conservatively. The error message will indicate the relevant parameter.

The other fatal errors are really fatal and caused by real bugs in the interpreter itself. In that case, as this software is under GNU/GPL, you can recompile it with -D_DEBUG and debug it yourself. Or you can write a sample program causing the fault and send it to the author via the bugtrack at SourceForge.net.

Further Development

Help is welcome! Please feel free to imagine, design, develop, document or debug (or do whatever can help) new basic or derivated classes, which can be added in the interpreter, as native classes or as plugins (shared object libraries). SSL/TLS would be an interesting new class. Also imaginary numbers, vectors, matrices, quaternions... Also, real installation packages for Debian, SuSE, RedHat, with automatic dependencies checking and resolving, would be of a great interest...And any enhancement or debugging brought to the existing base would be welcome as well.