# 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_until` with any `Fn(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 `BufRead` source
- **Minimal footprint** — a single struct, a single error type, one optional dependency
## Installation
```toml
[dependencies]
sbircio = "0.1.0"
```
To track the latest unreleased changes instead:
```toml
[dependencies]
sbircio = { git = "https://codeberg.org/marc0x71/sbircio" }
```
To pin to a specific commit or tag:
```toml
sbircio = { git = "https://codeberg.org/marc0x71/sbircio", tag = "v0.1.0" }
```
## Quick start
```rust
use sbircio::Input;
use std::io::Cursor;
fn main() -> Result<(), sbircio::InputError> {
let source = Cursor::new("42 + hello");
let mut input = Input::new(source);
// Read a number token
let num = input.consume_while(|c| c.is_ascii_digit())?;
input.skip_whitespace()?;
// Verify an operator
input.expect("+")?;
input.skip_whitespace()?;
// Read an identifier
let word = input.consume_while(|c| c.is_alphabetic())?;
println!("{num} + {word}"); // 42 + hello
Ok(())
}
```
## API reference
### `Input<R>`
```rust
pub struct Input<R> { /* private fields */ }
```
Wraps any [`BufRead`](https://doc.rust-lang.org/std/io/trait.BufRead.html) 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
```rust
pub fn new(rdr: R) -> Self
```
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
```rust
pub fn peek(&mut self) -> Result<Option<char>, InputError>
```
Returns the next Unicode character without consuming it.
Returns `Ok(None)` at end of input.
---
```rust
pub fn peek_n(&mut self, required: usize) -> Result<Option<&str>, InputError>
```
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
```rust
pub fn consume_char(&mut self) -> Result<Option<char>, InputError>
```
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.
---
```rust
pub fn consume_while<P>(&mut self, predicate: P) -> Result<String, InputError>
where
P: Fn(char) -> bool,
```
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.
---
```rust
pub fn consume_until<P>(&mut self, predicate: P) -> Result<String, InputError>
where
P: Fn(char) -> bool,
```
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.
---
```rust
pub fn skip_whitespace(&mut self) -> Result<(), InputError>
```
Consumes and discards all leading whitespace characters (as defined by
[`char::is_whitespace`](https://doc.rust-lang.org/std/primitive.char.html#method.is_whitespace)).
Equivalent to `consume_while(char::is_whitespace).map(|_| ())`.
---
#### Matching
```rust
pub fn expect(&mut self, expected: &str) -> Result<(), InputError>
```
Verifies that the next characters exactly match `expected` and consumes them.
On failure (mismatch or end of input), returns
[`InputError::UnsatisfiedExpectation`](#inputerror) and leaves the input unchanged.
---
```rust
pub fn expect_char(&mut self, expected: char) -> Result<(), InputError>
```
Verifies that the next character matches `expected` and consumes it.
On failure, returns [`InputError::UnsatisfiedExpectation`](#inputerror) and leaves the
input unchanged.
---
#### State
```rust
pub fn is_eof(&mut self) -> Result<bool, InputError>
```
Returns `true` if the end of input has been reached, `false` otherwise.
Internally performs a `peek()`, so the first unread character remains available.
---
```rust
pub fn position(&self) -> usize
```
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.
---
```rust
pub fn coordinates(&self) -> Coordinates
```
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`
```rust
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Coordinates { /* fields: line, column */ }
```
Represents a position in the input stream as a (line, column) pair, both 1-based.
Returned by [`Input::coordinates()`](#state).
```rust
pub fn new(line: usize, column: usize) -> Self
pub fn line(&self) -> usize
pub fn column(&self) -> usize
```
---
### `InputError`
```rust
#[derive(Error, Debug, PartialEq)]
pub enum InputError {
/// The byte sequence read is not valid UTF-8.
InvalidString(Utf8Error),
/// The stream ended in the middle of a multi-byte character.
UnexpectedEof,
/// The next characters did not match the expected value.
UnsatisfiedExpectation {
expected: String,
found: String,
},
/// An underlying I/O error occurred.
IO(std::io::Error),
}
```
`InputError` implements [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html)
and converts automatically from `std::io::Error` and `std::str::Utf8Error` via `From`.
> **Note on `PartialEq`:** two `IO` variants are considered equal if they have the
> same [`ErrorKind`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html), since
> `std::io::Error` does not itself implement `PartialEq`.
## 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.
```rust
use sbircio::{Input, InputError};
use std::io::BufRead;
#[derive(Debug, PartialEq)]
enum Token {
Number(u64),
Ident(String),
Add,
Sub,
Mul,
Div,
}
fn next_token<R: BufRead>(input: &mut Input<R>) -> Result<Option<Token>, InputError> {
input.skip_whitespace()?;
match input.peek()? {
None => Ok(None),
Some('+') => { input.consume_char()?; Ok(Some(Token::Add)) }
Some('-') => { input.consume_char()?; Ok(Some(Token::Sub)) }
Some('*') => { input.consume_char()?; Ok(Some(Token::Mul)) }
Some('/') => { input.consume_char()?; Ok(Some(Token::Div)) }
Some(c) if c.is_ascii_digit() => {
let s = input.consume_while(|c| c.is_ascii_digit())?;
Ok(Some(Token::Number(s.parse().unwrap())))
}
Some(c) if c.is_alphabetic() || c == '_' => {
let s = input.consume_while(|c| c.is_alphanumeric() || c == '_')?;
Ok(Some(Token::Ident(s)))
}
Some(c) => Err(InputError::UnsatisfiedExpectation {
expected: "a valid token".to_string(),
found: c.to_string(),
}),
}
}
fn main() -> Result<(), InputError> {
let mut input = Input::new(std::io::Cursor::new("x1 + 42 * y"));
while let Some(tok) = next_token(&mut input)? {
println!("{tok:?}");
}
// Ident("x1") Add Number(42) Mul Ident("y")
Ok(())
}
```
## License
Released under the [MIT License](LICENSE).
---
> This README was drafted with the assistance of an AI (Claude by Anthropic)
> and reviewed by the author.