What is SPL ?
=============


Overview
--------

SPL is an embeddable programming language with a wide range of features:

	* complete stateful. It is at any point possible to interrupt
	  a running SPL script, dump its entire state to disk and resume
	  later on.

	* feature-rich. SPL has native support for hashes and arrays, regular
	  expressions, object oriented programming, etc.

	* dynamic. SPL is a fully dynamic language - with all the advantages
	  and disadvantages.

	* c-style syntax. SPL has a c-style syntax (as well as many other
	  languages such as Java, JavaScript, PHP, slang, etc). so it is easier
	  to get started.

	* advanced string lexing. SPL allows the programmer to simply embed
	  variables and complex expressions in strings and template files. E.g.
	  this is very important for rapid development of web applications.

	* well-structured backend. The SPL runtime is not just one big
	  blackbox. Instead, there is a clear and visible seperation of
	  compiler, assembler, optimizer, virtual machine, etc. This makes it
	  possible to easily adapt the library for your special needs when
	  embedding it in your applications.

	* more, more, more,..

The Name "SPL" is a left-recursive acronym and expands to "SPL Programming
Language". The name was meant to be pronounced as an acronym, but I've already
heard people pronouncing it "spell", which is also fine with me.

The SPL VM is a pure bytecode interpeter. Support for JIT compilation or
generating machine code for the host CPU is not planned and doesn't make much
sense for various technical reasons.

The entire SPL toolchain (compiler, assembler, virtual machine, etc) is pretty
small (about 100k on x86 architectures). The additional memory usage by the
applications is rather small too.

WebSPL is a pretty powerful framework for doing web application development
with SPL.

The interesting thing about WebSPL is that, other than usual CGI scripts, a
WebSPL script is not executed once for each HTTP request. Instead there is one
SPL process for each session and such a WebSPL script can pause it's execution
at any time, wait for the user to do something and continue execution as soon
as the user did something.

In addition to that there is a module package called "WSF" (WebSPL Forms) which
adds an additional abstraction layer between the application logic and the
representation as web page. With this SPL modules, web application development
becomes as easy as normal application development with well-designed widget
sets.


Why should I learn SPL ?
------------------------

Maybe you want to use some software which is either built with SPL or using SPL
as embedded scripting language (such as QCAKE - www.qcake.org). In that case
you have answered that question already.

If you are doing Web Application development you defenitely want to have a look
at the WebSPL framework (README.WEBSPL or chapter 3 in the manual). It is an
entirely new concept of writing web applications.

If you are looking for a scripting language to embed in your applications, SPL
might be a great choice. Being easy to embed and to adapt was one of the SPL
design goals.

Don't look into SPL if you want to manage a lot of binary data. After all, it
is a scripting language.

In all other cases - SPL might still be very interesting for you. It is a very
flexible and powerful programming language and maybe you find another
interesting field in which SPL is at its full strengths.


Executing SPL scripts on the command line
-----------------------------------------

Often SPL is embedded in other applications. In this cases it depends on the
application how the SPL scripts can be executed. But SPL can also be used on
the command line using the 'splrun' program. E.g.:

	splrun hanoi.spl

It is also possible to pass a small SPL script directly on the command line:

	splrun -q 'debug "Hello World!";'

SPL is not optimized for fast compilation. Often compilation of a script takes
longer than execution. If this is a problem for you, you should pre-compile
your SPL scripts to SPL bytecode files:

	splrun -x hanoi.splb hanoi.spl

Such SPL bytecode files can then be executed using the -c option:

	splrun -c hanoi.splb

With the -m option it is even possible to create executeable files with the
look and feel of compiled C programs:

	splrun -m hanoi hanoi.spl
	./hanoi

Usually it is a good idea to pass the option -e when compiling SPL scripts
(or running not pre-compiled scripts). This option enables debug symbols so
that runtime error messages are printed with the line number in which the
error was triggered. Without this option only the offset in the current
bytecode block is contained in runtime error messages.

Calling 'splrun' without any parameter prints an overview of all available
command line options.


Little dump/restore demonstration
---------------------------------

The 'splrun' runtime and the "termio" module implement some CLIB functions:

	write(text)     write the text
	clear()         clear the screen
	setpos(x,y)     set a new cursor position
	sleep()         sleep for 1 second

These functions are used by the demo 'hanoi.spl' to play a little game of
towers of hanoi: type "./splrun -d hanoi.spld hanoi.spl". 

If you interrupt the program by pressing Ctrl-C, the full VM state will be
stored in the file 'hanoi.spld'. It can be resumed where its has been
interrupted any time by calling "./splrun -R hanoi.spld".


Documentation
-------------

	README ........... This short introduction    (manual chapter 1)
	INSTALL .......... Installation Instructions  (manual chapter 2)
	README.LANG ...... Language Reference Manual  (manual chapter 3)
	README.WEBSPL .... WebSPL and WSF Tutorial    (manual chapter 4)
	spldoc/ .......... SPL Module Reference       (next manual chapters)
	README.API ....... C API Reference            (the last chapter)

The module references are built using SPLDOC. Simply run 'make spldoc' to
create the "spldoc/" directory with the module documentations.

The SPL Reference Manual is automatically generated from this sources. The
PDF can be downloaded from the SPL homepage, a "make spldoc" also creates the
"manual.tex" file.


WebSPL
------

WebSPL makes use of the dump and restore features of SPL and creates a state
over the stateless HTTP protocol. Applications can simply generate a webpage
and then dump to disk and wait for the user to do something and resume when
the user sends a new request.

Install 'webspl.cgi' in your cgi-bin, copy the 'spl_modules/' directory to
the same location and create a 'webspl_cache/' directory in cgi-bin as well.
This directory must be writable by the apache user, it is used for dump files.
Add somthing like this to your apache config (httpd.conf):

	AddType application/x-httpd-webspl .webspl
	Action application/x-httpd-webspl /cgi-bin/webspl.cgi

You might also want to restrict access to files such as your templates to
prohibit users from simply downloading them as ASCII files.

Note that 'webspl.cgi' needs write-permissions in a subdirectory 'webspl_cache'
of the directory which contains 'webspl.cgi'. For just trying out WebSPL, you
can also simply start a seperate apache instance in the SPL source directory:

	httpd -d $PWD -c "DocumentRoot $PWD" -f httpd.conf
	mozilla http://localhost:3054/webspl_demo/friends.webspl
	mozilla http://localhost:3054/webspl_demo/wsfdemo.webspl
	mozilla http://localhost:3054/webspl_demo/wsfgraph.webspl
	mozilla http://localhost:3054/webspl_demo/wsf_dialog.webspl
	kill $( cat apache.pid )

The 'example-apps' package from the SPL webpage contains some additional
SPL and WebSPL demo applications. E.g. the 'cfpmanager' and 'splticket'
applicationes:

	mozilla http://localhost:3054/cfpmanager/cfpmanager.webspl
	mozilla http://localhost:3054/splticket/splticket.webspl

But before you can use them, you need to run the 'setup.sh' script
in the 'cfpmanager' or 'splticket' directory respectively.

Instead of apache you can also use the native WebSPL HTTP server. It does
not support stuff such as directory indexes and is not optimal for static
content, but is really fast for executing WebSPL scripts because it can hold
the sessions in memory and only dump them to disk when it is required and it
caches the SPL VM bytecode and so avoids redundant recompilations of the same
source file:

	./webspld

For best performance it is recommended to use the WebSPL HTTP server for the
WebSPL scripts and Apache for the rest. One way of integrating them is using
the Apache reverse proxy module.

Both WebSPL runtimes (the cgi script and the HTTP server) are looking for
files named 'webspl.conf' in the script directory and all parent directories.
This webspl.conf files can be used to configure the WebSPL runtime environemnt
and particular WebSPL scripts. These files contain sections, each section
starting with '[ filename-pattern ]', containing key-value pairs:

	[ foo-*.webspl ]
	spl.expirelocation = /expired.html

	[ bar-*.webspl ]
	spl.sessioncookie = bar_sid
	spl.respawnsessions = 1

The configuration variable 'spl.expirelocation' contains a URL. Browsers will
be redirected to that URL when the User is trying to resume an expired session.

The configuration variable 'spl.sessioncookie' contains the name of a cookie
which then can be used to pass the session-id (instead of the 'sid' query
string variable).

The configuration variable 'spl.respawnsessions', when set to 1, lets the
WebSPL framework automatically start a new session when the session passed by
the browser has expired.

Any key-value pairs can be specified in the webspl.conf files. Only the few
described here are used by the webspl runtime environment, but others can be
interpreted by modules or applications (see 'cgi.config' in the module
documentation of the "cgi" module).