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:

``sh
$ npm install --save snapdragon-position
`

What does this do?

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

`js
{
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.

$3

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

`js
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);
`

$3

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

`js
const Lexer = require('snapdragon-lexer');
const position = require('snapdragon-position');
const lexer = new Lexer();
lexer.use(position());
`

$3

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

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

$3

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

`js
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

`js
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

`js
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 } }
`

$3

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

Example

`js
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:

`js
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.

`js
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.

`js
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):

`js
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

`js
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:

`js
[
{
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

$3

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

$3

Jon Schlinkert

* linkedin/in/jonschlinkert
* github/jonschlinkert
* twitter/jonschlinkert

$3

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

*

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