.verb.md

What does this do?

Adds a .loc object to tokens that looks something like this:

{
  source: 'string',
  start: { index: 0, column: 1, line: 1 },
  end: { index: 3, column: 4, line: 1 },
  range: [0, 3] // getter
}

When used as [snapdragon-lexer][] plugin, this adds a .location() method to the instance and patches the lexer.lex() and lexer.handle() methods to automatically add location objects to tokens.

There is a more detailed example below.

Heads up!

If you prefer .position over .loc, use [snapdragon-position][] instead.

API

The main export is a function that can be used as a plugin with [snapdragon-lexer][], or called directly with an instance of [snapdragon-lexer][].

{%= apidocs("index.js") %}

Plugin usage

When used as a plugin, this adds a .position() method to a snapdragon-lexer instance, for adding position information to tokens.

Example

const location = require('snapdragon-location');
const Lexer = require('snapdragon-lexer');
const lexer = new Lexer('foo/bar');
lexer.use(location());

lexer.capture('slash', /^\//);
lexer.capture('text', /^\w+/);

var token = lexer.advance();
console.log(token);

Adds a .loc object to the token, like this:

Token {
  type: 'text',
  value: 'foo',
  match: [ 'foo', index: 0, input: 'foo/*' ],
  loc: {
    start: { index: 0, column: 1, line: 1 },
    end: { index: 3, column: 4, line: 1 },
    range: [0, 3] // getter
  } 
}

Token objects

See the Token documentation for more details about the Token object.

interface Token {
  type: string;
  value: string;
  match: array | undefined;
  loc: Location;
}

Location objects

The token.loc property contains source string location information on the token.

interface Location {
  source: string | undefined;
  start: Position;
  end: Position;
  range: array (getter)
}

• source {string|undefined} - the source location provided by lexer.options.source. Typically this is a filename, but could also be string or any user defined value.
• start {object} - start position object, which is the position of the first character of the lexed source string.
• end {object} - end position object, which is the position of the last character of the lexed source string.
• range {array} - getter that returns an array with the following values: [loc.start.index, loc.end.index]

Position objects

Each Position object consists of an index number (0-based), a column number (0-based), and a line number (1-based):

interface Position {
  index: number; // >= 0
  column: number; // >= 0,
  line: number; // >= 1
}

• line {string|undefined} - the source location provided by lexer.options.source. Typically this is a filename, but could also be string or any user defined value.
• column {object} - start position object, which is the position of the first character of the lexed source string.
• end {object} - end position object, which is the position of the last character of the lexed source string.

Example usage

const Lexer = require('snapdragon-lexer');
const lexer = new Lexer('foo/*', { source: 'string' });
lexer.use(location());
lexer.capture('star', /^\*/);
lexer.capture('slash', /^\//);
lexer.capture('text', /^\w+/);

lexer.tokenize();
console.log(lexer.tokens);

Results in:

[
  {
    type: 'text',
    val: 'foo',
    match: ['foo', index: 0, input: 'foo/*'],
    loc: {
      source: 'string',
      start: { index: 0, column: 1, line: 1 },
      end: { index: 3, column: 4, line: 1 },
      range: [0, 3]
    }
  },
  {
    type: 'slash',
    val: '/',
    match: ['/', index: 0, input: '/*'],
    loc: {
      source: 'string',
      start: { index: 3, column: 4, line: 1 },
      end: { index: 4, column: 5, line: 1 },
      range: [3, 4]
    }
  },
  {
    type: 'star',
    val: '*',
    match: ['*', index: 0, input: '*'],
    loc: {
      source: 'string',
      start: { index: 4, column: 5, line: 1 },
      end: { index: 5, column: 6, line: 1 },
      range: [4, 5]
    }
  }
]