{"id":16383855,"url":"https://github.com/jakesidsmith/jargs","last_synced_at":"2025-03-21T02:31:00.364Z","repository":{"id":16603037,"uuid":"78644222","full_name":"JakeSidSmith/jargs","owner":"JakeSidSmith","description":"Simple node arg parser with explicit tree structure schema","archived":false,"fork":false,"pushed_at":"2023-09-02T13:22:46.000Z","size":502,"stargazers_count":3,"open_issues_count":19,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-12T04:09:57.797Z","etag":null,"topics":["argparse","argument-parser","arguments","argv","explicit","node","nodejs","schema","tree","tree-structure"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/jargs","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/JakeSidSmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2017-01-11T13:59:49.000Z","updated_at":"2022-01-29T16:38:51.000Z","dependencies_parsed_at":"2024-06-21T14:23:39.876Z","dependency_job_id":"8bb7df56-49ce-429d-8097-f9fc0fa18645","html_url":"https://github.com/JakeSidSmith/jargs","commit_stats":{"total_commits":368,"total_committers":1,"mean_commits":368.0,"dds":0.0,"last_synced_commit":"0be749846702411a71ba505419d024b34d6a93b5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeSidSmith%2Fjargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeSidSmith%2Fjargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeSidSmith%2Fjargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeSidSmith%2Fjargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JakeSidSmith","download_url":"https://codeload.github.com/JakeSidSmith/jargs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221811387,"owners_count":16884305,"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":["argparse","argument-parser","arguments","argv","explicit","node","nodejs","schema","tree","tree-structure"],"created_at":"2024-10-11T04:09:50.888Z","updated_at":"2024-10-28T09:07:15.301Z","avatar_url":"https://github.com/JakeSidSmith.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jargs\n\n**Simple node arg parser with explicit tree structure schema**\n\n[![CircleCI](https://circleci.com/gh/JakeSidSmith/jargs/tree/master.svg?style=svg)](https://circleci.com/gh/JakeSidSmith/jargs/tree/master)\n\n## About\n\nJargs is a node argv parser that takes inspiration from [docopt](http://docopt.org/).\nUnlike other arg parsers, jargs allows you to define your commands, arguments, etc in a tree structure.\nThis way you can have, for example, nested sub-commands, or arguments that are attached to a specific command.\n\n## Installation\n\n```shell\nnpm install jargs --save\n```\n\n## Usage\n\n### Require jargs\n\n```javascript\nimport {\n  collect,\n  Program,\n  Command,\n  KWArg,\n  Flag,\n  Arg,\n  Required,\n  RequireAll,\n  RequireAny\n} from 'jargs';\n```\n\n### Create a schema\n\nHere's a cutdown example of how to create a schema for NPM.\n\nNote: you can nest nodes as many times as necessary.\n\n```javascript\nconst tree = collect(\n  Help(\n    'help',\n    null,\n    Program(\n      'npm',\n      null,\n      RequireAny(\n        Command(\n          'init'\n        ),\n        Command(\n          'install', {alias: 'i'},\n          Arg(\n            'lib'\n          ),\n          Flag(\n            'save', {alias: 'S'}\n          ),\n          Flag(\n            'save-dev', {alias: 'D'}\n          ),\n          Flag(\n            'save-exact', {alias: 'E'}\n          ),\n          Flag(\n            'save-optional', {alias: 'O'}\n          )\n        ),\n        Command(\n          'run', {alias: 'run-scripts'},\n          Arg(\n            'command'\n          )\n        )\n      )\n    )\n  ),\n  process.argv\n);\n```\n\nThis collects the arguments that match the schema you've defined.\n\nCalling the command `npm` returns the following.\n\n```javascript\n{\n  name: 'npm',\n  kwargs: {},\n  flags: {},\n  args: {}\n}\n```\n\nCalling the command `npm install jargs --save` returns the following.\n\n```javascript\n{\n  name: 'npm',\n  command: {\n    name: 'install',\n    kwargs: {},\n    flags: {\n      save: true\n    },\n    args: {\n      lib: 'jargs'\n    }\n  },\n  kwargs: {},\n  flags: {},\n  args: {}\n}\n```\n\nIf we set the `lib` `Arg` to `multi: true`, then we can supply multiple args and they will be added to an array.\n\n```javascript\nArg(\n  'lib',\n  {\n    multi: true\n  }\n)\n```\n\nCalling the command `npm install jargs another-lib --save` with `mutli` returns the following.\n\n```javascript\n{\n  name: 'npm',\n  command: {\n    name: 'install',\n    kwargs: {},\n    flags: {\n      save: true\n    },\n    args: {\n      lib: ['jargs', 'another-lib']\n    }\n  },\n  kwargs: {},\n  flags: {},\n  args: {}\n}\n```\n\n### Collecting arguments\n\nThe `collect` function is provided with your program and `argv` (from process). Collect returns a tree that represents the matched arguments, and handles calling the callbacks of any commands that were matched with the relevant part of the tree.\n\n```javascript\ncollect(Program('my-command'), process.argv);\n```\n\n### Querying the tree\n\nEach node always contains the keys `command`, `kwargs`, `flags`, `args` and `rest` so that you can easily query them.\n\n#### Querying Commands\n\n```javascript\nif (tree.command) {\n  switch (tree.command.name) {\n    case 'install':\n      // Install stuff\n      break;\n    default:\n      // This should never be hit since we check for the command existence first\n  }\n}\n```\n\n#### Rest\n\nRest is a key that is populated with all remaining arguments when the user provides `--` in their command. This is often used to pass all remaining arguments to a sub-process.\n\nRunning `npm test -- --coverage` would return something like\n\n```javascript\n{\n  name: 'npm',\n  command: {\n    {\n      name: 'test',\n      kwargs: {},\n      flags: {},\n      args: {},\n      rest: ['--coverage']\n    }\n  },\n  kwargs: {},\n  flags: {},\n  args: {}\n}\n```\n\n#### Querying Flags, KWArgs, and Args\n\n##### Flags\n\n```javascript\nif (tree.flags.verbose) {\n  doSomethingWithThisFlag(tree.flags.verbose);\n}\n```\n\n##### KWArgs\n\n```javascript\nif ('lib' in tree.kwargs) {\n  doSomethingWithThisKWArg(tree.kwargs.lib);\n}\n```\n\n##### Args\n\n```javascript\nif ('lib' in tree.args) {\n  doSomethingWithThisArg(tree.args.lib);\n}\n```\n\n### Nodes\n\nAll nodes (excluding require nodes, see blow for more info) take the following arguments, though `Command` and `Program` take additional arguments (more info about individual nodes below).\n\n```javascript\nNode(name, options);\n```\n\nNote: the available options vary per node.\n\n`Command` and `Program` can take an infinite number or arguments. Any arguments after `name` \u0026 `options` become that node's child nodes e.g.\n\n```javascript\nCommand(name, options, KWArg(), Flag(), Arg());\n```\n\nBoth `options` and `childNodes` are optional.\nAll keys in `options` are optional and have defaults (more info below).\n`childNodes` are any arguments following the name \u0026 options (only valid for `Command` and `Program`).\n\nYou can nest `Commands` as many times as necessary.\n\n#### Program\n\nProgram is the main command / name of your program. This should always be the root node in your schema.\n\nTakes the following options.\n\n```javascript\nProgram(\n  'program-name'\n  {\n    description: 'A command', // default: empty string\n    usage: 'program-name sub-command --flag', // default: empty string\n    examples: ['program command-name --flag'], // default: empty array\n    callback: function (tree) {}\n  },\n  ...childNodes\n)\n```\n\n#### Command\n\nA sub-command of your command line interface.\nProgram is the main command / name of your program.\nCommands form a fork in the tree - only one command at each level can be satisfied.\n\nTakes the following options.\n\n```javascript\nCommand(\n  'command-name'\n  {\n    alias: 'command-alias', // default: undefined\n    description: 'A command', // default: empty string\n    usage: 'program-name sub-command --flag', // default: empty string\n    examples: ['program command-name --flag'], // default: empty array\n    callback: function (tree) {}\n  },\n  ...childNodes\n)\n```\n\n#### KWArg\n\nA key word argument such as `--outfile` that takes a custom value.\nThese can be defined in 2 different ways: `--outfile filename.js` and `--outfile=filename.js`.\nYou don't need to add the `--` to the name, these are dealt with internally.\nIf an alias is defined e.g. `{alias: 'o'}` this KWArg will also get the value of `-o=filename.js` (note the single `-`).\n\nTakes the following options.\n\n```javascript\nKWArg(\n  'kwarg-name'\n  {\n    alias: 'k', // default: undefined\n    description: 'A key word argument', // default: empty string\n    type: 'string',\n    multi: false // default: false\n  }\n)\n```\n\n#### Flag\n\nLike a KWArg, but do not take a custom value. These are used like booleans.\n`--verbose` is an example of a flag.\nYou don't need to add the `--` to the name, these are dealt with internally.\nIf an alias is defined e.g. `{alias: 'v'}` this Flag will also be true if `-v` is present (note the single `-`).\n\nTakes the following options.\n\n```javascript\nFlag(\n  'flag-name'\n  {\n    alias: 'f', // default: undefined\n    description: 'A flag', // default: empty string\n  }\n)\n```\n\n#### Arg\n\nPositional argument that takes a custom value.\nIn the command `npm install jargs`, `jargs` is an Arg.\n\nTakes the following options.\n\n```javascript\nArg(\n  'arg-name'\n  {\n    description: 'An arg', // default: empty string\n    type: 'string',\n    multi: false // default: false\n  }\n)\n```\n\n### Help\n\nBy wrapping your Program node in the Help node users can get nicely formatted help \u0026 usage output about any part of your schema by passing the `--help` flag (you can change the help node name \u0026 alias).\n\nNote: if you provide another flag / kwarg node with the same name or alias as the help node, no help will be output.\nThis allows you to override the help output, and output some custom usage info.\n\n```javascript\nHelp(\n  'help',\n  {\n    alias: 'h', // default: undefined\n    description: 'Display help \u0026 usage' // default: empty string\n  }\n)\n```\n\n### Require Nodes\n\nThere are 3 different types of require nodes that you can wrap your argument / command nodes in to ensure that they are supplied.\n\nNote: you cannot require more than one Command at the same level unless you use RequireAny, as Commands form a fork in the tree and only one at each level can be satisfied.\n\n#### Required\n\nTakes a single node as an argument and ensures it is supplied.\n\n```javascript\nRequired(\n  Arg('arg-name')\n)\n```\n\n#### RequireAll\n\nTakes any number of nodes as arguments and ensures they are all supplied.\n\n```javascript\nRequireAll(\n  KWArg('kwarg-name'),\n  Arg('arg-name')\n)\n```\n\n#### RequireAny\n\nTakes any number of nodes as arguments, and ensures that one of them is supplied.\n\n```javascript\nRequireAny(\n  Command('command1'),\n  Command('command2')\n)\n```\n\n### Callbacks\n\nThe Program and Command nodes can take a callback. If satisfied, these callbacks will be called with the `tree` at that level, the `parentTree`, and anything returned from the previous callback.\n\n```shell\nprogram --kwarg=value command\n```\n\n```javascript\nProgram(\n  'program',\n  {\n    callback: function (tree) {\n      /*\n\n      tree = {\n        name: 'program',\n        command: {name: 'command', ...etc},\n        args: {},\n        flags: {},\n        kwargs: {\n          kwarg: 'value'\n        }\n      };\n\n      */\n\n      return 'Hello, World!';\n    }\n  },\n  KWArg(\n    'kwarg'\n  ),\n  Command(\n    'command',\n    {\n      callback: function (tree, parentTree, data) {\n        /*\n\n      tree = {\n        name: 'command',\n        args: {},\n        flags: {},\n        kwargs: {}\n      };\n\n      parentTree = {\n        name: 'program',\n        command: {name: 'command', ...etc},\n        args: {},\n        flags: {},\n        kwargs: {\n          kwarg: 'value'\n        }\n      };\n\n      data = 'Hello, World!';\n\n      */\n      }\n    }\n  )\n)\n```\n\n## Command examples\n\n```shell\nnpm install jargs --save\n```\n\nIn the above command `install` is a `Command`, `jargs` is an `Arg`, and `--save` is a `Flag`.\n\n```shell\nbrowserify --transform babelify --outfile=build/indexjs src/index.js\n```\n\nIn the above command `--transform` is a `KWArg` and its value is `babelify`,\n`--outfile` is also a `KWArg` (note the alternative kwarg syntax) with the value `build/index.js`,\nand `src/index.js` is an `Arg`\n\n## Complex schema examples\n\nThis example shows how to create the following commands (taken from [docopt](http://docopt.org/)).\n\n### Commands\n\n```shell\nnaval_fate ship new \u003cname\u003e...\nnaval_fate ship \u003cname\u003e move \u003cx\u003e \u003cy\u003e [--speed=\u003ckn\u003e]\nnaval_fate ship shoot \u003cx\u003e \u003cy\u003e\n```\n\n### Schema\n\n```javascript\nconst tree = collect(\n  Program(\n    'naval_fate',\n    null,\n    Command(\n      'ship', null,\n      RequireAny(\n        Arg(\n          'shipName'\n        ),\n        Command(\n          'new', null,\n          Required(\n            Arg(\n              'shipName'\n            )\n          )\n        ),\n        Command(\n          'shoot', null,\n          RequireAll(\n            Arg(\n              'shootX'\n            ),\n            Arg(\n              'shootY'\n            )\n          )\n        )\n      ),\n      Command(\n        'move', null,\n        RequireAll(\n          Arg(\n            'moveX'\n          ),\n          Arg(\n            'moveY'\n          )\n        ),\n        KWArg(\n          'speed'\n        )\n      )\n    )\n  ),\n  process.argv\n);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakesidsmith%2Fjargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakesidsmith%2Fjargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakesidsmith%2Fjargs/lists"}