A web microframework prototype for Jim Tcl. Provides a rough implementation of the HTTP protocol as well as routing, templates, JSON generation and parsing, an HTML DSL and persistent storage powered by SQLite3.

Components

The components listed below work in Tcl 8.5, Tcl 8.6 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.

Filename	Function	Version
arguments.tcl	Command line argument parsing.	1.0.0
example.tcl ¹	A sample web server that demonstrates the use of the other components.	—
entities.tcl	A dictionary mapping characters to HTML entities.	1.0.0
html.tcl	A DSL for HTML generation. Requires entities.tcl.	0.2.1
http.tcl ¹	The titular web microframework. Requires mime.tcl.	0.15.1
json.tcl	JSON generation with schema support. ² JSON parsing. ³	1.3.3
mime.tcl	Rudimentary MIME type detection based on the file extension.	1.2.0
storage.tcl ¹	SQLite persistence of static variables.	0.1.0
template.tcl	tmpl_parser templating.	1.0.0
testing.tcl	A test framework with support for tcltest-style constraints.	0.1.0
tests.tcl	Tests for other components. ⁴	—

1. Jim Tcl-only.

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

3. Warning: parsing is currently slow. The jq module provides faster JSON parsing in Jim Tcl through an external binary.

4. Only the compatible components are tested in Tcl 8.5/8.6.

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 array:number
    d string
}]

Requirements

Compile Jim Tcl 0.76 or later from the Git repository. Previous stable releases (0.75 or earlier) will not work. You will need an SQLite3 development package (libsqlite3-dev on Debian/Ubuntu, libsqlite3x-devel on Fedora) to do this and optionally AsciiDoc (asciidoc on Debian/Ubuntu and Fedora) to generate the documentation (don't use --disable-docs then).

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

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

Vagrant

The development environment can be set up for you automatically if you have VirtualBox and Vagrant installed.

Run the following commands in the terminal:

git clone https://github.com/dbohdan/jimhttp.git
cd jimhttp/vagrant
vagrant up

and open http://localhost:8080/. Go to http://localhost:8080/quit to restart the server when you edit example.tcl.

Stop the VM with

vagrant halt

Run the server again with

vagrant up

License

MIT.

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

kolewu / jimhttp