Crate minparser 

Simple parsing tools

This crate is a collection of objects and algorithms shared among different crates that needs to implement a parser.

A Position<F> is an object that identifies a (textual) file and a position inside it, represented as a line index and a column index. The main role of a Position object is to uniquely identify a single character or a token inside a file in order to allow the user to easily find it.

A View<'a, F> can be seen as a suffix of a larger string with the position of its first character. The match_tool and the match_atom methods can be used to match its prefix with any object implementing the ParseTool and the Atom traits respectively.

Many useful parsing tools can be found in atomlist and utils modules.

Usage example

use minparser::prelude::*;
let view = ViewFile::new_default("My string   value");
let (mtc, step) = view.match_atom_string("My string").unwrap();
assert_eq!(mtc, "My string");
assert_eq!(step.get_view(), "   value"); 
//let step = step.match_tool(minparser::utils::WhiteTool).unwrap();   // Use the WhiteTool tool to
//assert_eq!(step.get_view(), "value");                               //match a sequence of whitespaces
//assert!(step.match_tool('a').is_err()); // A missing match is an error

Main objects

Position<F> and Pos<T, F>.

A Position<F> is an object that holds a location inside a pool of different resources, where each resource can be identified as a string of textual data.

These object holds the following information:

• a file field of type F that identify a single resource inside your pool. Its type is provided by the user. If you work on a single resource then you should use NoFile as file.
• a position inside such resource, which is represented as the line number and column number, both of type u32. Lines here can be separated by either \n or \r\n, and it is an error if any \r character in the resource is not followed by the \n character.

The Pos<T, F> is just a pairing of an object of type T and a Position<F>.

View<'a, F>

A View<'a, F> holds a reference to a str with lifetime 'a and a Position<F> that locates the first character inside the resources pool. The most important method is match_tool that tests if any prefix of the view matches the provided pattern (called here tool) and if it matches then it strips away the matched prefix, or an error if no prefix matches it.

Tip: If you want to evaluate the original view after a missing match then you can clone it (which is possible when F implements Clone).

Atoms and Tools

An atom is an object that implements the Atom trait. Instead, a tool is an object that implements the ParseTool trait. Both these objects incapsulates patterns that a string prefix may or may not satisfy. Their main difference involes missed matches: an Atom that doesn’t match a string prefix reports the Position of its failure exatly at the beginning of the prefix, whereas a ParseTool can be more precise about where the failure happened. You can see an Atom just as an atomic element: it can only match or not match. A ParseTool instead can be viewed as a compound objects which each element can fail indipendently.

Moreover, a ParseTool can optionally return additional data other than the matched prefix.

Documented features

A list of features you can optionally enable. None of these are enabled by default:

• alloc: Links the library with the alloc crate and enable associated functions that works with Vec and other containers in alloc;
• nightly-features: Enable experimental features. Warning: it requires nightly builds and breaking changes may be introduced even at minor releases.

Modules

atomlist

Some usefult parsing atoms;

atoms

Parsing atoms

chains

Items that can be used both as Atom and as ParseTool.

pos

Positions.

predicates

Simple predicates for characters.

prelude

Crate prelude

utils

Other useful parsing tools.

view

View and other associated utilities.