
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.


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 create 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 and copy the 'spl_modules/' directory to
the same location. Add somthing like that to your apache config:

	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 )

There are also two bigger WebSPL demo applications:

	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. On 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. This 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 been 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).

