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 ❤️ and support.

Install

Install with npm:

$ npm install --save snapdragon-position

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.

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

const position = require('snapdragon-position');
const Lexer = require('snapdragon-lexer');
const lexer = new Lexer('foo/bar');
 
lexer.capture('slash', /^\//);
lexer.capture('text', /^\w+/);
 
const pos = position(lexer);
const token = pos(lexer.advance());
console.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

const Lexer = require('snapdragon-lexer');
const position = require('snapdragon-position');
const lexer = new Lexer();
lexer.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

const Lexer = require('snapdragon-lexer');
const lexer = new Lexer();
console.log(lexer.location());
//=> 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

const Lexer = require('snapdragon-lexer');
const lexer = new Lexer('foo/bar');
lexer.use(position());
 
lexer.set('text', function(tok) {
  // get start position before advancing lexer
  const pos = this.position();
  const match = this.match(/^\w+/);
  if (match) {
    // get end position after advancing lexer (with .match)
    return pos(this.token(match));
  }
});

Params

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

Example

const Lexer = require('snapdragon-lexer');
const Location = require('snapdragon-position').Location;
const lexer = new Lexer('foo/bar');
lexer.capture('text', /^\w+/);
lexer.advance();
console.log(new Location(lexer));
//=> 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

const Lexer = require('snapdragon-lexer');
const position = require('snapdragon-location');
const lexer = new Lexer('foo/bar')
  .capture('slash', /^\//)
  .capture('text', /^\w+/);
 
const start = new position.Location(lexer);
lexer.advance();
const end = new position.Location(lexer);
console.log(new position.Position(start, end, lexer));
// Position {
//   source: undefined,
//   start: Location { index: 0, column: 1, line: 1 },
//   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

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]
    }
  }
]

About

$ npm install && npm test

$ 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.