Trait texlang::vm::TexlangState

pub trait TexlangState: Sized {
    // Provided methods
    fn cat_code(&self, c: char) -> CatCode { ... }
    fn end_line_char(&self) -> Option<char> { ... }
    fn post_macro_expansion_hook(
        token: Token,
        input: &ExpansionInput<Self>,
        tex_macro: &Macro,
        arguments: &[&[Token]],
        reversed_expansion: &[Token]
    ) { ... }
    fn expansion_override_hook(
        token: Token,
        input: &mut ExpansionInput<Self>,
        tag: Option<Tag>
    ) -> Result<Option<Token>, Box<Error>> { ... }
    fn variable_assignment_scope_hook(state: &mut Self) -> Scope { ... }
    fn recoverable_error_hook(
        vm: &VM<Self>,
        recoverable_error: Box<Error>
    ) -> Result<(), Box<Error>> { ... }
}

Implementations of this trait may be used as the state in a Texlang VM.

The most important thing to know about this trait is that it has no required methods. For any type it can be implemented trivially:

struct SomeNewType;

impl TexlangState for SomeNewType {}

Methods of the trait are invoked at certain points when the VM is running, and in general offer a way of customizing the behavior of the VM. The trait methods are all dispatched statically, which is important for performance.

Provided Methods

fn cat_code(&self, c: char) -> CatCode

Get the cat code for the provided character.

The default implementation returns the cat code used in plain TeX.

fn end_line_char(&self) -> Option<char>

Get current end line char, or None if it’s undefined.

The default implementation returns Some(\r).

fn post_macro_expansion_hook( token: Token, input: &ExpansionInput<Self>, tex_macro: &Macro, arguments: &[&[Token]], reversed_expansion: &[Token] )

Hook that is invoked after a TeX macro is expanded.

This hook is designed to support the \tracingmacros primitive.

fn expansion_override_hook( token: Token, input: &mut ExpansionInput<Self>, tag: Option<Tag> ) -> Result<Option<Token>, Box<Error>>

Hook that potentially overrides the expansion of a command.

This hook is invoked before an expandable token is expanded. If the result of the hook is a non-empty, that result is considered the expansion of the token The result of the hook is not expanded before being returned.

This hook is designed to support the \noexpand primitive.

fn variable_assignment_scope_hook(state: &mut Self) -> Scope

Hook that determines the scope of a variable assignment.

This hook is designed to support the \global and \globaldefs commands.

fn recoverable_error_hook( vm: &VM<Self>, recoverable_error: Box<Error> ) -> Result<(), Box<Error>>

Hook that determines what to do when a recoverable error occurs.

If the hook returns Ok(()) then the recovery process should run. If the hook returns an error, then that error should be returned from the enclosing function and propagated through the VM.

Note that there is no requirement that an error returned from this hook is the same as the error provided to the hook. For example, when Knuth’s TeX is running in batch mode errors are logged but otherwise ignored. However if 100 such errors occur, the interpreter fails. To implement this in Texlang, the result of this function would be Ok(()) for the first 99 errors, but after the 100th error a “too many errors” error would be returned from the hook. Note that the returned error in this case is not the 100th error itself.

Implementations on Foreign Types

impl TexlangState for ()

Implementors