sbircio
A lightweight BufRead wrapper that adds Unicode-aware peek-ahead and
character-level scanning, designed for building parsers and lexers in Rust.
No complex combinators, no macros — just a thin layer over any BufRead
that lets you look ahead without consuming, match literals, and scan with
predicates.
Features
- Peek ahead — inspect the next N Unicode characters without consuming them
- Exact matching — consume and verify string literals or single characters
- Predicate scanning —
consume_while/consume_untilwith anyFn(char) -> bool - Full UTF-8 support — handles multi-byte characters and partial reads correctly
- Zero-copy cache — peeked characters are kept in an internal buffer and reused across calls; no redundant I/O
- Works with anything — files, stdin, in-memory buffers: any
BufReadsource - Minimal footprint — a single struct, a single error type, one optional dependency
Installation
[]
= "0.1.0"
To track the latest unreleased changes instead:
[]
= { = "https://codeberg.org/marc0x71/sbircio" }
To pin to a specific commit or tag:
= { = "https://codeberg.org/marc0x71/sbircio", = "v0.1.0" }
Quick start
use Input;
use Cursor;
API reference
Input<R>
Wraps any BufRead source and
provides Unicode-aware peek-ahead and character-level scanning. Peeked characters are
cached internally and reused across calls without triggering additional reads.
Constructor
Creates a new Input wrapping the given reader. The internal cache starts empty;
no reads are performed until the first peek or consume call.
Peeking
Returns the next Unicode character without consuming it.
Returns Ok(None) at end of input.
Returns the next required Unicode characters as a &str without consuming them.
Returns Ok(None) if fewer than required characters remain in the stream.
The returned slice is valid until the next consume call. Subsequent calls with the
same or a smaller required reuse the internal cache without additional I/O.
Consuming
Consumes and returns the next Unicode character.
Returns Ok(None) at end of input. The byte offset returned by position() advances
by the UTF-8 byte length of the consumed character.
Consumes and returns consecutive characters for which predicate returns true.
Stops at the first character for which predicate returns false, leaving it
available for subsequent reads. Returns an empty String if the very first character
does not match.
Consumes and returns characters until predicate returns true.
The first character for which predicate returns true is not consumed and
remains available for subsequent reads. Returns an empty String if the very first
character matches immediately.
Consumes and discards all leading whitespace characters (as defined by
char::is_whitespace).
Equivalent to consume_while(char::is_whitespace).map(|_| ()).
Matching
Verifies that the next characters exactly match expected and consumes them.
On failure (mismatch or end of input), returns
InputError::UnsatisfiedExpectation and leaves the input unchanged.
Verifies that the next character matches expected and consumes it.
On failure, returns InputError::UnsatisfiedExpectation and leaves the
input unchanged.
State
Returns true if the end of input has been reached, false otherwise.
Internally performs a peek(), so the first unread character remains available.
Returns the current byte offset from the beginning of the stream.
The offset is measured in bytes, not Unicode characters: multi-byte characters
such as 'è' (2 bytes) or '€' (3 bytes) advance the position accordingly.
Returns the current position in the input as line and column numbers. Both line and column are 1-based: the first character of the stream is at line 1, column 1. The column advances by one for each Unicode character consumed; a newline resets the column to 1 and increments the line counter.
Coordinates
Represents a position in the input stream as a (line, column) pair, both 1-based.
Returned by Input::coordinates().
InputError
InputError implements std::error::Error
and converts automatically from std::io::Error and std::str::Utf8Error via From.
Note on
PartialEq: twoIOvariants are considered equal if they have the sameErrorKind, sincestd::io::Errordoes not itself implementPartialEq.
Examples
Building a lexer
sbircio is a low-level primitive: it reads characters, the lexer gives them meaning.
Input knows nothing about your Token type — that separation is intentional.
use ;
use BufRead;
License
Released under the MIT License.
This README was drafted with the assistance of an AI (Claude by Anthropic) and reviewed by the author.