parserst

Crates.io	parserst
lib.rs	parserst
version	0.1.1
created_at	2025-10-25 06:10:09.589146+00
updated_at	2025-10-25 06:12:15.277725+00
description	A recursive-descent reST parser and renderer
homepage	https://github.com/stormlightlabs/parserst
repository	https://github.com/stormlightlabs/parserst
max_upload_size
id	1899773
size	116,504

Owais (desertthunder)

documentation

README

parseRST

A lightweight, recursive-descent reStructuredText parser written in Rust.

Overview

parserst is a small, fast, and self-contained parser for reStructuredText documents. It aims to provide a clean, idiomatic Rust API for converting .rst content into structured AST nodes or HTML/Markdown.

This crate is ideal for:

Building static site generators, documentation tools, or format converters.
Integrating reStructuredText support into note-taking or content-processing apps.
Experimenting with parsing techniques and markup language design.
Parsing Python docstrings

Features

Category	Description
Inline parsing	Supports `emphasis`, `strong`, `code`, and `link <https://...>`_.
Block parsing	Detects headings, paragraphs, lists (ordered/unordered), code fences, and quote blocks.
Output	Render to HTML (always available) or Markdown (requires `markdown` feature).
Serialization	Serialize AST to JSON, YAML, or any serde-supported format (requires `serde` feature).
AST Access	Exposes a clean, typed AST (`Block`, `Inline`, `Field`, `ListKind`) for custom rendering.
Error Handling	Safe `Result<Vec<Block>, ParseError>` API with detailed line numbers.
Minimal deps	No external parser frameworks or macros; all features are optional and can be enabled as needed.

Installation

Add to your Cargo.toml:

[dependencies]
parserst = "0.1"

# With markdown support
parserst = { version = "0.1", features = ["markdown"] }

# With serde serialization support
parserst = { version = "0.1", features = ["serde"] }

# With all features
parserst = { version = "0.1", features = ["markdown", "serde"] }

Example

use parserst::html_of;

fn main() {
    let rst = r#"
Heading
=======

This is *emphasized*, **bold**, and ``inline code``.

- Item 1
- Item 2
"#;

    let html = html_of(rst);
    println!("{}", html);
}

Output:

<h1>Heading</h1>
<p>
    This is <em>emphasized</em>, <strong>bold</strong>, and
    <code>inline code</code>.
</p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
</ul>

The AST can be serialized to any format supported by serde: JSON, YAML, TOML, MessagePack, etc.

Design

Recursive Descent — every rule is expressed in idiomatic Rust, not macros.
Predictable — prioritizes correctness over complete reStructuredText parity.
Composabe — easy to extend or replace the renderer layer (e.g., to JSON, Markdown, or AST tools).
No Unsafe — guaranteed safe Rust implementation.

Tests & Builds

cargo test

Test with specific feature configurations:

# Without any features
cargo test --no-default-features
cargo build --no-default-features # or cargo build

# With markdown
cargo test --features markdown
cargo build --features markdown

# With serde
cargo test --features serde
cargo build --features serde

# All features
cargo test --all-features
cargo build --release --all-features

Using just (if you have just installed):

# View all recipes
just -l

API Overview

Function	Description
`parse(input: &str)`	Parses `.rst` text into a `Vec<Block>` AST.
`html_of(input: &str)`	Parses and renders the input as HTML.
`markdown_of(input: &str)`	Parses and renders the input as Markdown (requires `markdown` feature).

Types

Item	Description
`Block`	Top-level AST nodes such as headings, paragraphs, directives, field lists, tables, etc.
`Inline`	Inline nodes nested inside `Block` variants (text, emphasis, strong, code, links)
`Field`	A field entry within a field list (e.g., `:param x: description`)
`ListKind`	Enum describing list flavor (`Ordered` or `Unordered`) for `Block::List`

License

See MIT License or learn more here

Made with ⚡️ by Stormlight Labs.

Stormlight Labs is just me, Owais. Support my work on Ko-fi.

Commit count: 0