Links Notation Parser for Rust

Rust implementation of the Links Notation parser using nom parser combinator library.

Installation

Add this to your Cargo.toml:

[dependencies]
links-notation = { path = "." }  # For local development
# Or from a registry:
# links-notation = "0.9.0"

From Source

Clone the repository and build:

git clone https://github.com/link-foundation/links-notation.git
cd links-notation/rust
cargo build

Build

Build the project:

cargo build

Build with optimizations:

cargo build --release

Test

Run tests:

cargo test

Run tests with output:

cargo test -- --nocapture

Usage

Basic Parsing

use links_notation::{parse_lino, LiNo};

fn main() {
    // Parse Links Notation format string
    let input = r#"papa (lovesMama: loves mama)
son lovesMama
daughter lovesMama
all (love mama)"#;
    
    match parse_lino(input) {
        Ok(parsed) => {
            println!("Parsed: {}", parsed);
            
            // Access the structure
            if let LiNo::Link { values, .. } = parsed {
                for link in values {
                    println!("Link: {}", link);
                }
            }
        }
        Err(e) => eprintln!("Parse error: {}", e),
    }
}

Working with Links

use links_notation::LiNo;

// Create links programmatically
let reference = LiNo::Ref("some_value".to_string());
let link = LiNo::Link {
    id: Some("parent".to_string()),
    values: vec![
        LiNo::Ref("child1".to_string()),
        LiNo::Ref("child2".to_string()),
    ],
};

// Check link types
if link.is_link() {
    println!("This is a link");
}
if reference.is_ref() {
    println!("This is a reference");
}

Formatting Output

use links_notation::parse_lino;

let input = "(parent: child1 child2)";
let parsed = parse_lino(input).unwrap();

// Regular formatting (parenthesized)
println!("Regular: {}", parsed);

// Alternate formatting (line-based)
println!("Alternate: {:#}", parsed);

Handling Different Input Formats

use links_notation::parse_lino;

// Single line format
let single_line = "id: value1 value2";
let parsed = parse_lino(single_line)?;

// Parenthesized format
let parenthesized = "(id: value1 value2)";
let parsed = parse_lino(parenthesized)?;

// Multi-line with indentation
let indented = r#"parent
  child1
  child2"#;
let parsed = parse_lino(indented)?;

// Quoted identifiers and values
let quoted = r#"("quoted id": "value with spaces")"#;
let parsed = parse_lino(quoted)?;

Syntax Examples

Doublets (2-tuple)

papa (lovesMama: loves mama)
son lovesMama
daughter lovesMama
all (love mama)

Triplets (3-tuple)

papa has car
mama has house
(papa and mama) are happy

N-tuples with References

(linksNotation: links notation)
(This is a linksNotation as well)
(linksNotation supports (unlimited number (of references) in each link))

Indented Structure

parent
  child1
  child2
    grandchild1
    grandchild2

API Reference

Enums

LiNo<T>

Represents either a Link or a Reference:

• Link { id: Option<T>, values: Vec<Self> } - A link with optional ID and child values
• Ref(T) - A reference to another link

Methods

Methods for LiNo<T>

• is_ref() -> bool - Returns true if this is a reference
• is_link() -> bool - Returns true if this is a link

Functions

parse_lino(document: &str) -> Result<LiNo<String>, String>

Parses a Links Notation document string and returns the parsed structure or an error.

Formatting

The Display trait is implemented for LiNo<T> where T: ToString:

• Regular format: format!("{}", lino) - Parenthesized output
• Alternate format: format!("{:#}", lino) - Line-based output

Maintenance

Linting and Formatting

Check code formatting:

cargo fmt --all -- --check

Auto-fix formatting:

cargo fmt --all

Run Clippy linter:

cargo clippy --all-targets --all-features -- -D warnings

Pre-commit Hooks

This project uses pre-commit hooks that automatically run cargo fmt and cargo check before commits. To set up pre-commit hooks locally:

# From repository root
pip install pre-commit
pre-commit install

Dependencies

• nom (8.0) - Parser combinator library

Error Handling

The parser returns descriptive error messages for:

• Empty or whitespace-only input
• Malformed syntax
• Unclosed parentheses
• Invalid characters

match parse_lino("(invalid") {
    Ok(parsed) => println!("Parsed: {}", parsed),
    Err(error) => eprintln!("Error: {}", error),
}

Maintenance

Code Formatting

This project uses rustfmt for code formatting and clippy for linting.

Format all files

cargo fmt

Check formatting (without modifying files)

cargo fmt --check

Run linter

cargo clippy

These checks are also enforced in CI. Pull requests with formatting issues will fail the format check.