Adding `rslnp` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add rslnp

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

rslnp = "0.4.1"

The rslnp library will be automatically available globally. Read the rslnp library documentation.

Back to the crate overview.

Readme

Rust Scopes List Notation Parser

This is a configurable parser for Scopes List Notation (SLN), written in Rust.

SLN was invented for the Scopes programming language, so also take a look at it.

It parses input using the token parser, which is an intermediate representation for code structure. In short, every value is either a symbol (represented as a string) or a parser (parsing other tokens).

Representation

SLN is a simple representation suitable for both code and data. It is indentation-based (similar to Python) and directly maps to a list representation (like Lisp). It also supports brackets for nesting, which is most useful for single-line expressions. You can use brackets to opt out of indentation entirely, treating SLN as a pure s-expression parser, or mix both styles.

Benefits

This notation offers several advantages:

Simplicity and Flexibility: It can replace common text formats like XML, JSON, TOML, YAML...
Multiline Strings: Ideal for embedding long texts (like HTML) or code from other languages (like shader code).
Token Parser Integration: Parsed output is compatible with the token parser crate. You can reuse parsers or write your own without rewriting core logic.
Prototyping for Languages: For DSLs or new languages, start with SLN and switch representations later without major refactors.

Usage

First, create a parser. Use the default Parser::new() for minimal features or Parser::scopes() for full SLN support (matching the Scopes language syntax). Then, parse any iterable of characters (from a string or file content) into a token parser.

Here's a basic example:

use std::fs;

use rslnp::{Error, Parser};

fn main() -> Result<(), Error> {
    // Create a parser configured for SLN
    let parser = Parser::scopes();

    // Parse a string
    let input = r#"
# A comment
hello-world # Single symbol
list item1 item2 # List of items

# Multiline string
""""
    This is a multiline string.
    It preserves newlines and removes the indentation.
"#;

    let mut token_parser = parser.parse(input.chars())?;

    // Handle tokens using the token parser

    Ok(())
}

Strings are parsed into lists. If prefixed (configurable), they become a list with a prefix symbol (like "string") followed by the content symbol. Otherwise, it's a single content symbol.

For full details, see the API documentation.

Configuration

The parser is highly configurable via builder methods. Key options include:

Indentation: Set the number of spaces for one nesting level with indent(u8). Set to 0 to disable indentation-based nesting.
Unpack Single Elements: Use unpack_single(bool) to interpret lines with a single element as lists (or not).
Multi-Indent: Allow multiple indent levels per line with allow_multi_indent(bool).
Brackets: Add bracket pairs with with_brackets(left: char, right: char, prefix: Option<&str>) or disable with without_brackets().
Strings: Add delimiters with with_strings(delimiter: char, prefix: Option<&str>) or disable with without_strings().
Comments: Add comment starters with with_comments(char) or disable with without_comments().
Separators: Add inline list separators with with_separator(char) or disable with without_separator().
Symbol Characters: Add always-single-char symbols with with_symbol_character(char) or disable with without_symbol_character().

Example configuration:

let custom_parser = Parser::new()
    .indent(2) // 2 spaces per level
    .unpack_single(false)
    .with_brackets('[', ']', Some("array"))
    .with_strings('\'', None) // Single-quoted strings without prefix
    .with_comments(';'); // Semicolon comments

Adding rslnp library as a dependency

Adding `rslnp` library as a dependency