cwal

cwal
Login

cwal

cwal: Scripting Engine Without A Language

cwal (pronounced "sea wall") is a 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 and whcl for the scripting languages currently 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.

As of May, 2024 this project is in "retirement mode." It is still maintained, because i have lots of scripts based on it, but it's unlikely to get any significant new pieces. Related new efforts are going on in cwal's successor, essentially a reimplementation of cwal's core model in modern C++ (17+).

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: cwal has been in heavy use since 2013. Though it makes no particular API stability guarantees, its core APIs are in widespread use in my client-side code so are exceedingly unlikely to be changed in incompatible ways. The core engine works quite well when used as advertized. Work on the now-defunct th1ish scripting engine proved that cwal's general lifetime model works. More recently s2 and whcl supersede th1ish in 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., wanderinghorse.net's static HTML pages are created, in large part, with s2, pushing cwal well beyond any initially envisioned uses.

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

The primary properties of cwal include:

Primary misfeatures: