lspx

a. fox

a lisp take on LuaX

!! THIS SOFTWARE IS ALPHA QUALITY. USE AT YOUR OWN RISK

Building

1. install roswell (or install SBCL and manually configure quicklisp)
2. $ ros install sbcl-bin/2.4.0 && ros use sbcl-bin/2.4.0
3. $ git clone https://dev.focks.website/focks/lspx ~/common-lisp/lspx
4. $ cd ~/common-lisp/lspx && make

Additional backends

This system supports building with a different, faster server backend named woo. To build with this backend, you need to ensure that libev is first installed on your system, then:

$ cd ~/common-lisp/lspx && make woo

Using

Usage: lspx [-h|--help] [--version] [--backtrace] [--log LEVEL] [-l|--load FILE]
            [-r|--root WEB ROOT] [-s|--static-path STATIC ROOT] [-t|--template-path TEMPLATE ROOT]
            [-p|--port PORT]

Available options:
  -h, --help                        prints this help
  --version                         prints the webserver version
  --backtrace                       displays the lisp error and backtrace as HTML
  --log LEVEL                       sets the log level. supported levels are: info, debug, error, trace
  -l, --load FILE                   loads specified lisp file before starting the server
  -r, --root WEB ROOT               specify web root. defaults to current directory
  -s, --static-path STATIC ROOT    
                                    path to static assets. defaults to ./static
  -t, --template-path TEMPLATE ROOT
                                    path to LSPX templates. defaults to ./templates
  -p, --port PORT                   port to use for server. defaults to 5000

$ ./lspx -r ./my-site

Setup

After building the binary, you need to do a bit of work to setup your site.

Pages

All pages are expected to live in whatever directory is specified as the webroot (supplied with -r. Assumes the current directory if not provided). Page files are regular lisp files with the extension "lspx". When the HTTP request comes in the server looks up what file, if any, matches the path. If an lspx file is found it gets compiled and loaded into memory. (my-site.com = web-root/index.lspx; my-site.com/toplevel = web-root/toplevel.lspx; my-site.com/directory/ = web-root/directory/index.lspx; my-site.com/toplevel/subpage = web-root/toplevel/subpage.lspx; etc, etc, etc)

A reader macro is inserted into the default readtable that allows for html to be written directly alongside lisp. It wraps up all HTML in a function that returns it as a string. Lisp statements are able to be written in-line with the HTML, allowing for fast, dynamic webpages. (see provided examples)

Pages can be edited or changed in-place and the server will detect that the compiled version is out of date and will recompile it, and serve the newly loaded copy. This makes deploying updates dead easy! Just drop any new LSPX files into your web root and you're done!

Static Files

Static files are able to be served directly to the users. The root for static files can be specified by the -s command line option. If not provided it defaults to ./static.

Templates

A homegrown templating system is available for defining your own HTML tags. The root for template files can be specified by the -t command line option. If not provided it defaults to ./templates.

Template files can be nested any amount of levels deep, they will be loaded regardless. They are expected to have the lspt extension (LSPX Template), if they do not have this extension LSPX will not discover them.

Template files at their heart are just lisp files that contain at least one deftemplate form. They get loaded after the --load option is processed so any functions declared in there will be available in any template.

deftemplate can be provided a format-compliant string, or a function that accepts at least one parameter that represents the inner HTML.

Templates are also capable of being passed parameters thru HTML tag attributes. This allows for customizing templates without having to rewrite anything after the fact.

an example of what I'm referring to:

(deftemplate "MyTag" (inner &key parm1 parm2)
  (if parm1
    (format nil "<div>~A</div>" inner)
   (format nil "<strong>parm2: ~A</strong>~%~A" parm2 inner)))

<MyTag parm1="value" parm2="Hi!">
  <p>Testing!</p>
</MyTag>

Tips and Tricks

;; TODO

License

GNU GPLv3