Crate tcl

High-level bindings to Tcl 8.6

The crate tcl is bindings to Tcl programming language, aiming at providing safe and easy to use API.

Quickstart

std::Convert between Rust values and Tcl objects.

use std::convert::TryFrom;
use tcl::*;

let obj = Obj::from( 0 );
assert_eq!( obj.to_string(), "0" );
assert_eq!( i32::try_from( obj )?, 0 );

let obj = Obj::from( 1 );
assert_eq!( obj.as_i32(), 1 );
assert_eq!( obj.as_f64(), 1.0 );
assert_eq!( obj.as_bool(), true );

let obj = Obj::from(( false, 42, "answer".to_owned() ));
assert_eq!( obj.to_string(), "0 42 answer" );
assert_eq!( <(bool,i32,String)>::try_from( obj )?,
    (false, 42, "answer".to_owned() )
);

let v = vec![ "alpha".to_owned(), "beta".to_owned(), "gamma".to_owned() ];
let obj: Obj = v.clone().into();
assert_eq!( obj.to_string(), "alpha beta gamma" );
assert_eq!( Vec::<String>::try_from( obj )?, v );

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert( "alpha".to_owned(), 1 );
map.insert( "beta" .to_owned(), 2 );
map.insert( "gamma".to_owned(), 3 );

let obj: Obj = map.clone().into();
assert_eq!( HashMap::<String, i32>::try_from( obj )?, map );

User-defined types deserialized / try_from Tcl objects.

use tcl::*;

#[derive( Clone, PartialEq, Debug, serde::Deserialize )]
#[derive( TryFromDe )]
struct Struct{ a: i32, b: bool, c: f64 }

let obj = Obj::from( "a 1 b false c 3.14" );
let v: Struct = from_obj( obj.clone() )?;
assert_eq!( v, Struct{ a: 1, b: false, c: 3.14 });

let v: Struct = obj.clone().try_into()?;
assert_eq!( v, Struct{ a: 1, b: false, c: 3.14 });

Use Tcl<T> to store Rust values in Tcl Objs, an vice-vesa.

use std::convert::TryFrom;
use tcl::*;

let obj = Tcl::new_obj( vec![ 1, 1, 2, 3, 5, 8 ]);
let tcl_obj = Tcl::<Vec<i32>>::try_from( obj )?;
assert_eq!( tcl_obj.into_inner(), vec![ 1, 1, 2, 3, 5, 8 ]);

Run Tcl scripts

use tcl::*;

let interpreter = Interpreter::new()?;
let a = 3;
let b = 7;
let c = interpreter.eval(( "expr", a, "*", b ))?;
assert_eq!( a*b, c.as_i32() );

Register Rust functions as tcl commands, the unsafe way

use tcl::*;

#[proc] fn mul( a: i32, b: i32 ) -> TclResult<i32> { Ok( a * b )}

let interpreter = Interpreter::new()?;
unsafe { // it's safe for `#[proc] fn`.
    interpreter.def_proc( "mul", mul );
}
let c = interpreter.eval( "mul 3 7" )?;
assert_eq!( c.as_i32(), 21 );

Register Rust functions as tcl commands, the safe way

use tcl::*;

let interpreter = Interpreter::new()?;

let cmd = tclfn!( &interpreter, /*cmd: "mul", args: "",*/
    fn mul( a: i32, b: i32 ) -> TclResult<i32> { Ok( a * b )}
);

let c = interpreter.eval( "mul 3 7" )?;
assert_eq!( c.as_i32(), 21 );

Register Rust closures as tcl commands

use tcl::*;

let offset = 0;
let interpreter = Interpreter::new()?;

let cmd = tclosure!( &interpreter, /*cmd: "mul", args: "",*/
    move |a: i32, b: i32| -> TclResult<i32> { Ok( a * b + offset )}
);

let a = 3;
let b = 7;
let c = interpreter.eval(( "eval", cmd, a, b ))?;
assert_eq!( c.as_i32(), 21 );

Re-exports

• pub use interp::CodeToResult;
• pub use interp::Interpreter;
• pub use interp::Interp;
• pub use interp::ObjCmdProc;
• pub use obj::Obj;
• pub use obj::incr_ref;
• pub use obj::decr_ref;
• pub use ext::Tcl;
• pub use ser::Serializer;
• pub use ser::to_c_str;
• pub use ser::to_string;
• pub use error::IntoTclError;
• pub use error::TclError;
• pub use error::TclResult;

Modules

• error
  All error types returned by this crate are defined in this mod.
• ext
  Provides an extention to Tcl values: Tcl<T>.
• interp
  Tcl interpreter.
• obj
  An overview of Tcl values, aka Objs.
• reexport_clib
  The following items will be seen in tcl_derive’s proc macros. Let’s reexport them from crate clib, otherwise the crate tcl’s users will depend on clib too.
• ser
  Serialize Obj into Tcl string.

Macros

• tclfn
  Helps to register rust functions as Tcl commands, or Tk event callbacks.
• tclosure
  Helps to register rust closures as Tcl commands or Tk event callbacks.

Structs

• DictIter
  An iterator that iterates each key-value pair.

Traits

• UnwrapOrAbort
  Aborts the program instead of panic!() in FFI callbacks.

Functions

• from_obj
  Deserialize an instance of type T from a Tcl obj.

Attribute Macros

• proc
  A proc macro attribute for filling the gap between ObjCmdProc functions and Rust functions with “normal” input arguments.

Derive Macros

• TryFromDe
  Derives std::from::TryFrom<tcl::Obj>, based on serde::Deserialize.