{"id":13570426,"url":"https://github.com/sogaiu/janet-please","last_synced_at":"2026-01-25T02:33:21.815Z","repository":{"id":187493733,"uuid":"677016340","full_name":"sogaiu/janet-please","owner":"sogaiu","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-27T03:07:38.000Z","size":119,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-27T04:41:37.646Z","etag":null,"topics":["cli","janet","subcommands"],"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-08-10T14:39:25.000Z","updated_at":"2025-06-27T03:07:41.000Z","dependencies_parsed_at":"2023-08-10T20:02:55.598Z","dependency_job_id":"3a773fbf-da08-4f64-b543-379cbe45035a","html_url":"https://github.com/sogaiu/janet-please","commit_stats":null,"previous_names":["sogaiu/janet-functions-as-subcommands","sogaiu/janet-fns-as-subcmds"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sogaiu/janet-please","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-please","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-please/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-please/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-please/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sogaiu","download_url":"https://codeload.github.com/sogaiu/janet-please/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sogaiu%2Fjanet-please/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28742511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T01:40:51.112Z","status":"online","status_checked_at":"2026-01-25T02:00:06.841Z","response_time":113,"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":["cli","janet","subcommands"],"created_at":"2024-08-01T14:00:52.343Z","updated_at":"2026-01-25T02:33:21.800Z","avatar_url":"https://github.com/sogaiu.png","language":"Janet","funding_links":[],"categories":["Janet"],"sub_categories":[],"readme":"# janet-please (jplz)\n\nEasily package up bits of functionality written in Janet to\nbe invokable at the command line in the form of subcommands for reuse,\nsharing, and discussion.\n\nBy expressing specific functionality as a subcommand of an existing\nalready installed utility (`jplz`), we can:\n\n* Skip some typical \"deployment\" / \"installation\" steps -- no need to\n  place anything additional on `PATH` as adding a new subcommand only\n  requires either:\n\n    * editing a file (`subcommands.janet`) -OR-\n    * creating a suitable directory and appropriately populating it\n      with a single file\n\n* Put off having to think of a name that doesn't conflict with other\n  command line program names.  The only names that need to be avoided\n  are the built-in subcommand names and others you may have already\n  chosen for subcommands.\n\n## Status\n\nUsed daily, but still working things out -- including these docs :)\n\n## Setup\n\n### Unixy\n\nClone this repository.  Suppose cloned source is typically stored\nunder `~/src`, then:\n\n```\ncd ~/src\ngit clone https://github.com/sogaiu/janet-please\n```\n\nArrange for some place to house user-defined subcommands.  One way is\nto symlink to the provided `user-defined-samples` subdirectory:\n\n```\ncd $HOME\nln -s ~/src/janet-please/user-defined-samples .jplz\n```\n\nAnother way is to create the `~/.jplz` subdirectory:\n\n```\ncd $HOME\nmkdir .jplz\n```\n\nand create a suitable top-level `subcommands.janet` file (see the one\nin `user-defined-samples` for an example).\n\n### Windows\n\nClone this repository.  Suppose cloned source is typically stored\nunder `C:\\Users\\user\\src`, then:\n\n```\ncd C:\\Users\\user\\src\ngit clone https://github.com/sogaiu/janet-please\n```\n\nArrange for some place to house user-defined subcommands.  One way is\nto copy the provided `user-defined-samples` subdirectory:\n\n```\ncd %USERPROFILE%\nxcopy /E /I C:\\Users\\user\\src\\janet-please\\user-defined-samples .jplz\n```\n\nAnother way is to create the `.jplz` subdirectory in an appropriate\nlocation:\n\n```\ncd %USERPROFILE%\nmkdir .jplz\n```\n\nand create a suitable top-level `subcommands.janet` file (see the one\nin `user-defined-samples` for an example).\n\n## Adding a Subcommand\n\n### Method 1: Editing `subcommands.janet`\n\nThe top-level `subcommands.janet` file needs to have an appropriate\ndefinition for `subcommands` like:\n\n```janet\n(def subcommands\n  [\"my/sample\" sample-config\n   \"chomp-slow\" chomp-slow-config])\n```\n\nThis defines a tuple of an even number of elements where the odd\nindex items are names (e.g. `\"my/sample\"` or `\"chomp-slow\"`) and\nthe even index items resolve to structs like:\n\n```janet\n{:help \"Simple sample subcommand.\"\n :rules []\n :fn (fn [_meta _args] (print \"hi\"))}\n```\n\nThat is, there are three keys `:help`, `:rules`, and `:fn`, each with\na corresponding value:\n\n* `:help` should be associated with a string that is a short\n  description\n* `:rules` should be associated with a tuple describing parameters\n* `:fn` should be associated with a function of two arguments\n\nSee the `user-defined-samples` directory for some examples.\n\nAdding a subcommand is a matter of appropriately adding two items to\n`subcommands` (i.e. a string and a struct (or something that resolves\nto a struct)).\n\n### Method 2: Creating and Populating a Subdirectory\n\nAny directories that live at the same level as the top-level\n`subcommands.janet` file will be searched for a `subcommand.janet`\n(singular) file.\n\n`subcommand.janet` should contain at least one definition like:\n\n```janet\n(def config\n  {:help \"Simple sample subcommand.\"\n   :rules []\n   :fn (fn [_meta _args] (print \"hi\"))})\n```\n\nThat is, `config` should be defined as an appropriate struct (see\n`Method 1` above for some details and hints).\n\nAdding a subcommand is a matter of creating a directory next to the\ntop-level `subcommands.janet` file and populating it with an\nappropriate `subcommand.janet` (singular) file.\n\n## Completion\n\nThere are some built-in subcommands to output completion-related code\nfor various \"shells\":\n\n### `bash`\n\n```\njplz bash-completion\n```\n\n### `zsh`\n\n```\njplz zsh-completion\n```\n\n### [`clink`](https://github.com/chrisant996/clink/) (\"injected\" `cmd.exe` on Windows)\n\n```\njplz clink-completion\n```\n\nEach \"shell\" has one or more ways of making the completion\nfunctionality active.  For example, in `bash`'s case, one way to get\nthings working is to place a file named `jplz` under\n`~/.local/share/bash-completion/completions/` and populate it with the\noutput from `jplz bash-completion`.\n\n## Related\n\n* [`groan`](https://github.com/keithy/groan)\n* [`jeep`](https://github.com/pyrmont/jeep)\n* [`sd`](https://github.com/ianthehenry/sd)\n* [`sub`](https://github.com/qrush/sub)\n* [`tome`](https://github.com/toumorokoshi/tome)\n\n## Credits\n\n* pyrmont - `jplz` was inspired through use and discussion of\n  [`jeep`](https://github.com/pyrmont/jeep) and\n  [`argy-bargy`](https://github.com/pyrmont/argy-bargy)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsogaiu%2Fjanet-please","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsogaiu%2Fjanet-please","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsogaiu%2Fjanet-please/lists"}