Struct texlang::vm::ExpansionInput

#[repr(transparent)]
pub struct ExpansionInput<S>(/* private fields */);

Input type for expansion primitives.

This type provides:

• Access to the input stream (with or without expansion). Its implementation of the TokenStream trait returns expanded tokens. To read the input stream without performing expansion, use the unexpanded method.

• Read only access to the VM.

• The ability to push source code or token expansions to the front of the input stream. For source code use ExpansionInput::push_source; for tokens use ExpansionInput::push_expansion or ExpansionInput::expansions_mut.

• Access to token buffers using the ExpansionInput::checkout_token_buffer and ExpansionInput::return_token_buffer methods.

This type is also used in the parsing code for situations where both an ExpansionInput or ExecutionInput is accepted. We use this type because it has only read access to the VM, and so casting does not escalate privileges.

Implementations

impl<S> ExpansionInput<S>

pub fn new(vm: &mut VM<S>) -> &mut ExpansionInput<S>

Creates a mutable reference to this type from the VM type.

impl<S: TexlangState> ExpansionInput<S>

pub fn push_source( &mut self, token: Token, file_name: PathBuf, source_code: String ) -> Result<(), Box<Error>>

Push source code to the front of the input stream.

pub fn end_current_file(&mut self)

End the current file.

This method is used by \endinput primitive.

pub fn push_string_tokens(&mut self, token: Token, s: &str)

impl<S> ExpansionInput<S>

pub fn unexpanded(&mut self) -> &mut UnexpandedStream<S>

pub fn expanded(&mut self) -> &mut ExpandedStream<S>

pub fn push_expansion(&mut self, expansion: &[Token])

Push tokens to the front of the input stream.

The first token in the provided slice will be the next token read.

pub fn expansions(&self) -> &Vec<Token>

Returns a reference to the expanded tokens stack for the current input source.

The tokens are a stack, so the next token is the last token in the vector.

Adding tokens to the front of the input using this method can be more efficient than using ExpansionInput::push_expansion because an allocation is avoided.

pub fn expansions_mut(&mut self) -> &mut Vec<Token>

Returns a mutable reference to the expanded tokens stack for the current input source.

The tokens are a stack, so the next token is the last token in the vector.

Adding tokens to the front of the input using this method can be more efficient than using ExpansionInput::push_expansion because an allocation is avoided.

pub fn state_and_expansions_mut(&mut self) -> (&S, &mut Vec<Token>)

pub fn checkout_token_buffer(&mut self) -> Vec<Token>

Returns a vector than can be used as a token buffer, potentially without allocating memory.

The returned vector is empty, but will generally have non-zero capacity from previous uses of the buffer. Reusing the allocated memory results in fewer allocations overall. This buffer mechanism was first introduced in a successful attempt to improve the performance of the TeX macros implementation.

When finished with the buffer, please return it using return_token_buffer.

This API may feel a bit awkward - it would seem nicer to return a mutable reference to a buffer instead. Doing this while keeping the borrow checker happy is very difficult and (as is often the case) for good reason. Token buffers are often used in macro expansion, and at any point in time multiple macros may be in the process of expansion. This getting “the” token buffer to use for expansion would be incorrect, as the multiple expansions would step on each other.

pub fn return_token_buffer(&mut self, token_buffer: Vec<Token>)

Return a token buffer, allowing it to be reused.

Trait Implementations

impl<S> AsMut<ExpandedStream<S>> for ExpansionInput<S>

fn as_mut(&mut self) -> &mut ExpandedStream<S>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<S: TexlangState> TokenStream for ExpansionInput<S>

type S = S

The type of the custom state in the VM.

fn next(&mut self) -> Result<Option<Token>, Box<Error>>

Gets the next token in the stream.

fn peek(&mut self) -> Result<Option<&Token>, Box<Error>>

Peeks at the next token in the stream without removing it.

fn vm(&self) -> &VM<Self::S>

Returns a reference to the VM.

fn consume(&mut self) -> Result<(), Box<Error>>

Consumes the next token in the stream without returning it.

fn commands_map(&self) -> &Map<Self::S>

Returns a reference to the commands map.

fn state(&self) -> &Self::S

Returns a reference to the custom state.

fn trace(&self, token: Token) -> SourceCodeTrace

fn trace_end_of_input(&self) -> SourceCodeTrace