{"_id":"protogram","_rev":"12-fc3ca28b8024c74fe19bf28a25f779a7","name":"protogram","description":"Handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc.","dist-tags":{"latest":"1.1.3"},"versions":{"1.1.0":{"name":"protogram","version":"1.1.0","description":"Handle command line flags and sub arguments without all the fat","main":"main.js","scripts":{"test":"nodeunit test/test.js","example":"node ./example/example.js"},"repository":{"type":"git","url":"https://github.com/arjunmehta/node-protogram.git"},"keywords":["yargs","minimist","cli","commander","command-line","arguments","options"],"author":{"name":"Arjun Mehta"},"license":"MIT","bugs":{"url":"https://github.com/arjunmehta/node-protogram/issues"},"homepage":"https://github.com/arjunmehta/node-protogram","dependencies":{"subarg":"~1.0.0","unparse-args":"~1.0.1"},"devDependencies":{"nodeunit":"~0.8.8"},"gitHead":"35e36e153f04d94673c69c15b935ff07049c6bde","_id":"protogram@1.1.0","_shasum":"b983ef56f6cd8bef5a319da617ef3b393bd7dc2d","_from":".","_npmVersion":"2.1.14","_nodeVersion":"0.10.35","_npmUser":{"name":"arjunmehta","email":"arjunmeht@gmail.com"},"maintainers":[{"name":"arjunmehta","email":"arjunmeht@gmail.com"}],"dist":{"shasum":"b983ef56f6cd8bef5a319da617ef3b393bd7dc2d","tarball":"https://registry.npmjs.org/protogram/-/protogram-1.1.0.tgz","integrity":"sha512-Fj7zcBUA4Lf3Ekaa0HPljdObpBbLpjsUuJBCtzTbupSlNmaB3hOjwsHskZpsUm6RBEVguXgJDQKHiFCZp9/PVg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCID+EKrR+o6XtVsxr3MzTvZSqQAc8Kedm2Q81+OdS/jEFAiBYEccES4ntO2N5qpfKTT7ua7b+Cx02MxVpooftk4J85A=="}]}},"1.1.1":{"name":"protogram","version":"1.1.1","description":"Handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc... with just a wee bit of fat.","main":"main.js","scripts":{"test":"nodeunit test/test.js","example":"node ./example/example.js"},"repository":{"type":"git","url":"https://github.com/arjunmehta/node-protogram.git"},"keywords":["yargs","minimist","cli","commander","command-line","arguments","options"],"author":{"name":"Arjun Mehta"},"license":"MIT","bugs":{"url":"https://github.com/arjunmehta/node-protogram/issues"},"homepage":"https://github.com/arjunmehta/node-protogram","dependencies":{"subarg":"~1.0.0","unparse-args":"~1.0.1"},"devDependencies":{"nodeunit":"~0.8.8"},"gitHead":"5bdde0e232328ae21cdb3260bab0ad8d12f47b91","_id":"protogram@1.1.1","_shasum":"130e200a7a8f5daf26fdd511b013f9779c9c46d6","_from":".","_npmVersion":"2.1.14","_nodeVersion":"0.10.35","_npmUser":{"name":"arjunmehta","email":"arjunmeht@gmail.com"},"maintainers":[{"name":"arjunmehta","email":"arjunmeht@gmail.com"}],"dist":{"shasum":"130e200a7a8f5daf26fdd511b013f9779c9c46d6","tarball":"https://registry.npmjs.org/protogram/-/protogram-1.1.1.tgz","integrity":"sha512-K/pdaiODZHwhgwRmBp0Es1zYaaSvevbUTECEJ1Hn5Rxg/WjheHc+j4RANUcAODXxgbq3e+5q4dktIltVj6QiHA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCd56SdQqJ+NwsrpAZN1X0l+hdeudVanC7ug3MwwL7AoAIgB1S3cyvprvFWqdT70KHGvuV1+vvXMjBz/UtHAIkvHHg="}]}},"1.1.2":{"name":"protogram","version":"1.1.2","description":"Handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc.","main":"main.js","scripts":{"test":"nodeunit test/test.js","example":"node ./example/example.js"},"repository":{"type":"git","url":"https://github.com/arjunmehta/node-protogram.git"},"keywords":["yargs","minimist","cli","commander","command-line","arguments","options","program","command","subarguments","flags","commands"],"author":{"name":"Arjun Mehta"},"license":"MIT","bugs":{"url":"https://github.com/arjunmehta/node-protogram/issues"},"homepage":"https://github.com/arjunmehta/node-protogram","dependencies":{"subarg":"~1.0.0","unparse-args":"~1.0.1"},"devDependencies":{"nodeunit":"~0.8.8"},"gitHead":"0b4446fe7c223d5808550b76bc88b70cb16e8597","_id":"protogram@1.1.2","_shasum":"2113fcd08123378421e865b437c658cc0994ed62","_from":".","_npmVersion":"2.1.14","_nodeVersion":"0.10.35","_npmUser":{"name":"arjunmehta","email":"arjunmeht@gmail.com"},"maintainers":[{"name":"arjunmehta","email":"arjunmeht@gmail.com"}],"dist":{"shasum":"2113fcd08123378421e865b437c658cc0994ed62","tarball":"https://registry.npmjs.org/protogram/-/protogram-1.1.2.tgz","integrity":"sha512-DWYmR6S1UPW+Qf+2zjR2+OUNyYvd9qJ+2wx4pIel063/DTXuEsgl+dDzWbVvgpmp+h/CbWc2CwIDGd3FEY7S5w==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD5TR7g+6IKdWWV5f2u2cu3uQYiA8lKmDPJQBrXEReT7gIhAIWTxJv5dHLstx+rZNZyLoFrcsXnTMYExAu/aH/3VOMu"}]}},"1.1.3":{"name":"protogram","version":"1.1.3","description":"Handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc.","main":"main.js","scripts":{"test":"nodeunit test/test.js","example":"node ./example/example.js"},"repository":{"type":"git","url":"https://github.com/arjunmehta/node-protogram.git"},"keywords":["yargs","minimist","cli","commander","command-line","arguments","options","program","command","subarguments","flags","commands"],"author":{"name":"Arjun Mehta"},"license":"MIT","bugs":{"url":"https://github.com/arjunmehta/node-protogram/issues"},"homepage":"https://github.com/arjunmehta/node-protogram","dependencies":{"subarg":"~1.0.0","unparse-args":"~1.0.1"},"devDependencies":{"nodeunit":"~0.8.8"},"gitHead":"9769c735adb51b61dcb029bfdaf4b9bbe1c2d66a","_id":"protogram@1.1.3","_shasum":"95f1df709c43310d62c13942baa09b753a688cf1","_from":".","_npmVersion":"2.1.18","_nodeVersion":"0.10.35","_npmUser":{"name":"arjunmehta","email":"arjunmeht@gmail.com"},"maintainers":[{"name":"arjunmehta","email":"arjunmeht@gmail.com"}],"dist":{"shasum":"95f1df709c43310d62c13942baa09b753a688cf1","tarball":"https://registry.npmjs.org/protogram/-/protogram-1.1.3.tgz","integrity":"sha512-/fdMf1mjKR2CN29TZYg5+5lBdBxCDPExHypfRfbst+t33E/Y6tl/yvnvDyia3W/E/b34+jfWo5gZqFUzkcugAQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIAOy/bkovn0nEJj3sSSmCgodj2dxfRmQiCIM1aqMb3rcAiEAr9YVPxzOm3zOAFJF3U12jJyOy9rIZDMb4+wgX8dQkJY="}]}}},"readme":"# protogram\n\n[![Build Status](https://travis-ci.org/arjunmehta/node-protogram.svg?branch=master)](https://travis-ci.org/arjunmehta/node-protogram)\n\n![protogram title image](https://raw.githubusercontent.com/arjunmehta/node-protogram/image/image/protogram.png)\n\nA node.js module to **recursively create command-line programs and sub-programs**. Easily handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc... with just a *little bit* of fat. Some things this module provides:\n\n- **a minimal, yet easily scalable interface**\n- **flexible control over the handling of argument flags and sub-commands**\n- **ability to handle sub-contexts as arguments a la [subarg](https://github.com/substack/subarg)**.\n- **autogenerate help information via [protogram-help](https://github.com/arjunmehta/node-protogram-help)**\n\n## Installation\n```bash\nnpm install --save protogram\n```\n\n## Basic Usage\n\n### Include and Create your Program\n\n```javascript\nvar program = require('protogram').create();\n```\n\n### Add Option Flags\nAdd option flags to your program. Shortcuts will automatically be made based on the first available character of the specified option name.\n\n```javascript\nprogram\n    .option('--optionA')  // shortcut will be -o\n    .option('--optionB'); // shortcut will be -O\n```\n\n### Set an Action For When Your Program Runs\n\n```javascript\nprogram.action = function(args, flags){\n    if(flags.optionA) console.log(\"optionA set to:\", flags.optionA)\n    if(flags.optionB) console.log(\"optionB set to:\", flags.optionB)\n    console.log(\"passed in arguments:\", args)\n};\n```\n\n### Parse Your Arguments to Execute\n\nFinally, the most important step! Now that you've set everything up, you're ready to parse your program's arguments.\n\n```javascript\nprogram.parse(process.argv);\n```\n\n### Test It\n\n```bash\nnode example.js 198787 \"Arg 2\" --optionA [ A 29787 \"b C\" -A -B 29872 ] --optionB \"This Is A Long String\"\n```\n\nWill output:\n\n```\noptionA set to: { _: [ \"A\", 29787, \"b C\"], A: true, B: 29872 }\noptionB set to: \"This Is A Long String\"\npassed in arguments: [ 198787, \"Arg 2\" ]\n```\n\n\n## Advanced Usage\n\nThe above was just to get you started. The API is super flexible and you can control the flow of your program to near infinite specificity.\n\n### Advanced Option Specification\n\nTake more control over how flags are specified and handled by passing in options to your `option` setting. Aside from the first argument specifying the flag name, all of the flag settings below are of course optional.\n\n```javascript\nprogram.option('--optionA', {\n    shortcut: '-a',\n    description: 'Use a generic flag to do anything',\n    required: 'a value'\n    action: function(value){\n        // called if the flag is set and there are no errors\n        console.log(\"optionA was set to:\", value);\n    },\n    error: function(err, value){\n        // called if the 'required' value is not specified when executing\n        console.error(err.message);\n    }\n});\n```\n\n### Add Commands as Sub-Programs\nRecursively add git-style commands to your program, and build them as you would your main program.\n\n```javascript\nvar sub_program = program.command('run', {\n    description: 'execute a command',\n    required: 'path name',\n    action: function(args, flags){\n        // executed if there are no errors\n        console.log(\"path to execute:\", args[0]);\n        if(flags.now) // executing now\n    },\n    error: function(err, args){\n        // called if the required argument is missing\n        // or if any flags' required arguments are missing.\n        console.error(err.message);\n    }\n});\n\nsub_program.option('--now')\n```\n\n\n### Use a Wildcard for Configuring All Commands\n\n```javascript\nprogram.command('*', {\n    includeRoot: true // also apply all these settings to the root program\n}).option('--version', {\n    action: function(value){\n        console.log(\"My Program v4.0.0\")\n    }\n});\n```\n\n\n### Add Automated Help to Your Program\nWant to output usage instructions automatically for your program? Use the **protogram-help** module. Refer to the documentation for how to use.\n\n\n### Bubble Up Execution Paths\n\nBy default the execution of `action` methods of a program does not bubble up to the parent commands.\n\nFor example, let's say we create a program with a system of sub commands:\n\n```javascript\nvar program = protogram.create({\n    action: function(args, flags) {\n        console.log(\"main program activated\"); // will not be executed \n    }\n});\n\nvar sub_program = program.command('sub-command', {\n    action: function(args, flags) {\n        console.log(\"sub-command activated\"); // will not be executed \n    }\n});\n\nsub_program.command('sub-sub-command', {\n    action: function(args, flags) {\n        console.log(\"sub-sub-command activated\"); // will be executed\n    }\n});\n```\n\nAnd execute:\n\n```bash\nnode example.js sub-command sub-sub-command\n```\n\nOnly the `sub-sub-command` action method would be trigged. We can change this by setting the `bubbleUp` option on any parent command.\n\n```javascript\nvar program = protogram.create({\n    action: function(args, flags) {\n        console.log(\"main program activated\"); // will not be executed \n    }\n});\n\nvar sub_program = program.command('sub-command', {\n    bubbleUp: true,\n    action: function(args, flags) {\n        console.log(\"sub-command activated\"); // will be executed\n    }\n});\n\nsub_program.command('sub-sub-command', {\n    action: function(args, flags) {\n        console.log(\"sub-sub-command activated\");  // will be executed\n    }\n});\n```\n\nNow both the `sub-command` and the `sub-sub-command` actions will be executed.\n\n### Halt on Error\nBy default if there is an error (ie. a required argument is missing) for a parent command, the program will continue to parse and evaluate sub-commands and flags. Prevent this by setting the `haltOnError` option to `true` when you create your program.\n\n```javascript\nvar program = protogram.create({haltOnError: true});\n```\n\nor apply to specific sub-commands:\n\n```javascript\nvar sub_program = program.command('run', {\n    haltOnError: true,\n    required: 'path name',\n    action: function(args, flags){ },\n    error: function(err, args){ }\n})\n\nsub_program.command('at', {\n    required: 'a time',\n    action: function(args, flags){ },\n    error: function(err, args){ }\n});\n```\n\n```bash\nnode example.js run at \"13:34\"\n```\n\nNow in the above example, even though the sub-command `at` is specified, it will not execute because the required argument `path name` is missing for the `run` command. The error will be handled by the `run`'s `error` property.\n\n\n### Test Flags\nIf you'd prefer the good ol' fashioned way of testing your flags, instead of using handlers, just test their existence after you've parsed your arguments:\n\n```javascript\nif(program.flagged['generic']){\n    console.log('the --generic flag has been used!')\n}\n```\n\n\n## API\n\n### Protogram.create(options)\nReturns a new `Protogram` command object.\n\n- `options` **Object**:\n    - `description` **String**: Specify a description for the sub-command.\n    - `required` **String**: Describe a required value that **must be** be passed in by the user if this sub-command is used.\n    - `optional` **String**: Describe an optional value that can be passed in when this sub-command is used. If `required` is set, `optional` will be ignored.\n    - `action` **Function(args, program)**: A handler method called if the sub-command is set without any errors. Receives all `args` passed in.\n    - `error` **Function(error, value, program)**: A handler method called if the flag is set but has an error (ie. `required` was set and no value was passed in by the user).\n    - `haltOnError` **Boolean**: Set whether the program should stop parsing if there is an error.\n    - `bubbleUp` **Boolean**: Set whether the program's `action` method should be executed along with sub-commands.\n\n```javascript\nvar program = protogram.create({\n    action: function(args, flags) {\n        console.log(\"running your program\");\n    }\n});\n```\n\n### Protogram.command(command_name, options)\nReturns a new `Protogram` command object.\n\nAdd a sub-command to your program. The sub-command is a new instance of `Protogram`.\n\n- `command_name` **String**: Name of the sub-command to your program. Use the `*` command name to apply this setting to all sub-commands of the program.\n- `options` **Object**: Since the **Protogram.command** method returns a new Protogram object, you can set the same options as **Protogram.create()**.\n\n#### Minimal Example\n```javascript\nprogram.command('run', {\n    action: function(args, flags) {\n        console.log(\"executed the run command\");\n    }\n});\n```\n\n#### Example with a Required Argument\n\n```javascript\nprogram.command('run', {\n    required: 'file path',\n    action: function(args, flags) {\n        console.log(\"executed the run command successfully\");\n    },\n    error: function(err, args){\n        console.log(err.message); // missing required <file path>\n    }\n}); \n```\n\n#### The Special `*` Wildcard Command Setting\nSet the `command_name` to `'*'` to apply universal settings to all sub-commands on your program. You can use the `includeRoot` option.\n\n```javascript\nprogram.command('*', {\n    includeRoot: true // also apply all these settings to the root program\n    error: function(err, args){\n        console.log(\"A universal error message\");\n    }\n}).option('--version', {\n    action: function(value){\n        console.log(\"My Program v4.0.0\")\n    }\n});\n\nprogram.command('run');\n```\n\nThe `run` command, as well as the `main program` will inherit the settings from the `*` command configuration, as well as the flag options specified (ie. `version`).\n\n\n### Protogram.option(flag_name, options)\nAdd a `Flag` as an option to your program.\n\n- `flag_name` **String**: Name of the option of your program.\n- `options` Object:\n    - `shortcut` **String**: Specify a shortcut letter for the flag. Defaults to the first available letter of the `flag_name`.\n    - `description` **String**: Specify a description for the flag.\n    - `required` **String**: Describe a required value that **must be** be passed in when this flag is set.\n    - `optional` **String**: Describe an optional value that can be passed in when this flag is set. If `required` is set, `optional` will be ignored.\n    - `action` **Function(value, program)**: A handler method called if the flag is set without any errors.\n    - `error` **Function(error, value, program)**: A handler method called if the flag is set but has an error (ie. `required` was set and no value was passed in by the user).\n    - `added` **Function(program, flag)**: A method called when your option has been added to the program.\n\nreturns the parent `Protogram` command object.\n\n#### Minimal Example\nAdd an option (`--name`) to your program. Protogram will automatically create a shortcut (`-n`) to your program.\n```javascript\nprogram.option('--name');\n```\n\n#### The Works\n\n```javascript\nprogram.option('--name', {\n    shortcut: '-n',\n    description: 'Set the name of the user',\n    required: 'username',\n    action: function(err, value){\n        if(err) console.error('Required value needed when using the --name flag');\n        else console.log(\"Name set to:\", value);\n    }\n});\n```\n\n\n### Protogram.parse(argv)\nAfter your program is configured, pass in your full `process.argv` array into the **Protogram.parse()** method to begin parsing the command-line arguments.\n\n```javascript\nprogram.parse(process.argv);\n```\n\n### Protogram.flagged & Protogram.flagged[flag_name]\nAn object you can use to check to see whether the user has used a flag, and retrieve the passed in value. This will only work after the arguments have been parsed by `program.parse`.\n\n```javascript\nif(program.flagged['name']){\n    console.log('the --name flag has been set to', program.flagged['name'])\n}\n```\n\n\n## License\n\n```\nThe MIT License (MIT)\nCopyright (c) 2014 Arjun Mehta\n```","maintainers":[{"name":"arjunmehta","email":"arjunmeht@gmail.com"}],"time":{"modified":"2022-06-24T21:02:07.561Z","created":"2015-01-09T23:45:00.270Z","1.1.0":"2015-01-09T23:45:00.270Z","1.1.1":"2015-01-10T00:38:19.387Z","1.1.2":"2015-01-10T17:53:02.396Z","1.1.3":"2015-01-30T22:46:45.585Z"},"homepage":"https://github.com/arjunmehta/node-protogram","keywords":["yargs","minimist","cli","commander","command-line","arguments","options","program","command","subarguments","flags","commands"],"repository":{"type":"git","url":"https://github.com/arjunmehta/node-protogram.git"},"author":{"name":"Arjun Mehta"},"bugs":{"url":"https://github.com/arjunmehta/node-protogram/issues"},"license":"MIT","readmeFilename":"README.md","users":{"goliatone":true,"jasonwoodland":true}}