{"id":15017334,"url":"https://github.com/perlpunk/app-spec-p5","last_synced_at":"2025-04-09T19:42:25.470Z","repository":{"id":56837673,"uuid":"46528023","full_name":"perlpunk/App-Spec-p5","owner":"perlpunk","description":"Writing command line apps made easy","archived":false,"fork":false,"pushed_at":"2023-05-28T10:35:40.000Z","size":391,"stargazers_count":23,"open_issues_count":16,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T21:45:35.124Z","etag":null,"topics":["bash","cli-framework","command-line","completion","getopt","perl5","pod","specification","subcommands","zsh"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perlpunk.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":"CONTRIBUTING.md","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":"2015-11-20T00:04:47.000Z","updated_at":"2023-10-18T17:24:07.000Z","dependencies_parsed_at":"2024-06-18T14:15:10.883Z","dependency_job_id":null,"html_url":"https://github.com/perlpunk/App-Spec-p5","commit_stats":{"total_commits":248,"total_committers":4,"mean_commits":62.0,"dds":"0.020161290322580627","last_synced_commit":"654a702a5c6b676294c992035252395684c6d4dc"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlpunk%2FApp-Spec-p5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlpunk%2FApp-Spec-p5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlpunk%2FApp-Spec-p5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlpunk%2FApp-Spec-p5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perlpunk","download_url":"https://codeload.github.com/perlpunk/App-Spec-p5/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248101082,"owners_count":21047898,"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":["bash","cli-framework","command-line","completion","getopt","perl5","pod","specification","subcommands","zsh"],"created_at":"2024-09-24T19:50:19.185Z","updated_at":"2025-04-09T19:42:25.446Z","avatar_url":"https://github.com/perlpunk.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# App::Spec\nWriting command line apps made easy\n\n## Status\n\nThe structure of the spec will probably change.\n\nI wait for your suggestions, wishes, bug reports.\n\n## Purpose\n\nWrite a specification for your command line application (currently in YAML) and get:\n* Subcommands (nested), options, parameters\n* a Perl 5 (and possibly other) framework that\n * automatically calls the specified method for the subcommand\n * validates options and parameters\n * outputs help\n* Automatic creation of pod, man pages\n* Automatic creation of zsh and bash completion scripts. Completion includes:\n * Subcommands, parameter values, option names and option values.\n * Description for completion items are shown, in zsh builtin, in bash with a cute little trick.\n * Generating dynamic completion. When completing a parameter or option, you can call an external\n command returning possible completion values\n* Possibly even creating a specification for your favourite app which lacks shell completion\n\nWriting the specification in YAML takes advantage of YAML aliases, for example when you have\noptions or parameters which are not global, but are used in more than one place. Alternatively the\nspec could allow to create definitions which you can just link to, kind of like Swagger does it.\n\n## Documentation\n\nFor now just an example in the examples directory called \"myapp\".\nJust play with it and use your tab key!\nAlso try zsh if you haven't yet.\n\n### For authors\n\nThere is a command line tool called appspec \u003chttps://github.com/perlpunk/App-AppSpec-p5\u003e\nwhich is useful for you as an author of an app. You can use it to\ncreate completion and pod from a spec file.\n\n### Example\n\nFor a first overview, here is how an app looks like:\n\n```perl\nuse strict;\nuse warnings;\nuse 5.010;\n# your app class\n# you could even go without an extra class and simply use the \"main\" namespace\npackage App::Spec::Example::MyApp;\nuse base 'App::Spec::Run';\n\n# the method for the subcommand frobnicate\nsub frobnicate {\n    my ($self) = @_;\n    my $options = $self-\u003eoptions; # just a hashref\n    my $parameters = $self-\u003eparameters; # just a hashref\n    say \"frobnicate\";\n}\n\npackage main;\nuse App::Spec;\n\n# read YAML from __DATA__ section\nmy $spec = App::Spec-\u003eread(\"myapp-spec.yaml\");\nmy $run = App::Spec::Example::MyApp-\u003enew({ spec =\u003e $spec });\n# this will check input and call frobnicate\n$run-\u003erun;\n```\n\nSee https://github.com/perlpunk/App-Spec-p5/blob/master/examples/myapp-spec.yaml\nfor the specification of the example app. It's supposed to cover all currently\nimplemented features.\n\n## Getting the completion to work\n\nHere is how you get the completion for the example app.\n\nFirst, add the bin directory to your path:\n\n `% PATH=$PWD/examples/bin:$PATH`\n\nLocate the modules:\n\n` % export PERL5LIB=$PWD/lib:$PERL5LIB`\n\n### Bash\n\nSimply source the bash completion script:\n```\n $ source examples/bash/myapp.bash\n $ myapp \u003cTAB\u003e\n```\n\n### Zsh\n\nWhen using a new script/completion, you have to do two things:\n\nAdd the path to the completion dir to your .zshrc before the compinit call:\n\n `fpath=('/path/to/App-Spec-p5/examples/zsh' $fpath)`\n\nThen:\n\n `% exec zsh`\n \nIf you change the completion script later, you just need to source it:\n\n `% source examples/zsh/_myapp`\n \n Note that the completion script must also be executable!\n\n## Reinventing the wheel?\n\nYes, I know MooseX::App::Cmd, MooseX::App::Command, MouseX::App::Cmd, MooX::Cmd. I've written https://github.com/perlpunk/MooseX-App-Plugin-ZshCompletion.\n\nBut all are a little bit different and lack things.\n\nMy use case which got me into this required automatic creation of the spec, and I would have been\nforced to dynamically generate a whole bunch of Mo*X classes when I actually just needed one.\n\nI also like the idea of having a language independent specification.\n\nI'm lazy and I didn't want to write a completion for all the other app frameworks and getopt modules.\nI just want to do it once. \n\n## TODO\n\nSee https://github.com/perlpunk/App-Spec-p5/issues\n\n* Write a schema\n* Write tests\n* Complete the help output\n* Generate pod, man pages\n* Allow Getopt::Long, Getopt::Long::Descriptive, ... input as a specification\n* Allow caching of dynamic completion values that take long to compute\n* Options/parameters imply other options\n* Options with multiple values\n* Allow apps without subcommands\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperlpunk%2Fapp-spec-p5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperlpunk%2Fapp-spec-p5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperlpunk%2Fapp-spec-p5/lists"}