Struct tectonic::io::InputHandle

pub struct InputHandle { /* fields omitted */ }

Input handles are basically Read objects with a few extras. We don't require the standard io::Seek because we need to provide a dummy implementation for GZip streams, which we wouldn't be allowed to do because both the trait and the target struct are outside of our crate.

An important role for the InputHandle struct is computing a cryptographic digest of the input file. The driver uses this information in order to figure out if the TeX engine needs rerunning. TeX makes our life more difficult, though, since it has somewhat funky file access patterns. LaTeX file opens work by opening a file and immediately closing it, which tests whether the file exists, and then by opening it again for real. Under the hood, XeTeX reads a couple of bytes from each file upon open to sniff its encoding. So we can't just stream data from read() calls into the SHA2 computer, since we end up seeking and reading redundant data.

The current system maintains some internal state that, so far, helps us Do The Right Thing given all this. If there's a seek on the file, we give up on our digest computation. But if there's a seek back to the file beginning, we are open to the possibility of restarting the computation. But if nothing is ever read from the file, we once again give up on the computation. The ExecutionState code then has further pieces that track access to nonexistent files, which we treat as being equivalent to an existing empty file for these purposes.

Methods

impl InputHandle

Important traits for InputHandle

impl Read for InputHandle

pub fn new<T: 'static + InputFeatures>(     name: &OsStr,     inner: T,     origin: InputOrigin ) -> InputHandle

pub fn name(&self) -> &OsStr

pub fn origin(&self) -> InputOrigin

Important traits for Box<R>

impl<R> Read for Box<R> where
    R: Read + ?Sized, impl<W> Write for Box<W> where
    W: Write + ?Sized, impl<I> Iterator for Box<I> where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn into_inner(self) -> Box<InputFeatures>

Consumes the object and returns the underlying readable handle that it references.

pub fn into_name_digest(self) -> (OsString, Option<DigestData>)

Consumes the object and returns the SHA256 sum of the content that was written. No digest is returned if there was ever a seek on the input stream, since in that case the results will not be reliable. We also return None if the stream was never read, which is another common TeX access pattern: files are opened, immediately closed, and then opened again.

pub fn getc(&mut self) -> Result<u8>

Various piece of TeX want to use the libc ungetc() function a lot. It's kind of gross, but happens often enough that we provide special support for it. Here's getc() emulation that can return a previously ungetc()-ed character.

pub fn ungetc(&mut self, byte: u8) -> Result<()>

Here's the ungetc() emulation.

Trait Implementations

impl Read for InputHandle

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

Important traits for Bytes<R>

impl<R> Iterator for Bytes<R> where
    R: Read,  type Item = Result<u8, Error>;

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

Important traits for Chars<R>

impl<R> Iterator for Chars<R> where
    R: Read,  type Item = Result<char, CharsError>;

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

Important traits for Chain<T, U>

impl<T, U> Read for Chain<T, U> where
    T: Read,
    U: Read, 

fn chain<R>(self, next: R) -> Chain<Self, R> where     R: Read,

Creates an adaptor which will chain this stream with another.

Important traits for Take<T>

impl<T> Read for Take<T> where
    T: Read, 

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl InputFeatures for InputHandle

fn get_size(&mut self) -> Result<usize>

fn try_seek(&mut self, pos: SeekFrom) -> Result<u64>