{"id":23642422,"url":"https://github.com/sogaiu/janet-pegdoc","last_synced_at":"2026-01-24T07:32:22.027Z","repository":{"id":147780796,"uuid":"618504645","full_name":"sogaiu/janet-pegdoc","owner":"sogaiu","description":"Janet PEG Specials Multi-Tool","archived":false,"fork":false,"pushed_at":"2025-05-12T10:26:35.000Z","size":494,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-19T14:04:43.804Z","etag":null,"topics":["command-line-tool","doc","janet","peg","quiz","usages"],"latest_commit_sha":null,"homepage":"","language":"Janet","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/sogaiu.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,"zenodo":null}},"created_at":"2023-03-24T16:00:16.000Z","updated_at":"2025-05-12T10:26:38.000Z","dependencies_parsed_at":"2023-11-08T12:32:22.543Z","dependency_job_id":"47ee4f15-022f-4771-bcee-b67e7fd6188e","html_url":"https://github.com/sogaiu/janet-pegdoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sogaiu/janet-pegdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-pegdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-pegdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-pegdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-pegdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sogaiu","download_url":"https://codeload.github.com/sogaiu/janet-pegdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-pegdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28718960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T05:53:42.649Z","status":"ssl_error","status_checked_at":"2026-01-24T05:53:41.698Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["command-line-tool","doc","janet","peg","quiz","usages"],"created_at":"2024-12-28T10:50:53.385Z","updated_at":"2026-01-24T07:32:22.022Z","avatar_url":"https://github.com/sogaiu.png","language":"Janet","funding_links":[],"categories":[],"sub_categories":[],"readme":"# janet-pegdoc (pdoc)\n\nTool for doc lookups, usages, and quizzes of [Janet's PEG\nspecials](https://janet-lang.org/docs/peg.html).\n\n`pdoc` manifests itself as a command line tool as well as a macro.\n\n## Installation\n\nQuick:\n\n```\njpm install https://github.com/sogaiu/janet-pegdoc\n```\nManual:\n\n```\ngit clone https://github.com/sogaiu/janet-pegdoc\ncd janet-pegdoc\njpm install\n```\n\nIn either case, success should lead to the command `pdoc` being\navailable on `PATH` and a `pegdoc` directory within a directory on\n`JANET_PATH`.\n\n## CLI Invocation Examples\n\nShow doc and usages for a peg special.\n\n```\n$ pdoc any\n\n`(any patt)`\n\nMatches 0 or more repetitions of `patt`\n\n####################################################################\n\n# any with empty string\n(peg/match ~(any \"a\")\n           \"\")\n# =\u003e\n@[]\n\n# any\n(peg/match ~(any \"a\")\n           \"aa\")\n# =\u003e\n@[]\n\n# any with capture\n(peg/match ~(capture (any \"a\"))\n           \"aa\")\n# =\u003e\n@[\"aa\"]\n```\n\nShow just doc for the peg special `to`.\n\n```\n$ pdoc -d to\n\n`(to patt)`\n\nMatch up to `patt` (but not including it).\n\nIf the end of the input is reached and `patt` is not matched, the entire\npattern does not match.\n```\n\nShow just usages for a peg special.\n\n```\n$ pdoc -u if\n\n(peg/match ~(if 1 \"a\")\n           \"a\")\n# =\u003e\n@[]\n\n(peg/match ~(if 5 (set \"eilms\"))\n           \"smile\")\n# =\u003e\n@[]\n\n(peg/match ~(if 5 (set \"eilms\"))\n           \"wink\")\n# =\u003e\nnil\n```\n\nAsk for a quiz question and have your answer checked.\n\n```\n$ pdoc --quiz replace\n(peg/match ~(replace (sequence (capture \"ca\")\n                               (_______ \"t\"))\n                     ,(fn [one two]\n                        (string one two \"alog\")))\n           \"cat\")\n# =\u003e\n@[\"catalog\"]\n\nWhat value could work in the blank?\n```\n\nGet basic help.\n\n```\nUsage: pdoc [option] [peg-special]\n\nView Janet PEG information.\n\n  -h, --help                   show this output\n\n  -d, --doc [\u003cpeg-special\u003e]    show doc\n  -q, --quiz [\u003cpeg-special\u003e]   show quiz question\n  -u, --usage [\u003cpeg-special\u003e]  show usage\n\n  --bash-completion            output bash-completion bits\n  --fish-completion            output fish-completion bits\n  --zsh-completion             output zsh-completion bits\n  --raw-all                    show all names for completion\n\nWith a peg-special, but no options, show docs and usages.\n\nIf any of \"boolean\", \"dictionary\", \"integer\", \"string\",\n\"struct\", or \"table\" are specified as the \"peg-special\",\nshow docs and usages about using those as PEG constructs.\n\nWith the `-d` or `--doc` option, show docs for specified\nPEG special, or if none specified, for a randomly chosen one.\n\nWith the `-q` or `--quiz` option, show quiz question for\nspecified PEG special, or if none specified, for a randomly\nchosen one.\n\nWith the `-u` or `--usage` option, show usages for\nspecified PEG special, or if none specified, for a randomly\nchosen one.\n\nWith no arguments, lists all PEG specials.\n\nBe careful to quote shortnames (e.g. *, -\u003e, \u003e, \u003c-, etc.)\nappropriately so the shell doesn't process them in an\nundesired fashion.\n```\n\n## Conveniences\n\n### Cheatsheet\n\nTry `pdoc` by itself to get a \"cheatsheet\" of sorts:\n\n```\n$ pdoc\n\nPrimitive Patterns\n  Integer (..., -1, 0, 1, ...)\n  range                  =  (range r1 ?r2 ... ?rn)\n  set                    =  (set chars)\n  String (\"...\")\n  Buffer (@\"...\")\n  Boolean (true, false)\n\nCombining Patterns\n  any                    =  (any patt)\n  at-least               =  (at-least n patt)\n  at-most                =  (at-most n patt)\n  backmatch              =  (backmatch ?tag)\n  between (opt, ?)       =  (between min max patt)\n  choice (+)             =  (choice patt-1 patt-2 ...)\n  if                     =  (if cond patt)\n  if-not                 =  (if-not cond patt)\n  look (\u003e)               =  (look offset ?patt)\n  not (!)                =  (not patt)\n  repeat (0, 1, 2, ...)  =  (repeat n patt)\n  sequence (*)           =  (sequence patt-1 patt-2 ...)\n  some                   =  (some patt)\n  split                  =  (split sep patt)\n  sub                    =  (sub window-patt patt)\n  thru                   =  (thru patt)\n  til                    =  (til sep patt)\n  to                     =  (to patt)\n\nCaptures\n  accumulate (%)         =  (accumulate pat ?tag)\n  argument               =  (argument n ?tag)\n  backref (-\u003e)           =  (backref prev-tag ?tag)\n  capture (\u003c-, quote)    =  (capture patt ?tag)\n  cms                    =  (cms patt fun ?tag)\n  cmt                    =  (cmt patt fun ?tag)\n  column                 =  (column ?tag)\n  constant               =  (constant k ?tag)\n  drop                   =  (drop patt)\n  error                  =  (error ?patt)\n  group                  =  (group patt ?tag)\n  int                    =  (int n ?tag)\n  int-be                 =  (int-be n ?tag)\n  lenprefix              =  (lenprefix n patt)\n  line                   =  (line ?tag)\n  nth                    =  (nth index patt ?tag)\n  number                 =  (number patt ?base ?tag)\n  only-tags              =  (only-tags patt)\n  position ($)           =  (position ?tag)\n  replace (/)            =  (replace patt subst ?tag)\n  uint                   =  (uint n ?tag)\n  uint-be                =  (uint-be n ?tag)\n  unref                  =  (unref rule ?tag)\n\nBuilt-ins\n  :a                     =  (range \"AZ\" \"az\")\n  :d                     =  (range \"09\")\n  :h                     =  (range \"09\" \"AF\" \"af\")\n  :s                     =  (set \" \\0\\f\\n\\r\\t\\v\")\n  :w                     =  (range \"09\" \"AZ\" \"az\")\n  :A                     =  (if-not :a 1)\n  :D                     =  (if-not :d 1)\n  :H                     =  (if-not :h 1)\n  :S                     =  (if-not :s 1)\n  :W                     =  (if-not :w 1)\n  :a+                    =  (some :a)\n  :d+                    =  (some :d)\n  :h+                    =  (some :h)\n  :s+                    =  (some :s)\n  :w+                    =  (some :w)\n  :A+                    =  (some :A)\n  :D+                    =  (some :D)\n  :H+                    =  (some :H)\n  :S+                    =  (some :S)\n  :W+                    =  (some :W)\n  :a*                    =  (any :a)\n  :d*                    =  (any :d)\n  :h*                    =  (any :h)\n  :s*                    =  (any :s)\n  :w*                    =  (any :w)\n  :A*                    =  (any :A)\n  :D*                    =  (any :D)\n  :H*                    =  (any :H)\n  :S*                    =  (any :S)\n  :W*                    =  (any :W)\n\nAliases\n  (! patt)               =  (not patt)\n  ($ ?tag)               =  (position ?tag)\n  (% patt ?tag)          =  (accumulate patt ?tag)\n  (* patt-1 ... patt-n)  =  (sequence patt-1 ... patt-n)\n  (+ patt-1 ... patt-n)  =  (choice patt-1 ... patt-n)\n  (-\u003e prev-tag ?tag)     =  (backref prev-tag ?tag)\n  (/ patt subst ?tag)    =  (replace patt subst ?tag)\n  (\u003c- patt ?tag)         =  (capture patt ?tag)\n  (\u003e offset ?patt)       =  (look offset ?patt)\n  (? patt)               =  (between 0 1 patt)\n  (1 patt)               =  (repeat 1 patt)\n  (2 patt)               =  (repeat 2 patt)\n  (3 patt)               =  (repeat 3 patt)\n  ...\n  (opt patt)             =  (between 0 1 patt)\n  (quote patt ?tag)      =  (capture patt ?tag)\n  'patt                  =  (capture patt)\n```\n\n### Flexible Option Position\n\nAs a convenience feature, options (e.g. `-u` or `-d`) can be specified\nbefore or after a PEG special, e.g. invoking:\n\n```\npdoc -d thru\n```\n\nshould yield the same result as:\n\n```\npdoc thru -d\n```\n\nThis was done so that quick editing of a previous command would be\nmore convenient for different uses.\n\nIf interested in a particular PEG special, may be you'd prefer to be\ninvoking `pdoc \u003cpeg-special\u003e -d` followed by `pdoc \u003cpeg-special\u003e -u`,\nand then may be even `pdoc \u003cpeg-special\u003e -q` for a quiz question.\n\nInstead, if interested in seeing usages for different PEG specials,\nmay be you'd prefer to be invoking `pdoc -u int` followed by\n`pdoc -u int-be` or `pdoc -u uint`.\n\n### Shell Completion\n\nThe PEG special argument to `pdoc` can be completed if using the bash\n/ fish / zsh shells with appropriate configuration.\n\nSo for example, pressing `TAB` after entering `pdoc a` might yield the\noutput:\n\n```\naccumulate  any         argument    at-least    at-most\n```\n\nTo set this up, invoke `pdoc` with one of the following for the\nrelevant shell:\n\n* `--bash-completion`\n* `--fish-completion`\n* `--zsh-completion`\n\nPut the resulting output in a location appropriate for the shell in\nuse.  Something along the lines of:\n\n* `bash` -\n    put output in file named `pdoc` in the directory at\n    `~/.local/share/bash-completion/complete/`\n\n* `fish` -\n    put output in file named `pdoc.fish` in the directory at\n    `~/.config/fish/completions/`\n\n* `zsh` -\n    put output in file named `_pdoc` and put it in a directory\n    that's on your `fpath`\n\nBelow are some links to resources that are probably much better than the bits above:\n\n* [bash](https://github.com/scop/bash-completion/blob/master/README.md#faq) --\n  look for `Where should I install my own local completions?`\n* [fish](https://fishshell.com/docs/current/completions.html#where-to-put-completions)\n* [zsh](https://zsh.sourceforge.io/Doc/Release/Completion-System.html) -- good luck...just kidding, see [this](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org) instead.\n\n## Use from REPL\n\nThere is a macro named `pdoc` (a bit like the built in `doc` macro)\nthat can be used from the REPL to look up PEG special documentation.\n\nOne way to use it is to start `janet` like:\n\n```\njanet -l pegdoc\n```\n\nThen at the REPL:\n\n```\nJanet 1.32.1-11d7af3f linux/x64/gcc - '(doc)' for help\nrepl:1:\u003e (pdoc if)\n\n\n    peg special\n\n    (if cond patt)\n\n    Tries to match patt only if cond matches as well.\n\n    cond will not produce any captures.\n\nnil\n```\n\nAlternatively, evaluate `(use pegdoc)` before invoking `(pdoc ...)`.\n\nSetting up one's user profile appropriately may be another way to make\n`pdoc` available (see `-R` and/or `JANET_PROFILE` info in the janet(1)\nmanual page for hints).\n\nLike the `doc` macro, `pdoc` can also be invoked with a string (or no\nargument) to produce a set of search results.  The results are grouped\naccording to whether they are primitive, combining, or capture\npatterns.\n\n## Credits\n\nPortions of tests and the documentation come from Janet and the\njanet-lang.org website.\n\nThus the following license applies to at least those portions.\n\n```\nCopyright (c) 2019, 2020, 2021, 2022, 2023, 2024 Calvin Rose and contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsogaiu%2Fjanet-pegdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsogaiu%2Fjanet-pegdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsogaiu%2Fjanet-pegdoc/lists"}