{"id":26119459,"url":"https://github.com/mmontone/peggy-input","last_synced_at":"2026-05-20T05:32:31.529Z","repository":{"id":253876197,"uuid":"844740245","full_name":"mmontone/peggy-input","owner":"mmontone","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-14T11:44:04.000Z","size":1662,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T12:56:38.089Z","etag":null,"topics":["completion","html","javascript","parsing","syntax","web"],"latest_commit_sha":null,"homepage":"https://mmontone.github.io/peggy-input/","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/mmontone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-08-19T22:00:33.000Z","updated_at":"2024-11-14T11:44:08.000Z","dependencies_parsed_at":"2024-09-14T23:54:40.491Z","dependency_job_id":"2a8909b7-b885-4dbf-b94a-49e2ab7236e6","html_url":"https://github.com/mmontone/peggy-input","commit_stats":null,"previous_names":["mmontone/peggy-input"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mmontone/peggy-input","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmontone%2Fpeggy-input","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmontone%2Fpeggy-input/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmontone%2Fpeggy-input/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmontone%2Fpeggy-input/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmontone","download_url":"https://codeload.github.com/mmontone/peggy-input/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmontone%2Fpeggy-input/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271430780,"owners_count":24758372,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["completion","html","javascript","parsing","syntax","web"],"created_at":"2025-03-10T12:55:00.452Z","updated_at":"2026-05-20T05:32:31.500Z","avatar_url":"https://github.com/mmontone.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PEGGY INPUT\n\nAn HTML input element that provides syntax directed editing and completion based on a [Peggy](https://peggyjs.org/) PEG grammar.\n\n![PeggyInput](docs/peggy-input.gif)\n\n## Usage\n\nCall `PeggyInput` with the jQuery input element and a javascript object with:\n\n- grammar: A Peggy grammar with completion blocks for some of the rules.\n- completers: A javascript object to use for matching completions.\n\nThe `completers` object contains subobjects that specified \"completion rules\".\nA completion rule is a special rule with a Peggy `rule`, plus the completion `candidates`.\nThe Peggy grammar is expanded using the completers object.\n\nExample:\n\n```javascript\nconst users = ['Mariano Montone', 'Asgeir Bjørlykke', 'Martin Montone'];\nconst groups = ['Management', 'Administration', 'Human Resources'];\n\n({\n    'completers': {\n       'username' : {\n           'rule' : 'name',\n           'candidates' : users\n       },\n       'group' : {\n          'rule' : 'name',\n          'candidates' : groups\n       }\n    }\n})\n```\n\nThat means two Peggy rules are added to the original grammar.\nA `username` rule, that is parsed using the `name` rule.\nAnd a `group` rule, that is also parsed using `name`.\n\nThe `candidates` contain an array of completion candidates.\nA completion candidate should either a string, or an object with `label` and `value` members.\nWhen one of those rules match, they are completed using the specified candidates.\n\n### Options\n\n- `grammar`: String. Required. The Peggy grammar.\n- `completers`: Object. Required. Object with keys being the completer name, and value an object with `rule` and `candidates`. `rule` is the name of the Peggy rule to create.\n- `updateEvent`. String. Optional. The event for when the widget updates its status. By default, 'change' event is used. If you need a more instantanious widget, it is possible to use 'keyup' instead.\n- `showSyntaxErrorMsg`: Boolean. Optional. Default is `true`. When enabled show the syntax errors below the HTML input.\n- `onChange`: Function. Optional. A function handler that is invoked with the PeggyInput instance as argument when there's a change.\n- `errorMsgFormatter`. Function. Optional. A function that takes a PeggyInput instance and a Peggy SyntaxError and should return an error message string. `getExpectedDescription` could be useful to implement this function (see API below).\n- `validateWhenBlank`: Boolean. Optional. Default is true iff the input is required. Whether to validate the input and show an error when the input is blank.\n- `completionsCharCount`: Integer. Optional. Default is 0. The number of characters needed from the user to expand the list of completions candidates. Useful for when the number of completion candidates to filter out is big.\n- `caseSensitive`: Boolean. Optional. Default is false. Complete with case sensitivity or not.\n- `completionsAreaSize`: Integer. Optional. Number of elements to be shown in the completion area at a time. Default is 10. \n- `completionsAreaWidth`: Integer. Optional. Width of completions area, in pixels. Default is 400.\n\n#### Completer object\n\n- `rule` : The Peggy rule to match the completion.\n- `candidates`: \n   * An array of strings.\n   * An array of objects with `label` and `value` members.\n   * A string with an url from where to `fetch` the candidates.\n   * A function. Takes current entered prefix string and a PeggyInstance, and should return a Promise with a list of strings filtered by the prefix.\n- `charCount`: Integer. Optional. Default is `completionsCharCount`. The number of characters needed from the user to expand the list of the completion's candidates.\n\n### API\n\n- `isValid`: Returns `true` iff the current input value is a valid expression according to the provided grammar.\n- `getValue`: Returns the parsed value of the input, unless it is in an error state.\n- `getError`: Returns the current syntax error.\n- `getInput`: Access the HTML input element.\n- `getExpectedDescription`: Returns a description for the current syntax error.\n\n### User interface\n\nA completion area `\u003cselect\u003e` and an error message `\u003cp\u003e` elements are added beside the affected input.\n\nSize of completions area can be controlled with `completionsAreaSize` and `completionsAreaWidth` options.\n\nWhen the input is in an invalid state, it is marked as so, by adding an `error` class to it. Also, [setCustomValidity](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity) is called on the input with the parser error message.\n\n## Examples\n\n### Assignments language\n\nEdit a mini-language for assignments. There are users and groups of users.\nThe language has expressions like:\n- everyone but @Peter\n- members of Management but @John\n- ...\n\nSpecify the Peggy grammar:\n\n```javascript\nstart = assignment\nassignmentgroup = \"everyone\" / groupmembers\nassignment = g:assignmentgroup \" \" \"but \" as:assignees { return [g, {'not': as}] } / assignees\nassignee = \"everyone\" / user / groupmembers\nassignees = a:assignee WS \",\" WS as:assignees { return [a].concat(as) } / a:assignee { return [a] }\ngroupmembers = \"members of \" groups:groups { return {'membersOf':groups} }\ngroups = g:group WS \",\" WS gs:groups { return [g].concat(gs) } / g:group { return [g] }\nuser = \"@\" username:username { return {'user':username} }\nWS = [ \\t]*\nword = !\"but\" cs:(![ ,@] .)+ { return cs.map(c =\u003e c[1]).join('') }\nname = word:word \" \" name:name { return word + \" \" + name } / word\n```\n\nCreate an HTML input element:\n\n```html\n\u003cinput id=\"input\" type=\"text\" style=\"width: 400px;\"\u003e\u003c/input\u003e\n```\n\nInstantiate a PeggyInput passing the grammar and completers as options:\n\n```javascript\nconst users = ['Mariano Montone', 'Asgeir Bjorlykke', 'Martin Montone', 'Fernando Berretti'];\nconst groups = ['Management', 'Administration', 'Human Resources'];\nPeggyInput('#input',\n          {\n              'grammar': grammar,\n              'completers': {\n                  'username' : {\n                      'rule' : 'name',\n                      'candidates' : users\n                  },\n                  'group' : {\n                      'rule' : 'name',\n                      'candidates' : groups\n                  }\n              }\n          }\n      );\n```\n\n## How it works\n\nThe algorithm is based on the following: try to parse the input using the given PEG grammar. When an error ocurrs, that error contains the expected input at point. The expected input is used to provide the completions.\n\n## Development\n\n`npm install`\n\nRun `make`, `make clean`, `make rebuild`.\n\nOr build via NPM:\n\n`npm run build`\n\n### Debug logs\n\n`peggyInputInstance.logger.setLevel('debug');`\n\n## Demo\n\n`npm install`\n\nRun `make start-demo`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmontone%2Fpeggy-input","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmontone%2Fpeggy-input","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmontone%2Fpeggy-input/lists"}