Trait texlang::vm::Handlers

pub trait Handlers<S: TexlangState> {
    // Provided methods
    fn character_handler(
        input: &mut ExecutionInput<S>,
        token: Token,
        character: char
    ) -> Result<(), Box<Error>> { ... }
    fn math_character_handler(
        input: &mut ExecutionInput<S>,
        token: Token,
        math_character: MathCode
    ) -> Result<(), Box<Error>> { ... }
    fn undefined_command_handler(
        input: &mut ExecutionInput<S>,
        token: Token
    ) -> Result<(), Box<Error>> { ... }
    fn unexpanded_expansion_command(
        input: &mut ExecutionInput<S>,
        token: Token
    ) -> Result<(), Box<Error>> { ... }
}

Implementations of this trait determine how the VM handles non-execution-command tokens.

The main loop of the VM reads the next expanded token and performs some action based on the token. Many cases are handled automatically based on the semantics of the TeX language:

token type	example	action
execution command	\def	run the command
variable command	\count	assign a value to the corresponding variable
token alias	\a after \let\a=a	run the main VM loop for the token that is aliased
begin group character	{	begin a group
end group character	}	end the current group

Note that the first three rows can arise from both control sequences and active character tokens.

The remaining cases are not specified by the TeX language but instead by the business logic of the TeX engine being built. The behavior in these cases is specified by implementing the associated handler. These cases and handlers are:

token type	example	handler	default
character token	b	character_handler	do nothing
undefined command	\b where \b was never defined	undefined_command_handler	return an undefined control sequence error
unexpanded expansion command	\the in \noexpand\the	unexpanded_expansion_command	do nothing

Each of the handlers has the same function signature as an execution command.

Provided Methods

fn character_handler( input: &mut ExecutionInput<S>, token: Token, character: char ) -> Result<(), Box<Error>>

Handler to invoke for character tokens.

This token is not invoked for tokens whose category code is begin group (1), end group (2) or active character (13). These cases are handled automatically by the VM based on the semantics of the TeX language.

The default implementation is a no-op.

fn math_character_handler( input: &mut ExecutionInput<S>, token: Token, math_character: MathCode ) -> Result<(), Box<Error>>

Handler to invoke for math character tokens.

The default implementation throws an error because math character tokens are only valid in math mode which is implemented outside of the main VM loop.

fn undefined_command_handler( input: &mut ExecutionInput<S>, token: Token ) -> Result<(), Box<Error>>

Handler to invoke for a control sequence or active character for which no command is defined.

The default implementation throws an undefined command error.

fn unexpanded_expansion_command( input: &mut ExecutionInput<S>, token: Token ) -> Result<(), Box<Error>>

Handler to invoke for expansion commands that were not expanded.

For example, in the TeX snippet \noexpand\the, this handler handles the unexpanded \the token.

The default implementation is a no-op.

Implementors

impl<S: TexlangState> Handlers<S> for DefaultHandlers