Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Jim Tcl in Rust

This is the documentation site for the rust-jim project, which supplies two things:

  • The jimtcl crate, and its underlying jimtcl-sys, to enable Jim Tcl to be embedded in Rust programs.
  • Guardian Tcl, an extended version of Jim Tcl with additional commands leveraging the rich Rust ecosystem.

The rust-jim repository on Codeberg has the source code and issue tracker. Pull requests welcome!

Embedding Jim Tcl

The jimtcl crate is the primary entry point to embed stock Jim Tcl into Rust. It uses the separate jimtcl-sys crate that provides the Jim Tcl source code and low-level FFI bindings.

The API reference is the primary documentation for using this crate.

Jim is compiled and statically linked into the executable. Linking against a system-provided Jim is TBD.

Note

Currently, Jim Tcl only supports Unix-like systems. Windows suppport is planned but not yet implemented.

Crate Features

The following features control Rust integration, and are enabled by default:

  • cli — add a dependency on Clap and provide a reusable command line for Jim Tcl shells. Enables the rust-jimsh binary as well.
  • serde — add a DeserializeSeed implementation to allow Jim objects to be directly deserialized with Serde format libraries. Serialization is not yet supported, as it would require some kind of schema mechanism.

Extension Features

Each of the Jim Tcl optional extensions, except for database extensions, is exposed through a Rust crate feature, and passed through to a correpsonding feature on jimtcl-sys. They are all enabled by default.

  • aio
  • array
  • binary
  • clock
  • ensemble
  • eventloop
  • exec
  • file
  • glob
  • history
  • interp
  • json (enables both json and jsonencode extensions)
  • namespace
  • oo
  • pack
  • package
  • posix
  • readdir
  • regexp
  • signal
  • tclcompat
  • tree

Introducing Guartcl

Guardian is Jimmy Olsen with superhero gear.

Guartcl is Jim Tcl with extra bits.

Guardian Tcl is provided by the guartcl crate, and supplies a guarsh binary to run Guardian Tcl scripts.

Commands

Guardian Tcl currenly adds one ensemble command, parse. This command exposes subcommands to parse data from a variety of formats directly into nested Tcl data structures.

parse

The parse command has the following usage:

parse <format> <data>
  • <format> can be any of json, toml, or yaml.
  • <data> is a Tcl string containing the raw data to deserialize.

For example, to deserialize the contents of the $conf_src variable as JSON, you can write:

set config [parse json $conf_src]

These commands are wrappers around the corresponding Serde deserializers.