cwal: Scripting Engine Without A Language

cwal (pronounced "sea wall") is an experimental scripting engine/garbage-collection library implemented in C (which is where the "c" comes from - its original name was "sewal"). cwal itself does not provide a scripting language, only the pieces needed for a custom script parser to manage its memory, scoping, variables, a value type system with which to communicate values between script code and native code, etc. (That said, see s2 for a scripting language built on top of cwal.) It could also be used as a form of garbage collector for client apps, independent of any scripting-related functionality (there's a big overlap). cwal uses a hybrid of reference-counting with C++-like scoping for deterministic finalization and supports the proper tracking and cleaning up cyclic structures.

cwal was started in late July, 2012 as a fork of cson, a JSON library for C, from which cwal initially derived its data type system and much of the related code. It was largely inspired by the TH1 scripting engine originally found in the Fossil SCM, and one of the goals of cwal is to be used as the basis for such app/library "glue languages," primarily with the goal of scripting unit tests (TH1's original purpose). cwal represents, without a doubt, my most intricate C code to date (and is amongst the cleanest, as well).

License: Dual Public Domain/MIT. The underlying JSON parser code has a BSD-ish "keep this copyright in place" license with a "do no evil" subclause. (Otherwise evildoers must be sure to replace the underlying parser before using this code. Alternately, evildoers may disable those bits at build-time: see cwal_config.h for details.)

Author: stephan beal

Code status: highly experimental, but has been in heavy use since 2013. The core engine works quite well when used as advertized. Work on the th1ish scripting engine (based on cwal, of course) has proven that cwal's general lifetime model works. More recently (summer, 2014), s2 shows even more promise, superseding th1ish in essentially every way. The verdict is still out as to whether cwal can really scale to be able to be useful in any "really interesting" scripting work, but has been shown to at least be viable for such tasks as creating web sites. e.g.,'s static HTML pages are created, in part, with s2, pushing cwal well beyond any initially envisioned uses.

See also: download, cwal_gc, HowTo, MemoryModel, DataTypes, ToDo, th1ish, cwal_weak_ref, s2, CwalBestPractices, MaybeSomeday.

The primary properties of cwal include:

Primary misfeatures: