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).