spock

Introduction

SPOCK is a compiler and runtime system supporting most of R5RS Scheme. You can use it either by statically generating JavaScript files from Scheme source files or by translating s-expressions containing Scheme code on the fly.

This extension is still in a very early state and is likely to contain numerous bugs.

Programming interface

State management

Compilation of Scheme to JavaScript is controlled by a state object that specifies options relevant to the translation process together with a syntactic environment, i.e. the macro-definitions available to the code to be compiled. Depending on the use of the compiler, it must be possible to explicitly create a new state or re-use an existing one. For example, in a web-server, one usually needs a state local to the current request - syntactic definitions and compilation options should not necessarily be shared between multiple requests.

Compilation options

Compilation options are given as a list of symbols, where some symbols must be followed by an argument:

Option

Argument

Meaning

source

show source forms

expand

show forms after macro-expansion

canonicalized

show forms after canonicalization

optimized

show forms after optimization

cps

show forms after CPS-conversion

strict

enable strict mode

optimize

enable optimizations

block

enable block-compilation

library-path

[DIR]

add DIR to library path or return library path

namespace

VAR

put globals into module

xref

show cross-reference

runtime

include runtime-system in generated code

library

compile runtime library

seal

wrap toplevel definitions into local scope

debug

enable debug-mode

usage

PROC

invoke PROC on usage-errors

fail

PROC

invoke PROC on compiler-errors

import

FILENAME

expand FILENAME

environment

STORE

provide syntactic environment

debug-syntax

show debug-output during expansion

verbose

show diagnostic messages

prepare

just prepare state without compiling

code

EXP

code to be compiled instead of file

output-file

FILENAME

specify output-file

Note that the argument to the library-path option may be omitted, which means it must be the last element in the option list.

make-spock-state

[procedure](make-spock-state OPTION ...)

Creates a fresh compilation state, with settings given in OPTION .. and returns this state.

spock-state?

[procedure](spock-state? X)

Returns #t if X is a compilaton state or #f otherwise.

current-spock-state

[parameter]current-spock-state

The currently active compilation state. Defaults to #f, which means a new state will be created automatically for the next compilation (via <script>) and will be re-used on subsequent compilations.

spock

[procedure](spock FILENAME-OR-OPTION ...)

The main interface to the compiler. Any string-argument given will be taken as the name of a Scheme source file to be compiled. If the code option is given and followed by an expression, then that expression is compiled instead of reading source from files. The other options are the same as those that can be passed to make-spock-state.

spock-initialize

[procedure](spock-initialize OPTIONS ...)

Creates a compilation state using the given options and sets the value of the parameter current-spock-state.

<script>

[syntax](<script> FORM)

Compiles the Scheme (unquoted) expression FORM using the current compilation state and returns the generated JavaScript code as a string. FORM may contain sub-expressions of the form (<unscript> and <unsript-splicing>, respectively, which work similar to unquote and unquote-splicing in R5RS Scheme, but switch between code to be compiled and code or literal data to be computed in the host environment, e.g.

will return a <script> HTML element containing JavaScript code that defines a function and calls it with the argument read at execution of the <script> expression.

Note that the compiled form needs runtime support code to execute successfully. See <script-header> below.

<script-header>

[procedure](<script-header> #!key minified debug path)

Emits HTML to load the runtime system. Keyword-arguments are available to specify whether a "minified" version of the runtime library should be loaded, and whether a debug version should be used. Minified means a compressed library that can be loaded faster by the client. The debug version performs additional error checks and keeps a trace of recently invoked functions.

Note that the JavaScript files containing the runtime library need to be available to be transmitted to the client. In the usual case of web-server code generating script content this means, one of the files

should be in a location that holds files to be retrieved by the client and it should match the keyword arguments given to <script-header>. The path keyword argument can be used to override the path prefix and defaults to an empty path.

The runtime library is installed in spock subdirectory of the extension repository, which is located at the path returned by entering

chicken-install -repository

or

csi -p '(repository-path)'

Special read syntax

To make embedding of Scheme code fragments easier, read syntax is available that simplifies the use of the <script>:

In compiled code, you must explicitly load the spock extension to make the read-syntax available by passing -X spock to the compiler and the spock module must be imported.

Using the static compiler

The compiler takes one or more Scheme files are translates them into a single JavaScript file, writing it by default to stdout. You can use the -o option to specify a file into which the code should be written instead. The compiler understands most of the options that can be given to make-spock-state, enter

Authors

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.