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

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),
}