snapdragon-position

Snapdragon util and plugin for patching the position on an 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-position

What does this do?

Adds a .position 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 .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.

position

Sets the start position and returns a function for setting the end position on a token.

Params

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

Example

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

.plugin

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

Example

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

.location

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

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

Example

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

.position

Returns a function for getting the current position.

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

Example

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

Params

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

Example

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

Params

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

Example

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

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

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

Position objects

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

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

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

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

• 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

1const Lexer = require('snapdragon-lexer');
2const lexer = new Lexer('foo/*', { source: 'string' });
3lexer.use(position());
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    position: {
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    position: {
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    position: {
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.