Trait Input 

pub trait Input {
    // Required methods
    fn lookahead(&mut self, count: usize);
    fn buflen(&self) -> usize;
    fn bufmaxlen(&self) -> usize;
    fn raw_read_ch(&mut self) -> char;
    fn raw_read_non_breakz_ch(&mut self) -> Option<char>;
    fn skip(&mut self);
    fn skip_n(&mut self, count: usize);
    fn peek(&self) -> char;
    fn peek_nth(&self, n: usize) -> char;

    // Provided methods
    fn buf_is_empty(&self) -> bool { ... }
    fn byte_offset(&self) -> Option<usize> { ... }
    fn slice_bytes(&self, _start: usize, _end: usize) -> Option<&str> { ... }
    fn may_contain_comments(&self) -> bool { ... }
    fn take_source_error(&mut self) -> Option<ErrorKind> { ... }
    fn look_ch(&mut self) -> char { ... }
    fn next_char_is(&self, c: char) -> bool { ... }
    fn nth_char_is(&self, n: usize, c: char) -> bool { ... }
    fn next_2_are(&self, c1: char, c2: char) -> bool { ... }
    fn next_3_are(&self, c1: char, c2: char, c3: char) -> bool { ... }
    fn next_is_document_indicator(&self) -> bool { ... }
    fn next_is_document_start(&self) -> bool { ... }
    fn next_is_document_end(&self) -> bool { ... }
    fn skip_ws_to_eol(
        &mut self,
        skip_tabs: SkipTabs,
    ) -> (usize, Result<SkipTabs, ErrorKind>) { ... }
    fn skip_ws_to_eol_blanks(
        &mut self,
        skip_tabs: SkipTabs,
    ) -> (usize, SkipTabs) { ... }
    fn next_can_be_plain_scalar(&self, in_flow: bool) -> bool { ... }
    fn next_is_blank_or_break(&self) -> bool { ... }
    fn next_is_blank_or_breakz(&self) -> bool { ... }
    fn next_is_blank(&self) -> bool { ... }
    fn next_is_break(&self) -> bool { ... }
    fn next_is_breakz(&self) -> bool { ... }
    fn next_is_z(&self) -> bool { ... }
    fn next_is_flow(&self) -> bool { ... }
    fn next_is_digit(&self) -> bool { ... }
    fn next_is_alpha(&self) -> bool { ... }
    fn skip_while_non_breakz(&mut self) -> usize { ... }
    fn skip_while_blank(&mut self) -> usize { ... }
    fn fetch_while_is_alpha(&mut self, out: &mut String) -> usize { ... }
    fn fetch_while_is_yaml_non_space(&mut self, out: &mut String) -> usize { ... }
    fn fetch_block_scalar_line(&mut self, out: &mut String) -> usize { ... }
    fn take_quoted_scalar_ascii_chunk(&mut self, _single: bool) -> &str { ... }
    fn fetch_plain_scalar_chunk(
        &mut self,
        out: &mut String,
        count: usize,
        flow_level_gt_0: bool,
    ) -> (bool, usize) { ... }
    fn skip_plain_scalar_chunk(
        &mut self,
        count: usize,
        flow_level_gt_0: bool,
    ) -> (bool, usize) { ... }
}

Interface for a source of characters.

Hiding the input’s implementation behind this trait allows input-specific optimizations, such as using str methods instead of manually transferring one char at a time to a buffer. Implementations with stable backing storage can also return borrowed &str slices and avoid allocating token values.

Scalar scanning hooks

Self::fetch_block_scalar_line and Self::take_quoted_scalar_ascii_chunk allow bulk processing of block and quoted scalar content. Both provide defaults: custom inputs need only override them when they can offer a more efficient implementation.

Overrides must consume from the logical stream front, including any characters already buffered for lookahead, and keep Self::byte_offset accurate if it is supported. They must work without a preceding Self::lookahead call; callers refresh lookahead before inspecting subsequent characters. Source errors must remain available through Self::take_source_error, and a terminal source error must prevent further source reads. The scanner, not the input hook, updates line/column markers and interprets YAML syntax.

Required Methods

fn lookahead(&mut self, count: usize)

A hint to the input source that we will need to read count characters.

If the input is exhausted, \0 can be used to pad the last characters and later returned. The characters must not be consumed, but may be placed in an internal buffer.

This method may be a no-op if buffering yields no performance improvement.

Implementers of Input must not expose a lookahead window larger than Input::bufmaxlen. They may retain a larger window requested by an earlier call; callers should use Input::buflen to observe the currently available window.

fn buflen(&self) -> usize

Return the number of characters in the active lookahead window.

This is the number of characters that the input promises can be read through peek and peek_nth after prior lookahead calls. It is not necessarily the number of source characters remaining: inputs may keep the window available after consuming characters and may pad positions past EOF with \0.

fn bufmaxlen(&self) -> usize

Return the maximum number of characters this input can buffer for lookahead.

fn raw_read_ch(&mut self) -> char

Read the next character from the logical input stream and return it directly.

If an implementation has already fetched characters for lookahead, this consumes the buffered stream front before reading farther from the underlying source.

fn raw_read_non_breakz_ch(&mut self) -> Option<char>

Read a non-breakz character from the input stream and return it directly.

If an implementation has already fetched characters for lookahead, this consumes from the buffered stream front before reading farther from the underlying source.

If the next character is a breakz, it is either not consumed or placed into the buffer (if any).

fn skip(&mut self)

Consume the next character.

fn skip_n(&mut self, count: usize)

Consume the next count characters.

fn peek(&self) -> char

Return the next character, without consuming it.

Users of the Input must make sure that the character has been loaded through a prior call to Input::lookahead. Implementors of Input may assume that a valid call to Input::lookahead has been made beforehand.

Return

If the input source is not exhausted, returns the next character to be fed into the scanner. Otherwise, returns \0.

fn peek_nth(&self, n: usize) -> char

Return the n-th character in the buffer, without consuming it.

This function assumes that the n-th character in the input has already been fetched through Input::lookahead.

Provided Methods

fn buf_is_empty(&self) -> bool

Return whether the active lookahead window is empty.

This is equivalent to self.buflen() == 0. It does not mean the underlying source is exhausted: after a previous lookahead call, an input may keep a non-empty lookahead window available even after all source characters have been consumed, with positions past EOF observed as \0.

fn byte_offset(&self) -> Option<usize>

Return the current byte offset in the underlying source, if available.

This is an optional capability that enables zero-copy (Cow::Borrowed) token values for inputs that keep a stable backing string (notably str::StrInput).

The returned value (when Some) is the number of bytes that have been consumed so far, i.e. an offset into the original source string.

Correctness contract

Implementations returning Some(_) must satisfy all of the following:

• The offset is a valid UTF-8 boundary in the underlying source.
• The offset is monotonically non-decreasing as characters are consumed.
• The underlying source is stable for the duration of parsing (no reallocation/mutation) so that slices returned by Input::slice_bytes remain valid.

Inputs that cannot provide stable slicing (e.g. stream/iterator inputs) must return None.

fn slice_bytes(&self, _start: usize, _end: usize) -> Option<&str>

Return a borrowed slice of the underlying source between two byte offsets.

This is an optional capability used to produce Cow::Borrowed values without allocating.

start and end are byte offsets as returned by Input::byte_offset. The interval is half-open: [start, end).

Correctness contract

Implementations returning Some(&str) must ensure:

• start <= end.
• Both offsets are valid UTF-8 boundaries.
• The returned &str is a view into the stable underlying source associated with this input.

Implementations that return None from Input::byte_offset must also return None here.

Panics

Implementations may panic in debug builds if start is greater than end or end is past the end of the underlying source.

fn may_contain_comments(&self) -> bool

Return whether this input may contain a # character.

This is a conservative performance hint. Inputs that cannot answer cheaply should return true, which keeps full comment handling enabled.

fn take_source_error(&mut self) -> Option<ErrorKind>

Take a terminal error reported by the underlying source.

Infallible inputs use the default implementation. Fallible streaming inputs latch their first source error and return it here so the scanner can distinguish the failure from clean end-of-input. Once an implementation reports an error, it must not read from its source again.

Source adapters should use an input-related ErrorKind such as ErrorKind::InputIo, ErrorKind::InputDecoding, or ErrorKind::InputByteLimitExceeded.

fn look_ch(&mut self) -> char

Look for the next character and return it.

The character is not consumed. Equivalent to calling Input::lookahead and Input::peek.

fn next_char_is(&self, c: char) -> bool

Return whether the next character in the input source is equal to c.

This function assumes that the next character in the input has already been fetched through Input::lookahead.

fn nth_char_is(&self, n: usize, c: char) -> bool

Return whether the n-th character in the input source is equal to c.

This function assumes that the n-th character in the input has already been fetched through Input::lookahead.

fn next_2_are(&self, c1: char, c2: char) -> bool

Return whether the next 2 characters in the input source match the given characters.

This function assumes that the next 2 characters in the input have already been fetched through Input::lookahead.

Panics

Panics if the active lookahead window contains fewer than 2 characters.

fn next_3_are(&self, c1: char, c2: char, c3: char) -> bool

Return whether the next 3 characters in the input source match the given characters.

This function assumes that the next 3 characters in the input have already been fetched through Input::lookahead.

Panics

Panics if the active lookahead window contains fewer than 3 characters.

fn next_is_document_indicator(&self) -> bool

Check whether the next characters correspond to a document indicator.

This function assumes that the next 4 characters in the input have already been fetched through Input::lookahead.

Panics

Panics if the active lookahead window contains fewer than 4 characters.

fn next_is_document_start(&self) -> bool

Check whether the next characters correspond to a start of document.

This function assumes that the next 4 characters in the input have already been fetched through Input::lookahead.

Panics

Panics if the active lookahead window contains fewer than 4 characters.

fn next_is_document_end(&self) -> bool

Check whether the next characters correspond to an end of document.

This function assumes that the next 4 characters in the input have already been fetched through Input::lookahead.

Panics

Panics if the active lookahead window contains fewer than 4 characters.

fn skip_ws_to_eol( &mut self, skip_tabs: SkipTabs, ) -> (usize, Result<SkipTabs, ErrorKind>)

Skip YAML whitespace up to the end of the current line.

Inline comments are consumed only after at least one preceding YAML whitespace character.

Return

Return a tuple with the number of characters that were consumed and the result of skipping whitespace. The number of characters returned can be used to advance the index and column, since no end-of-line character will be consumed. See SkipTabs for more details on the success variant.

Errors

Returns ErrorKind::CommentNotSeparated if a comment is encountered without preceding whitespace. In that event, the first tuple element contains the number of characters consumed prior to reaching the #.

Panics

Panics if skip_tabs is SkipTabs::Result, which is an output-only variant.

fn skip_ws_to_eol_blanks(&mut self, skip_tabs: SkipTabs) -> (usize, SkipTabs)

Skip YAML blank characters, stopping before comments, line breaks, or other content.

This is the comment-aware counterpart to Input::skip_ws_to_eol: it preserves a following # for the scanner to tokenize while still letting input implementations batch the common run of spaces and tabs.

Return

Returns the number of consumed characters and a SkipTabs::Result describing whether tabs and valid YAML whitespace ( ) were encountered.

Panics

Panics if skip_tabs is SkipTabs::Result, which is an output-only variant.

fn next_can_be_plain_scalar(&self, in_flow: bool) -> bool

Check whether the next characters may be part of a plain scalar.

This function assumes we are not given a blankz character.

fn next_is_blank_or_break(&self) -> bool

Check whether the next character is a blank or a break.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a blank or a break, false otherwise.

fn next_is_blank_or_breakz(&self) -> bool

Check whether the next character is a blank or a breakz.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a blank or [a break], false otherwise.

fn next_is_blank(&self) -> bool

Check whether the next character is a blank.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a blank, false otherwise.

fn next_is_break(&self) -> bool

Check whether the next character is a break.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a break, false otherwise.

fn next_is_breakz(&self) -> bool

Check whether the next character is a breakz.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a breakz, false otherwise.

fn next_is_z(&self) -> bool

Check whether the input is at its physical end.

The default implementation infers end-of-input from the \0 sentinel returned by Self::peek. Inputs that can distinguish a literal NUL from end-of-input should override this method. The next position must have previously been fetched through Self::lookahead.

Return

Returns true if the input is exhausted, false otherwise.

fn next_is_flow(&self) -> bool

Check whether the next character is a flow.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a flow, false otherwise.

fn next_is_digit(&self) -> bool

Check whether the next character is a digit.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a digit, false otherwise.

fn next_is_alpha(&self) -> bool

Check whether the next character is a letter.

The character must have previously been fetched through lookahead

Return

Returns true if the character is a letter, false otherwise.

fn skip_while_non_breakz(&mut self) -> usize

Skip printable characters until a breakz or non-printable character is found.

The stopping character is not consumed.

Return

Return the number of characters that were consumed. The number of characters returned can be used to advance the index and column, since no end-of-line character will be consumed.

fn skip_while_blank(&mut self) -> usize

Skip characters from the input while blanks are found.

The characters are consumed from the input.

Return

Return the number of characters that were consumed. The number of characters returned can be used to advance the index and column, since no end-of-line character will be consumed.

fn fetch_while_is_alpha(&mut self, out: &mut String) -> usize

Fetch characters from the input while we encounter letters and store them in out.

The characters are consumed from the input.

Return

Return the number of characters that were consumed. The number of characters returned can be used to advance the index and column, since no end-of-line character will be consumed.

fn fetch_while_is_yaml_non_space(&mut self, out: &mut String) -> usize

Fetch characters as long as they satisfy is_yaml_non_space(c).

The characters are consumed from the input.

Return

Return the number of characters that were consumed. The number of characters returned can be used to advance the index and column, since no end-of-line character will be consumed.

fn fetch_block_scalar_line(&mut self, out: &mut String) -> usize

Append a block scalar’s content line to out, stopping before CR, LF, NUL, or EOF.

The caller positions the input after the line’s indentation. This method consumes the entire remaining content line and appends it without clearing existing contents of out. The stopping character is not consumed; in particular, both characters of CRLF remain unconsumed, even if already buffered for lookahead.

This copies content verbatim, including tabs and any non-printable characters other than NUL. Unicode characters such as NEL (U+0085), line separator (U+2028), and paragraph separator (U+2029) are content, not line terminators here. The scanner remains responsible for validation, indentation, folding, and chomping; overrides must not discard or replace invalid content.

The default uses Self::raw_read_non_breakz_ch, including any buffered lookahead. Inputs with contiguous storage, such as str::StrInput, can override this to append a source slice in one operation. No prior lookahead is required; callers refresh lookahead before inspecting the next character. If a source error interrupts the line, append and count only the characters consumed before it. Keep the error available through Self::take_source_error; the return value alone does not distinguish a source failure from a normal line ending.

Returns

The number of consumed Unicode scalar values (chars), not UTF-8 bytes, for advancing the character index and column. A return value of zero means no content was appended or consumed, for example when already at a line terminator or EOF.

Examples

use granit_parser::{Input, StrInput};

let mut input = StrInput::new("é🦀\r\nnext");
let mut output = String::from("prefix:");
assert_eq!(input.fetch_block_scalar_line(&mut output), 2);
assert_eq!(output, "prefix:é🦀");
assert_eq!(input.byte_offset(), Some("é🦀".len()));
input.lookahead(2);
assert_eq!(input.peek(), '\r');
assert_eq!(input.peek_nth(1), '\n');

fn take_quoted_scalar_ascii_chunk(&mut self, _single: bool) -> &str

Consume and return an ordinary ASCII run inside a quoted scalar, if supported.

The caller has already consumed the opening quote. The boolean selects the quote style: true for single quotes, false for double quotes. This optional optimization batches characters needing no YAML escape or folding handling. The default returns an empty slice without consuming input, leaving character-by-character scanning in place.

Override contract

A non-empty result must contain exactly the consumed source prefix, with no decoding or substitution. Only bytes in 0x21..=0x7e may be consumed, excluding the matching quote (' for single quotes, otherwise ") and, in double-quoted scalars, backslashes. Backslashes and double quotes are ordinary content in single-quoted scalars; single quotes are ordinary content in double-quoted scalars. Whitespace, non-ASCII text, control characters, escapes, and closing or doubled matching quotes are left for the scanner. The returned byte length is also the number of consumed characters, and any supported Self::byte_offset must advance by that length.

The run need not be maximal. Returning an empty slice must consume nothing, even if an eligible run is present; it does not indicate EOF or the end of the scalar. No prior lookahead is required, and already-buffered characters must not be skipped. Callers refresh lookahead before inspecting the next character. The returned slice is tied to the borrow of self, not to the original source lifetime used by BorrowedInput::slice_borrowed.

Examples

use granit_parser::{BufferedInput, Input, StrInput};

// Remaining content after a double-quoted scalar's opening quote.
let mut input = StrInput::new(r#"name\n""#);
assert_eq!(input.take_quoted_scalar_ascii_chunk(false), "name");
input.lookahead(1);
assert_eq!(input.peek(), '\\'); // The escape is left for the scanner.

// Streaming inputs may retain the default and consume nothing.
let mut stream = BufferedInput::new("name".chars());
assert_eq!(stream.take_quoted_scalar_ascii_chunk(false), "");
stream.lookahead(1);
assert_eq!(stream.peek(), 'n');

fn fetch_plain_scalar_chunk( &mut self, out: &mut String, count: usize, flow_level_gt_0: bool, ) -> (bool, usize)

Fetch a chunk of plain scalar characters.

This optimization method allows the input to batch process characters. Returns (stopped, chars_consumed). stopped is true if the chunk ended because of a non-plain-scalar character.

fn skip_plain_scalar_chunk( &mut self, count: usize, flow_level_gt_0: bool, ) -> (bool, usize)

Consume a chunk of plain-scalar characters without materializing them.

Stable inputs use this while the scanner retains the source as a borrowed slice and only promotes it to an owned buffer if YAML folding changes the scalar contents.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Input for StrInput<'_>

impl<T: Iterator<Item = Result<char, ErrorKind>>> Input for FallibleBufferedInput<T>

impl<T: Iterator<Item = char>> Input for BufferedInput<T>