molt-forked

Crates.iomolt-forked
lib.rsmolt-forked
version0.4.5
sourcesrc
created_at2024-06-24 13:30:07.44307
updated_at2024-06-26 18:35:42.44053
descriptionEmbeddable TCL interpreter for Rust applications (personal forked)
homepage
repositoryhttps://github.com/zao111222333/molt-forked
max_upload_size
id1282249
size488,767
Junzhuo ZHOU (zao111222333)

documentation

https://docs.rs/molt-forked

README

Molt-forked

Crates.io

This is a forked version of molt, a embeddable TCL interpreter for Rust applications. The original repository is no longer actively maintained, and this version aims to continue its development, fix bugs, and add new features. WASM runtime support. See demo.

TODO

  • Full tcl 8.6.14 support
  • Update molt-app to latest rustyline version

New in Molt-forked 0.4.1

  • The subcommands now is static, we can use gen_subcommand! macro to init SubCommand.

New in Molt-forked 0.4.0

  • WASM runtime support. See demo and you can find that the size of compiled WASM binary is only ~600k.

  • Remove ContextMap and related attributes / function parameters in Interpreter. Now the definiton of Interpreter is Interp<Ctx> (with user-defined generic Ctx), we can access Interpreter's Context directly via interp.context.

  • The native commands now is static, we can use gen_command! macro to init Command.

    The benefit is that molt-fork can use match block to implement token matching, rather than HashMap

  • New document (The Molt Book, Code Description) is not unimplemented yet.

Benchmark Result

  • Command: cd molt-app && cargo run --release bench ../benchmarks/basic.tcl

  • Platform: Intel Xeon 6348 CPU

molt-forked 0.4.0 (time unit in Nanos) molt 0.3.2 Speedup (×) Benchmark
89 208 2.34 ok-1.1 ok, no arguments
90 207 2.3 ok-1.2 ok, one argument
97 219 2.26 ok-1.3 ok, two arguments
119 209 1.76 ident-1.1 ident, simple argument
209 402 1.92 incr-1.1 incr a
158 311 1.97 set-1.1 set var value
201 348 1.73 list-1.1 list of six items

===================== Below is Origin Document =====================


Molt -- More Or Less TCL

MoltLogo.png

Molt is a minimal implementation of the TCL language for embedding in Rust apps and for scripting Rust libraries. See The Molt Book for details and user documentation, and docs.rs/molt for the Rust API.

Mazegen: An Example

See Mazegen as an example of using Molt to provide a TCL interface for real Rust APIs. Mazegen is a collection of maze generation code and related infrastructure, with a Molt interface as an aid for debugging and experimentation. Among other things, Mazegen includes:

  • A simple binding to (a small part of) the rand::thread_rng crate
  • The smallest beginning of a binding to the image crate (more to come)

New in Molt 0.3.1

  • molt_throw! macro
  • New Exception methods
  • Access to environment variables via the env() variable
  • Additional TCL commands

See the Annotated Change Log in the Molt Book for the complete list of new features by version.

Coming Attractions

At this point Molt is capable and robust enough for real work, though the Rust-level API is not yet completely stable. Standard Rust 0.y.z semantic versioning applies: ".y" changes can break the Rust-level API, ".z" changes will not.

  • Additional TCL commands
  • Testing improvements
  • Documentation improvements
  • Feature: Regex and Glob pattern matching by Molt commands

Why Molt Exists

Using Molt, you can:

  • Create a shell interpreter for scripting and interactive testing of your Rust crates.
  • Provide your Rust applications with an interactive REPL for debugging and administration.
  • Extend your Rust application with scripts provided at compile-time or at run-time.
  • Allow your users to script your applications and libraries.

See the molt-sample repo for a sample Molt client skeleton.

Molt and Standard TCL

Molt is intended to be lightweight and require minimal dependencies, so that it can be added to any project without greatly increasing its footprint. (At present, the core language is a single library create with no dependencies at all!) As such, it does not provide all of the features of Standard TCL (e.g., TCL 8.6).

At the same time, Molt's implementation of TCL should be consistent with TCL 8.6 so far as it goes. Some archaic commands and command features are omitted; some changes are made so Molt works better in the Rust ecosystem. (E.g., Molt's notion of whitespace is the same as Rust's.) All liens against Standard TCL are documented in the The Molt Book.

No effort has been made to make the Rust-level API for extending Molt in Rust look like Standard TCL's C API; rather, the goal is to make the Rust-level API as simple and ergonomic as possible. Note: A big part of this effort is defining and refining the Rust API used to interact with and extend the interpreter. If you have comments or suggestions for improvement, please contact me or write an issue!

Building and Installation

The easiest approach is to get the latest Molt through crates.io. Look for the molt, molt-shell, and molt-app crates, or add them to your dependencies list in cargo.toml.

To build Molt:

  • Install the latest stable version of Rust (1.38.0 at time of writing)
  • Clone this repository
  • To build:
$ cd .../molt
$ cargo build
  • To run the interactive shell
$ cargo run shell
  • To run just the language test suite
$ cargo run test molt/tests/all.tcl

Since Molt 0.2.0 the language tests are also run by cargo test; however, it's much easier to see the output of the individual tests using the above command.

Dependencies

At present, the only dependency required by the Molt core is indexmap.

Acknowledgements

I've gotten help from many people in this endeavor; here's a (necessarily partial) list.

  • Mary Duquette, for the Molt logo
  • Jonathan Castello, for general Rust info
  • Kevin Kenny, for help with TCL numerics and general encouragement
  • Don Porter, for help with TCL parsing
  • rfdonnelly, for the crates.io badge, etc.
  • Coleman McFarland, for improvements to molt_shell::repl.
  • dbohdan, for TCL command implementations and advice.
  • Various folks from users.rust-lang.org who have answered my questions:
    • Krishna Sannasi, for help getting Value to work with arbitrary user data types
    • Yandros, for pointing me at OnceCell and UnsafeCell.
    • jethrogb, for help on how to use Ref::map to return a Ref<T> of a component deep within a RefCell<S> from a function. (Mind you, once I got it working and gave it a try I tore it out again, because of BorrowMutError panics. But I had to try it.)
Commit count: 570

cargo fmt