Trait tectonic_bridge_core::DriverHooks

pub trait DriverHooks {
    // Required method
    fn io(&mut self) -> &mut dyn IoProvider;

    // Provided methods
    fn event_output_closed(
        &mut self,
        _name: String,
        _digest: DigestData,
        _status: &mut dyn StatusBackend
    ) { ... }
    fn event_input_closed(
        &mut self,
        _name: String,
        _digest: Option<DigestData>,
        _status: &mut dyn StatusBackend
    ) { ... }
    fn sysrq_shell_escape(
        &mut self,
        _command: &str,
        _status: &mut dyn StatusBackend
    ) -> StdResult<(), SystemRequestError> { ... }
}

The DriverHooks trait allows engines to interact with the higher-level code that is driving the TeX processing.

Drivers mainly manage interactions between the engines and the outside world. The primary way they do this is by exposing an IoProvider implementation.

Drivers can also implement handlers for additional events that help it track the input and output access patterns of the engines. The CLI program needs these to intelligently decide when to rerun the TeX engine, to choose which files to actually save to disk, and to emit Makefile rules describing the dependency of the outputs on the inputs. The relevant trait methods have default implementations that do nothing.

Required Methods

fn io(&mut self) -> &mut dyn IoProvider

Get the main I/O implementations of this driver.

Provided Methods

fn event_output_closed( &mut self, _name: String, _digest: DigestData, _status: &mut dyn StatusBackend )

This function is called when an output file is closed. The “digest” argument specifies the cryptographic digest of the data that were written. Note that this function takes ownership of the name and digest.

fn event_input_closed( &mut self, _name: String, _digest: Option<DigestData>, _status: &mut dyn StatusBackend )

This function is called when an input file is closed. The “digest” argument specifies the cryptographic digest of the data that were read, if available. This digest is not always available, if the engine used seeks while reading the file. Note that this function takes ownership of the name and digest.

fn sysrq_shell_escape( &mut self, _command: &str, _status: &mut dyn StatusBackend ) -> StdResult<(), SystemRequestError>

The engine is requesting a “shell escape” evaluation.

If the driver wishes to implement this request, it should run the specified command using the OS’s default shell. Relevant files should be available in the command’s working directory, and if the command creates any files, they should be incorporated into the I/O environment. The shell-escape environment should persist across multiple invocations of this system request, because some packages run a series of commands that assume such persistence. Also note that the command text has to be evaluated through a shell, not just with exec(), since shell features such as redirections might be used. This is therefore a wildly insecure feature.

This function can only return a limited range of error values because the C/C++ engines can’t do anything useful with them. Detailed error information should be logged or stored inside the hook function.

Implementors

impl<T: IoProvider> DriverHooks for MinimalDriver<T>