jimhttp

A collection of standalone libraries and a web microframework prototype for Jim Tcl. Most of the libraries also work in Tcl 8.x. The libraries implement command line and proc argument parsing, an HTML DSL, parsing and generating JSON, templates, and persistent storage powered by SQLite3. The web microframework provides a rough implementation of the HTTP/1.1 protocol and a routing DSL.

Components

The components listed below work in Tcl 8.5, Tcl 8.6, Tcl 8.7a3, and Jim Tcl 0.76 or later unless indicated otherwise. Each component is versioned separately. Component version numbers follow semantic versioning. A major version number of zero indicates an unstable API.

1. Jim Tcl-only.

2. Does not support Tcl 8.5.

3. Schemas define data types. See the example below.

4. Warning: parsing is fairly slow in general and extremely slow in UTF-8 builds of Jim Tcl. (Obsolete benchmark.) This may matter to you if you need to decode more than a few dozen KiB of JSON at a time. Since version 0.79 Jim Tcl can be built with a fast binary extension for parsing and encoding JSON. The jq module is an option for faster JSON parsing in earlier versions. It requires an external binary.

5. Only compatible components are tested in Tcl 8.

Use examples

http.tcl

source http.tcl

::http::add-handler GET /hello/:name/:town {
    ::http::respond [::http::make-response \
            "Hello, $routeVars(name) from $routeVars(town)!"]
}

::http::start-server 127.0.0.1 8080

http.tcl and storage.tcl

source http.tcl
source storage.tcl

::http::add-handler GET /counter-persistent {{counter 0}} {
    ::storage::restore-statics

    incr counter

    ::storage::persist-statics
    ::http::respond [::http::make-response $counter]
}

::storage::init
::http::start-server 127.0.0.1 8080

json.tcl

# This produces the output
# {"a": "123", "b": 123, "c": [123, 456], "d": "true", "e": true}
source json.tcl

puts [::json::stringify {
    a 123
    b 123
    c {123 456}
    d true
    e true
} 0 {
    a string
    c {N* number}
    d string
}]

Requirements

Compile Jim Tcl 0.76 or later from its Git repository. Stable releases prior to that (0.75 and earlier) will not work. You will need an SQLite3 development package (libsqlite3-dev on Debian and Ubuntu, libsqlite3x-devel on Fedora, sqlite3-devel on openSUSE Tumbleweed) to do this and optionally AsciiDoc (asciidoc on Debian and Ubuntu, Fedora, and openSUSE) to generate the documentation (don't use the option --disable-docs in that case).

git clone https://github.com/msteveb/jimtcl.git
cd jimtcl
./configure --with-ext="oo tree binary sqlite3" --enable-utf8 --ipv6 --disable-docs
make
sudo make install

Once you have installed Jim Tcl you can clone this repository and try out the example by running

git clone https://github.com/dbohdan/jimhttp.git
cd jimhttp
jimsh example.tcl

and then pointing your web browser at http://localhost:8080/.

License

MIT.

static.jpg photo by Steven Lewis. License: CC0.