{"id":14384652,"url":"https://github.com/rse/pegjs-util","last_synced_at":"2025-04-19T09:58:51.914Z","repository":{"id":25092001,"uuid":"28512939","full_name":"rse/pegjs-util","owner":"rse","description":"Utility Class for PEG.js","archived":false,"fork":false,"pushed_at":"2024-03-08T21:51:43.000Z","size":79,"stargazers_count":32,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T21:55:49.199Z","etag":null,"topics":["peg","utility"],"latest_commit_sha":null,"homepage":"https://npmjs.com/pegjs-util","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-26T14:35:56.000Z","updated_at":"2024-05-04T03:24:55.000Z","dependencies_parsed_at":"2024-06-18T16:45:36.131Z","dependency_job_id":"b02a446f-b572-48b6-b200-370ebdee8182","html_url":"https://github.com/rse/pegjs-util","commit_stats":{"total_commits":132,"total_committers":2,"mean_commits":66.0,"dds":0.007575757575757569,"last_synced_commit":"55645edf49cbea9c923be91fedbd7b235473eef8"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fpegjs-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fpegjs-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fpegjs-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fpegjs-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/pegjs-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249670023,"owners_count":21308669,"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":["peg","utility"],"created_at":"2024-08-28T18:01:33.087Z","updated_at":"2025-04-19T09:58:51.898Z","avatar_url":"https://github.com/rse.png","language":"JavaScript","readme":"\npegjs-util\n===========\n\nThis is a small utility class for the excellent\n[Peggy](https://peggyjs.org) (formerly [PEG.js](http://pegjs.org/))\nparser generator which wraps around Peggy's central `parse` function\nand provides three distinct convenience features: *Parser Tree Token\nUnrolling*, *Abstract Syntax Tree Node Generation* and *Cooked Error\nReporting*.\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/pegjs-util.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/rse/pegjs-util.png\" alt=\"\"/\u003e\n\nInstallation\n------------\n\n```shell\n$ npm install peggy pegjs-util\n```\n\nUsage\n-----\n\n#### sample.pegjs\n\n```\n{\n    var unroll = options.util.makeUnroll(location, options)\n    var ast    = options.util.makeAST   (location, options)\n}\n\nstart\n    = _ seq:id_seq _ {\n          return ast(\"Sample\").add(seq)\n      }\n\nid_seq\n    = id:id ids:(_ \",\" _ id)* {\n          return ast(\"IdentifierSequence\").add(unroll(id, ids, 3))\n      }\n\nid\n    = id:$([a-zA-Z_][a-zA-Z0-9_]*) {\n          return ast(\"Identifier\").set(\"name\", id)\n      }\n\n_ \"blank\"\n    = (co / ws)*\n\nco \"comment\"\n    = \"//\" (![\\r\\n] .)*\n    / \"/*\" (!\"*/\" .)* \"*/\"\n\nws \"whitespaces\"\n    = [ \\t\\r\\n]+\n```\n\n#### sample.js\n\n```js\nvar fs      = require(\"fs\")\nvar ASTY    = require(\"asty\")\nvar PEG     = require(\"peggy\")\nvar PEGUtil = require(\"pegjs-util\")\n\nvar asty = new ASTY()\nvar parser = PEG.generate(fs.readFileSync(\"sample.pegjs\", \"utf8\"))\nvar result = PEGUtil.parse(parser, fs.readFileSync(process.argv[2], \"utf8\"), {\n    startRule: \"start\",\n    makeAST: function (line, column, offset, args) {\n        return asty.create.apply(asty, args).pos(line, column, offset)\n    }\n})\nif (result.error !== null)\n    console.log(\"ERROR: Parsing Failure:\\n\" +\n        PEGUtil.errorMessage(result.error, true).replace(/^/mg, \"ERROR: \"))\nelse\n    console.log(result.ast.dump().replace(/\\n$/, \"\"))\n```\n\n#### Example Session\n\n```shell\n$ cat sample-input-ok.txt\n/*  some ok input  */\nfoo, bar, quux\n\n$ node sample.js sample-input-ok.txt\nSample [1/1]\n    IdentifierSequence [2/1]\n        Identifier (name: \"foo\") [2/1]\n        Identifier (name: \"bar\") [2/6]\n        Identifier (name: \"quux\") [2/11]\n\n$ cat sample-input-bad.txt\n/*  some bad input  */\nfoo, bar, quux baz\n\n$ node sample.js sample-input-bad.txt\nERROR: Parsing Failure:\nERROR: line 2 (column 16):   */\\nfoo, bar, quux baz\\n\nERROR: -----------------------------------------^\nERROR: Expected \",\" or end of input but \"b\" found.\n```\n\nDescription\n-----------\n\nPEGUtil is a small utility class for the excellent\n[Peggy](https://peggyjs.org) (formerly [PEG.js](http://pegjs.org/))\nparser generator. It wraps around Peggy's central `parse` function and\nprovides three distinct convenience features:\n\n### Parser Tree Token Unrolling\n\nIn many Peggy gammar rule actions you have to concatenate a first token\nand a repeated sequence of tokens, where from the sequence of tokens\nonly relevant ones should be picked:\n\n```\nid_seq\n    = id:id ids:(_ \",\" _ id)* {\n          return unroll(id, ids, 3)\n      }\n```\n\nHere the `id_seq` rule returns an array of ids, consisting of the first\ntoken `id` and then all 4th tokens from each element of the `ids`\nrepetition.\n\nThe `unroll` function has the following signature:\n\n```\nunroll(first: Token, list: Token[], take: Number): Token[]\nunroll(first: Token, list: Token[], take: Number[]): Token[]\n```\n\nIt accepts `first` to be also `null` (and then skips this) and `take`\ncan be either just a single position (counting from 0) or a list of\npositions.\n\nTo make the `unroll` function available to your rule actions code,\nplace the following at the top of your grammar definition:\n\n```js\n{\n    var unroll = options.util.makeUnroll(location, options)\n}\n```\n\nThe `options.util` above points to the PEGUtil API and is made available\nautomatically by using `PEGUtil.parse` instead of Peggy's standard\nparser method `parse`.\n\n### Abstract Syntax Tree Node Generation\n\nUsually the result of Peggy grammar rule actions should\nbe the generation of an Abstract Syntax Tree (AST) node.\nFor this libraries like e.g. [ASTy](http://github.com/rse/asty) can be used.\n\n```\nid_seq\n    = id:id ids:(_ \",\" _ id)* {\n          return ast(\"IdentifierSequence\").add(unroll(id, ids, 3))\n      }\n```\n\nHere the result is an AST node of type `IdentifierSequence`\nwhich contains no attributes but all identifiers as child nodes.\n\nTo make the `ast` function available to your rule actions code,\nplace the following at the top of your grammar definition:\n\n```js\n{\n    var ast = options.util.makeAST(location, options)\n}\n```\n\nAdditionally, before performing the parsing step, your\napplication has to tell PEGUtil how to map this call\nonto the underlying AST implementation. For [ASTy](http://github.com/rse/asty) you\ncan use a `makeAST` function like:\n\n```js\nfunction (line, column, offset, args) {\n    return ASTY.apply(null, args).pos(line, column, offset)\n}\n```\n\nThe `args` argument is an array containing all arguments\nyou supply to the generated `ast()` function. For\n[ASTy](http://github.com/rse/asty) this would be\nat least the type of the AST node.\n\nThe `options.util` above again points to the PEGUtil API and is made available\nautomatically by using `PEGUtil.parse` instead of Peggy's standard\nparser method `parse`.\n\n### Cooked Error Reporting\n\nInstead of calling the regular Peggy `parser.parse(source[,\nstartRule])` you now should call `PEGUtil.parse(parser, source[,\nstartRule])`. The result then is always an object consisting of either\nan `ast` field (in case of success) or an `error` field (in case of an\nerror).\n\nIn case of an error, the `error` field provides cooked error information\nwhich allow you to print out reasonable human-friendly error messages\n(especially because of the detailed `location` field):\n\n```js\nresult = {\n    error: {\n        line:     Number, /* line number */\n        column:   Number, /* column number */\n        message:  String, /* parsing error message */\n        found:    String, /* found token during parsing */\n        expected: String, /* expected token during parsing */\n        location: {\n            prolog: String, /* text before the error token */\n            token:  String, /* error token */\n            epilog: String  /* text after the error token */\n        }\n    }\n}\n```\n\nFor convenience reasons you can render a standard human-friendly\nerror message out of this information with\n`PEGUtil.errorMessage(result.error)`.\n\nLicense\n-------\n\nCopyright (c) 2014-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fpegjs-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Fpegjs-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fpegjs-util/lists"}