.verb.md

What does this do?

Adds a .position 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 .position() method to the instance and patches the lexer.lex() and lexer.handle() methods to automatically add position objects to tokens.

There is a more detailed example below.

Heads up!

If you would prefer for the property name to be token.loc rather than token.position, use [snapdragon-location][] 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 position = require('snapdragon-position');
const Lexer = require('snapdragon-lexer');
const lexer = new Lexer('foo/bar');
lexer.use(position());

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

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

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

Token {
  type: 'text',
  value: 'foo',
  match: [ 'foo', index: 0, input: 'foo/*' ],
  position: {
    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;
  position: Position;
}

Position objects

The token.position property contains source string position information on the token.

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

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

Location objects

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

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

• line {string|undefined} - the source position provided by lexer.options.source. Typically this is a filename, but could also be string or any user defined value.
• column {object} - start location object, which is the location of the first character of the lexed source string.
• end {object} - end location object, which is the location 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(position());
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/*'],
    position: {
      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: '/*'],
    position: {
      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: '*'],
    position: {
      source: 'string',
      start: { index: 4, column: 5, line: 1 },
      end: { index: 5, column: 6, line: 1 },
      range: [4, 5]
    }
  }
]