{"id":20348970,"url":"https://github.com/here-be/snapdragon-location","last_synced_at":"2025-04-12T01:22:27.568Z","repository":{"id":57364568,"uuid":"116663376","full_name":"here-be/snapdragon-location","owner":"here-be","description":"Adds a location object to snapdragon token or AST node.","archived":false,"fork":false,"pushed_at":"2018-01-08T11:07:26.000Z","size":26,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T12:01:46.735Z","etag":null,"topics":["ast","javascript","location","node","nodejs","parse","parser","position","snapdragon","token","tokenize","tokenizer"],"latest_commit_sha":null,"homepage":"https://github.com/here-be","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/here-be.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-08T10:36:24.000Z","updated_at":"2018-12-12T10:02:28.000Z","dependencies_parsed_at":"2022-09-13T21:01:10.221Z","dependency_job_id":null,"html_url":"https://github.com/here-be/snapdragon-location","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/here-be%2Fsnapdragon-location","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/here-be%2Fsnapdragon-location/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/here-be%2Fsnapdragon-location/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/here-be%2Fsnapdragon-location/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/here-be","download_url":"https://codeload.github.com/here-be/snapdragon-location/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248502037,"owners_count":21114726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","javascript","location","node","nodejs","parse","parser","position","snapdragon","token","tokenize","tokenizer"],"created_at":"2024-11-14T22:23:27.932Z","updated_at":"2025-04-12T01:22:27.541Z","avatar_url":"https://github.com/here-be.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# snapdragon-location [![NPM version](https://img.shields.io/npm/v/snapdragon-location.svg?style=flat)](https://www.npmjs.com/package/snapdragon-location) [![NPM monthly downloads](https://img.shields.io/npm/dm/snapdragon-location.svg?style=flat)](https://npmjs.org/package/snapdragon-location) [![NPM total downloads](https://img.shields.io/npm/dt/snapdragon-location.svg?style=flat)](https://npmjs.org/package/snapdragon-location) [![Linux Build Status](https://img.shields.io/travis/here-be/snapdragon-location.svg?style=flat\u0026label=Travis)](https://travis-ci.org/here-be/snapdragon-location)\n\n\u003e Adds a location object to snapdragon token or AST node.\n\nPlease consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/):\n\n```sh\n$ npm install --save snapdragon-location\n```\n\n## What does this do?\n\nAdds a `.loc` object to tokens that looks something like this:\n\n```js\n{\n  source: 'string',\n  start: { index: 0, column: 1, line: 1 },\n  end: { index: 3, column: 4, line: 1 },\n  range: [0, 3] // getter\n}\n```\n\nWhen used as [snapdragon-lexer](https://github.com/here-be-snapdragons/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](#location-objects) to tokens.\n\nThere is a more [detailed example](#example-usage) below.\n\n**Heads up!**\n\nIf you prefer `.position` over `.loc`, use [snapdragon-position](https://github.com/here-be/snapdragon-position) instead.\n\n## API\n\nThe main export is a function that can be [used as a plugin](#plugin-usage) with [snapdragon-lexer](https://github.com/here-be-snapdragons/snapdragon-lexer), or called directly with an instance of [snapdragon-lexer](https://github.com/here-be-snapdragons/snapdragon-lexer).\n\n### [location](index.js#L25)\n\nSets the `start` location and returns a function for setting the `end` location.\n\n**Params**\n\n* `name` **{String|Object}**: (optional) Snapdragon Lexer or Tokenizer instance, or the name to use for the location property on the token. Default is `toc`.\n* `target` **{Object}**: Snapdragon Lexer or Tokenizer instance\n* `returns` **{Function}**: Returns a function that takes a `token` as its only argument\n\n**Example**\n\n```js\nconst location = require('snapdragon-location');\nconst Lexer = require('snapdragon-lexer');\nconst lexer = new Lexer('foo/bar');\n\nlexer.capture('slash', /^\\//);\nlexer.capture('text', /^\\w+/);\n\nconst loc = location(lexer);\nconst token = loc(lexer.advance());\nconsole.log(token);\n```\n\n### [.plugin](index.js#L51)\n\nUse as a plugin to add a `.location` method to your [snapdragon-lexer](https://github.com/here-be-snapdragons/snapdragon-lexer) or [snapdragon-tokenizer][] instance to automatically add a location object to tokens when the `.lex()` or `.handle()` methods are used.\n\n**Example**\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst location = require('snapdragon-location');\nconst lexer = new Lexer();\nlexer.use(location());\n```\n\n### [.position](index.js#L73)\n\nGet the current source position, with `index`, `column` and `line`. Used by [.location()](#location) to create the \"start\" and \"end\" positions.\n\n* `returns` **{Object}**: Returns an object with the current source position.\n\n**Example**\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst lexer = new Lexer();\nconsole.log(lexer.position());\n//=\u003e Position { index: 0, column: 0, line: 1 };\n```\n\n### [.location](index.js#L97)\n\nReturns a function for getting the current location.\n\n* `returns` **{Function}**: Returns a function that takes a `token` as its only argument, and patches a `.loc` property onto the token.\n\n**Example**\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst lexer = new Lexer('foo/bar');\nlexer.use(location());\n\nlexer.set('text', function(tok) {\n  // get start location before advancing lexer\n  const loc = this.location();\n  const match = this.match(/^\\w+/);\n  if (match) {\n    // get end location after advancing lexer (with .match)\n    return loc(this.token(match));\n  }\n});\n```\n\n**Params**\n\n* `start` **{Object}**: (required) Starting [position](#position)\n* `end` **{Object}**: (required) Ending [position](#position)\n* `target` **{Object}**: (optional) Snapdragon Lexer or Tokenizer instance\n* `returns` **{Object}**\n\n**Example**\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst Position = require('snapdragon-location').Position;\nconst lexer = new Lexer('foo/bar');\nlexer.capture('text', /^\\w+/);\nlexer.advance();\nconsole.log(new Position(lexer));\n//=\u003e Position { index: 3, column: 4, line: 1 }\n```\n\n**Params**\n\n* `start` **{Object}**: (required) Starting [position](#position)\n* `end` **{Object}**: (required) Ending [position](#position)\n* `target` **{Object}**: (optional) Snapdragon Lexer or Tokenizer instance\n* `returns` **{Object}**\n\n**Example**\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst location = require('snapdragon-position');\nconst lexer = new Lexer('foo/bar')\n  .capture('slash', /^\\//)\n  .capture('text', /^\\w+/);\n\nconst start = new location.Position(lexer);\nlexer.advance();\nconst end = new location.Position(lexer);\nconsole.log(new location.Location(start, end, lexer));\n// Location {\n//   source: undefined,\n//   start: Position { index: 0, column: 1, line: 1 },\n//   end: Position { index: 3, column: 4, line: 1 } }\n```\n\n### Plugin usage\n\nWhen used as a plugin, this adds a `.position()` method to a [snapdragon-lexer](https://github.com/here-be-snapdragons/snapdragon-lexer) instance, for adding [position information](#position-information) to tokens.\n\n**Example**\n\n```js\nconst location = require('snapdragon-location');\nconst Lexer = require('snapdragon-lexer');\nconst lexer = new Lexer('foo/bar');\nlexer.use(location());\n\nlexer.capture('slash', /^\\//);\nlexer.capture('text', /^\\w+/);\n\nvar token = lexer.advance();\nconsole.log(token);\n```\n\nAdds a `.loc` object to the token, like this:\n\n```js\nToken {\n  type: 'text',\n  value: 'foo',\n  match: [ 'foo', index: 0, input: 'foo/*' ],\n  loc: {\n    start: { index: 0, column: 1, line: 1 },\n    end: { index: 3, column: 4, line: 1 },\n    range: [0, 3] // getter\n  } \n}\n```\n\n## Token objects\n\nSee the [Token documentation](https://github.com/here-be/snapdragon-token/blob/master/README.md#token-object) for more details about the `Token` object.\n\n```js\ninterface Token {\n  type: string;\n  value: string;\n  match: array | undefined;\n  loc: Location;\n}\n```\n\n## Location objects\n\nThe `token.loc` property contains source string location information on the token.\n\n```js\ninterface Location {\n  source: string | undefined;\n  start: Position;\n  end: Position;\n  range: array (getter)\n}\n```\n\n* `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.\n* `start` **{object}** - start [position object](#position-objects), which is the position of the _first character of_ the lexed source string.\n* `end` **{object}** - end [position object](#position-objects), which is the position of the _last character of_ the lexed source string.\n* `range` **{array}** - getter that returns an array with the following values: `[loc.start.index, loc.end.index]`\n\n## Position objects\n\nEach `Position` object consists of an `index` number (0-based), a `column` number (0-based), and a `line` number (1-based):\n\n```js\ninterface Position {\n  index: number; // \u003e= 0\n  column: number; // \u003e= 0,\n  line: number; // \u003e= 1\n}\n```\n\n* `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.\n* `column` **{object}** - start [position object](#position-objects), which is the position of the _first character of_ the lexed source string.\n* `end` **{object}** - end [position object](#position-objects), which is the position of the _last character of_ the lexed source string.\n\n## Example usage\n\n```js\nconst Lexer = require('snapdragon-lexer');\nconst lexer = new Lexer('foo/*', { source: 'string' });\nlexer.use(location());\nlexer.capture('star', /^\\*/);\nlexer.capture('slash', /^\\//);\nlexer.capture('text', /^\\w+/);\n\nlexer.tokenize();\nconsole.log(lexer.tokens);\n```\n\nResults in:\n\n```js\n[\n  {\n    type: 'text',\n    val: 'foo',\n    match: ['foo', index: 0, input: 'foo/*'],\n    loc: {\n      source: 'string',\n      start: { index: 0, column: 1, line: 1 },\n      end: { index: 3, column: 4, line: 1 },\n      range: [0, 3]\n    }\n  },\n  {\n    type: 'slash',\n    val: '/',\n    match: ['/', index: 0, input: '/*'],\n    loc: {\n      source: 'string',\n      start: { index: 3, column: 4, line: 1 },\n      end: { index: 4, column: 5, line: 1 },\n      range: [3, 4]\n    }\n  },\n  {\n    type: 'star',\n    val: '*',\n    match: ['*', index: 0, input: '*'],\n    loc: {\n      source: 'string',\n      start: { index: 4, column: 5, line: 1 },\n      end: { index: 5, column: 6, line: 1 },\n      range: [4, 5]\n    }\n  }\n]\n```\n\n## About\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/summary\u003e\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).\n\nPlease read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRunning Tests\u003c/strong\u003e\u003c/summary\u003e\n\nRunning and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:\n\n```sh\n$ npm install \u0026\u0026 npm test\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBuilding docs\u003c/strong\u003e\u003c/summary\u003e\n\n_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_\n\nTo generate the readme, run the following command:\n\n```sh\n$ npm install -g verbose/verb#dev verb-generate-readme \u0026\u0026 verb\n```\n\n\u003c/details\u003e\n\n### Related projects\n\nYou might also be interested in these projects:\n\n* [snapdragon-capture](https://www.npmjs.com/package/snapdragon-capture): Snapdragon plugin that adds a capture method to the parser instance. | [homepage](https://github.com/jonschlinkert/snapdragon-capture \"Snapdragon plugin that adds a capture method to the parser instance.\")\n* [snapdragon-node](https://www.npmjs.com/package/snapdragon-node): Snapdragon utility for creating a new AST node in custom code, such as plugins. | [homepage](https://github.com/jonschlinkert/snapdragon-node \"Snapdragon utility for creating a new AST node in custom code, such as plugins.\")\n* [snapdragon-util](https://www.npmjs.com/package/snapdragon-util): Utilities for the snapdragon parser/compiler. | [homepage](https://github.com/jonschlinkert/snapdragon-util \"Utilities for the snapdragon parser/compiler.\")\n\n### Author\n\n**Jon Schlinkert**\n\n* [linkedin/in/jonschlinkert](https://linkedin.com/in/jonschlinkert)\n* [github/jonschlinkert](https://github.com/jonschlinkert)\n* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)\n\n### License\n\nCopyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).\nReleased under the [MIT License](LICENSE).\n\n***\n\n_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on January 08, 2018._","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhere-be%2Fsnapdragon-location","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhere-be%2Fsnapdragon-location","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhere-be%2Fsnapdragon-location/lists"}