snapdragon-location

Adds a location object to snapdragon token or AST node.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

1$ npm install --save snapdragon-location

What does this do?

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

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

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.

location

Sets the start location and returns a function for setting the end location.

Params

• name {String|Object}: (optional) Snapdragon Lexer or Tokenizer instance, or the name to use for the location property on the token. Default is toc.
• target {Object}: Snapdragon Lexer or Tokenizer instance
• returns {Function}: Returns a function that takes a token as its only argument

Example

1const location = require('snapdragon-location');
2const Lexer = require('snapdragon-lexer');
3const lexer = new Lexer('foo/bar');
4
5lexer.capture('slash', /^\//);
6lexer.capture('text', /^\w+/);
7
8const loc = location(lexer);
9const token = loc(lexer.advance());
10console.log(token);

.plugin

Use as a plugin to add a .location method to your snapdragon-lexer or [snapdragon-tokenizer][] instance to automatically add a location object to tokens when the .lex() or .handle() methods are used.

Example

1const Lexer = require('snapdragon-lexer');
2const location = require('snapdragon-location');
3const lexer = new Lexer();
4lexer.use(location());

.position

Get the current source position, with index, column and line. Used by .location() to create the "start" and "end" positions.

• returns {Object}: Returns an object with the current source position.

Example

1const Lexer = require('snapdragon-lexer');
2const lexer = new Lexer();
3console.log(lexer.position());
4//=> Position { index: 0, column: 0, line: 1 };

.location

Returns a function for getting the current location.

• returns {Function}: Returns a function that takes a token as its only argument, and patches a .loc property onto the token.

Example

1const Lexer = require('snapdragon-lexer');
2const lexer = new Lexer('foo/bar');
3lexer.use(location());
4
5lexer.set('text', function(tok) {
6  // get start location before advancing lexer
7  const loc = this.location();
8  const match = this.match(/^\w+/);
9  if (match) {
10    // get end location after advancing lexer (with .match)
11    return loc(this.token(match));
12  }
13});

Params

• start {Object}: (required) Starting position
• end {Object}: (required) Ending position
• target {Object}: (optional) Snapdragon Lexer or Tokenizer instance
• returns {Object}

Example

1const Lexer = require('snapdragon-lexer');
2const Position = require('snapdragon-location').Position;
3const lexer = new Lexer('foo/bar');
4lexer.capture('text', /^\w+/);
5lexer.advance();
6console.log(new Position(lexer));
7//=> Position { index: 3, column: 4, line: 1 }

Params

• start {Object}: (required) Starting position
• end {Object}: (required) Ending position
• target {Object}: (optional) Snapdragon Lexer or Tokenizer instance
• returns {Object}

Example

1const Lexer = require('snapdragon-lexer');
2const location = require('snapdragon-position');
3const lexer = new Lexer('foo/bar')
4  .capture('slash', /^\//)
5  .capture('text', /^\w+/);
6
7const start = new location.Position(lexer);
8lexer.advance();
9const end = new location.Position(lexer);
10console.log(new location.Location(start, end, lexer));
11// Location {
12//   source: undefined,
13//   start: Position { index: 0, column: 1, line: 1 },
14//   end: Position { index: 3, column: 4, line: 1 } }

Plugin usage

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

Example

1const location = require('snapdragon-location');
2const Lexer = require('snapdragon-lexer');
3const lexer = new Lexer('foo/bar');
4lexer.use(location());
5
6lexer.capture('slash', /^\//);
7lexer.capture('text', /^\w+/);
8
9var token = lexer.advance();
10console.log(token);

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

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

Token objects

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

1interface Token {
2  type: string;
3  value: string;
4  match: array | undefined;
5  loc: Location;
6}

Location objects

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

1interface Location {
2  source: string | undefined;
3  start: Position;
4  end: Position;
5  range: array (getter)
6}

• 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):

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

• 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

1const Lexer = require('snapdragon-lexer');
2const lexer = new Lexer('foo/*', { source: 'string' });
3lexer.use(location());
4lexer.capture('star', /^\*/);
5lexer.capture('slash', /^\//);
6lexer.capture('text', /^\w+/);
7
8lexer.tokenize();
9console.log(lexer.tokens);

Results in:

1[
2  {
3    type: 'text',
4    val: 'foo',
5    match: ['foo', index: 0, input: 'foo/*'],
6    loc: {
7      source: 'string',
8      start: { index: 0, column: 1, line: 1 },
9      end: { index: 3, column: 4, line: 1 },
10      range: [0, 3]
11    }
12  },
13  {
14    type: 'slash',
15    val: '/',
16    match: ['/', index: 0, input: '/*'],
17    loc: {
18      source: 'string',
19      start: { index: 3, column: 4, line: 1 },
20      end: { index: 4, column: 5, line: 1 },
21      range: [3, 4]
22    }
23  },
24  {
25    type: 'star',
26    val: '*',
27    match: ['*', index: 0, input: '*'],
28    loc: {
29      source: 'string',
30      start: { index: 4, column: 5, line: 1 },
31      end: { index: 5, column: 6, line: 1 },
32      range: [4, 5]
33    }
34  }
35]

About

1$ npm install && npm test

1$ npm install -g verbose/verb#dev verb-generate-readme && verb

Related projects

You might also be interested in these projects:

• snapdragon-capture: Snapdragon plugin that adds a capture method to the parser instance. | homepage
• snapdragon-node: Snapdragon utility for creating a new AST node in custom code, such as plugins. | homepage
• snapdragon-util: Utilities for the snapdragon parser/compiler. | homepage

Author

Jon Schlinkert

• linkedin/in/jonschlinkert
• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on January 08, 2018.