Trait Mouth 

pub trait Mouth<ET: EngineTypes> {
    // Required methods
    fn new(aux: &mut EngineAux<ET>, state: &mut ET::State) -> Self;
    fn push_file(&mut self, f: ET::File);
    fn push_string(&mut self, s: StringLineSource<ET::Char>);
    fn push_exp(&mut self, exp: &TokenList<ET::Token>);
    fn push_vec(&mut self, exp: Vec<ET::Token>);
    fn push_slice_rev(&mut self, exp: &[ET::Token]);
    fn push_macro_exp(&mut self, exp: MacroExpansion<ET::Token>);
    fn requeue(&mut self, t: ET::Token);
    fn get_next(
        &mut self,
        aux: &mut EngineAux<ET>,
        state: &ET::State,
    ) -> Result<Option<ET::Token>, InvalidCharacter<ET::Char>>;
    fn iterate<R, E, F: FnMut(&mut EngineAux<ET>, ET::Token) -> TeXResult<Option<R>, ET>>(
        &mut self,
        aux: &mut EngineAux<ET>,
        state: &ET::State,
        cont: F,
        eof: E,
    ) -> TeXResult<R, ET>
       where E: Fn(&EngineAux<ET>, &ET::State, &mut Self) -> TeXResult<(), ET>;
    fn endinput(
        &mut self,
        aux: &mut EngineAux<ET>,
        state: &ET::State,
    ) -> Result<(), InvalidCharacter<ET::Char>>;
    fn finish(&mut self);
    fn current_sourceref(
        &self,
    ) -> SourceReference<<ET::File as File>::SourceRefID>;
    fn start_ref(&self) -> SourceReference<<ET::File as File>::SourceRefID>;
    fn update_start_ref(&mut self);
    fn line_number(&self) -> usize;
    fn get_args(&mut self) -> [Vec<ET::Token>; 9];
    fn return_args(&mut self, args: [Vec<ET::Token>; 9]);
    fn preview(
        &self,
        int: &<ET::CSName as CSName<ET::Char>>::Handler,
        cc: &CategoryCodeScheme<ET::Char>,
        esc: Option<ET::Char>,
    ) -> String;
    fn file_trace(
        &self,
    ) -> impl Iterator<Item = SourceReference<<ET::File as File>::SourceRefID>> + '_;

    // Provided method
    fn read_until_endgroup<E, F: FnMut(&mut EngineAux<ET>, ET::Token) -> TeXResult<(), ET>>(
        &mut self,
        aux: &mut EngineAux<ET>,
        state: &ET::State,
        cont: F,
        eof: E,
    ) -> TeXResult<ET::Token, ET>
       where E: Fn(&EngineAux<ET>, &ET::State, &mut Self) -> TeXResult<(), ET> { ... }
}

A Mouth provides a stream of Tokens to be processed by an engine; either by tokenizing a file or by returning the Tokens expanded by a macro. Since a TeX engine spends most of its time processing and expanding Tokens, the Mouth is likely the most performance critical component of the engine.

DefaultMouth is the default implementation of Mouth that has been quite well optimized.

During a run, most methods provided by the Mouth should not be called directly, since they circumvent the Gullet, which needs to occasionally do some bookkeeping (e.g. counting braces in an \halign). Instead, the Mouth should if possible be accessed through the EngineReferences or the Gullet only.

Note that we do not require ET:EngineTypes<Mouth=Self> - this allows for implementing your own Mouth by just wrapping an existing implementation in a new wrapper struct and pass on functionality to the inner Mouth, which would otherwise fail since ET::Mouth would be the outer wrapper struct, not the inner one.

Required Methods

fn new(aux: &mut EngineAux<ET>, state: &mut ET::State) -> Self

Create a new Mouth. May use EngineAux and State, although in practice, the default implementation doesn’t.

fn push_file(&mut self, f: ET::File)

Push a file to the Mouth. The Mouth will tokenize the file contents and return the Tokens lazily.

fn push_string(&mut self, s: StringLineSource<ET::Char>)

Push a string to the Mouth. The Mouth will tokenize the string and return the Tokens lazily.

fn push_exp(&mut self, exp: &TokenList<ET::Token>)

Push a TokenList to the Mouth - e.g. from a token register or \everypar.

fn push_vec(&mut self, exp: Vec<ET::Token>)

Push a Vec of Tokens to the Mouth. This is occasionally useful for things like \write.

fn push_slice_rev(&mut self, exp: &[ET::Token])

Push a slice of Tokens to the Mouth, assumed to be in reverse order (i.e. the first token to return is the last one in the slice).

fn push_macro_exp(&mut self, exp: MacroExpansion<ET::Token>)

Push a MacroExpansion (with arguments already read) to the Mouth. The Mouth will return the Tokens lazily, resolving the parameter tokens in the expansion in the process.

fn requeue(&mut self, t: ET::Token)

Push a Token back to the Mouth. This is useful for e.g. \futurelet, \expandafter, or when reading keywords, numbers, dimensions, etc. that often read “too far ahead” and need to back up. This method should not be called directly, but rather through EngineReferences::requeue or Gullet::requeue.

fn get_next( &mut self, aux: &mut EngineAux<ET>, state: &ET::State, ) -> Result<Option<ET::Token>, InvalidCharacter<ET::Char>>

Get the next Token from the Mouth. This method should not be called directly, but rather through EngineReferences::get_next or Gullet::get_next_opt.

Errors

fn iterate<R, E, F: FnMut(&mut EngineAux<ET>, ET::Token) -> TeXResult<Option<R>, ET>>( &mut self, aux: &mut EngineAux<ET>, state: &ET::State, cont: F, eof: E, ) -> TeXResult<R, ET>

where E: Fn(&EngineAux<ET>, &ET::State, &mut Self) -> TeXResult<(), ET>,

Iterate over the Tokens in the Mouth until cont returns false. Can be faster than repeatedly calling get_next_opt, but blocking both state changes and expanding macros. Useful for e.g. reading macro arguments or the expansion list in \def. This method should not be called directly, but rather through EngineReferences::iterate or Gullet::iterate.

Errors

fn endinput( &mut self, aux: &mut EngineAux<ET>, state: &ET::State, ) -> Result<(), InvalidCharacter<ET::Char>>

\endinput - removes the last file from the Mouth without inserting \everyeof or an EOF Token.

Errors

fn finish(&mut self)

clears the mouth at the end of a run, if desired.

fn current_sourceref(&self) -> SourceReference<<ET::File as File>::SourceRefID>

Get the current SourceReference of the Mouth (file/line/column).

fn start_ref(&self) -> SourceReference<<ET::File as File>::SourceRefID>

The mouth (can) track(s) two SourceReferences: the current one (see current_sourceref) and the position of the last Token encountered in the top-loop of an engine run that was not the result of an expansion. The latter is returned by this function. The intuition being that this one indicates the start of the macro responsible for what is currently happening, even if the Mouth is already further along because more Tokens have been eaten as arguments to a macro etc.

fn update_start_ref(&mut self)

Tells the mouth to update the start reference to the current SourceReference (see start_ref).

fn line_number(&self) -> usize

The current line number in the top-most file in the Mouth.

fn get_args(&mut self) -> [Vec<ET::Token>; 9]

We (can) reuse an array of Token vectors for macro arguments and reuse it to avoid frequent memory allocations. This method provides such an array. If it is not pushed to the mouth using push_macro_exp, later, it should be given back to the mouth using return_args later.

fn return_args(&mut self, args: [Vec<ET::Token>; 9])

Return the array of Token vectors to the mouth. Should only be called with an array that was previously obtained using get_args.

fn preview( &self, int: &<ET::CSName as CSName<ET::Char>>::Handler, cc: &CategoryCodeScheme<ET::Char>, esc: Option<ET::Char>, ) -> String

For debugging purposes, this method returns a string representation of the upcoming stuff in the Mouth.

fn file_trace( &self, ) -> impl Iterator<Item = SourceReference<<ET::File as File>::SourceRefID>> + '_

Provided Methods

fn read_until_endgroup<E, F: FnMut(&mut EngineAux<ET>, ET::Token) -> TeXResult<(), ET>>( &mut self, aux: &mut EngineAux<ET>, state: &ET::State, cont: F, eof: E, ) -> TeXResult<ET::Token, ET>

where E: Fn(&EngineAux<ET>, &ET::State, &mut Self) -> TeXResult<(), ET>,

Convenience method reading Tokens in the Mouth until the next EndGroup Token is encountered and returns that. Useful whenever a group is to be taken; e.g. when reading macro arguments. This method should not be called directly, but rather through EngineReferences::read_until_endgroup or Gullet::read_until_endgroup.

Errors

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<ET: EngineTypes> Mouth<ET> for DefaultMouth<ET>