Crate tcl

Source
Expand description

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::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.