nom_locate

A special input type for nom to locate tokens

Documentation

The documentation of the crate is available here.

How to use it

The crate provide the LocatedSpan struct that encapsulates the data. Look at the below example and the explanations:

#[macro_use]
extern crate nom;
#[macro_use]
extern crate nom_locate;

use nom::types::CompleteStr;
use nom_locate::LocatedSpan;
type Span<'a> = LocatedSpan<CompleteStr<'a>>;

struct Token<'a> {
    pub position: Span<'a>,
    pub foo: String,
    pub bar: String,
}

named!(parse_foobar( Span ) -> Token, do_parse!(
    take_until!("foo") >>
    position: position!() >>
    foo: tag!("foo") >>
    bar: tag!("bar") >>
    (Token {
        position: position,
        foo: foo.to_string(),
        bar: bar.to_string()
    })
));

fn main () {
    let input = Span::new(CompleteStr("Lorem ipsum \n foobar"));
    let output = parse_foobar(input);
    let position = output.unwrap().1.position;
    assert_eq!(position, Span {
        offset: 14,
        line: 2,
        fragment: CompleteStr("")
    });
    assert_eq!(position.get_column(), 2);
}

Import

Import nom and nom_locate.

#[macro_use]
extern crate nom;
extern crate nom_locate;

use nom_locate::LocatedSpan;

Also you'd probably create type alias for convenience so you don't have to specify the fragment type every time:

type Span = LocatedSpan<CompleteStr>;

Note you'd better in most case use CompleteStr in order to optimize your parser.

Define the output structure

The output structure of your parser may contain the position as a Span (which provides the index, line and column information to locate your token).

struct Token<'a> {
    pub position: Span<'a>,
    pub foo: String,
    pub bar: String,
}

Create the parser

The parser has to accept a Span as an input. You may use position!() in your nom parser, in order to capture the location of your token:

named!(parse_foobar( Span ) -> Token, do_parse!(
    take_until!("foo") >>
    position: position!() >>
    foo: tag!("foo") >>
    bar: tag!("bar") >>
    (Token {
        position: position,
        foo: foo.to_string(),
        bar: bar.to_string()
    })
));

Call the parser

The parser returns a nom::IResult<Token, _> (hence the unwrap().1). The position property contains the offset, line and column.

fn main () {
    let input = Span::new("Lorem ipsum \n foobar");
    let output = parse_foobar(input);
    let position = output.unwrap().1.position;
    assert_eq!(position, Span {
        offset: 14,
        line: 2,
        fragment: ""
    });
    assert_eq!(position.get_column(), 2);
}