{"id":22273102,"url":"https://github.com/mac-/opter","last_synced_at":"2025-07-28T14:31:49.811Z","repository":{"id":6863234,"uuid":"8112124","full_name":"mac-/opter","owner":"mac-","description":null,"archived":false,"fork":false,"pushed_at":"2015-01-02T20:50:06.000Z","size":255,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-08T06:25:44.144Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mac-.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-09T17:10:47.000Z","updated_at":"2022-12-05T01:50:49.000Z","dependencies_parsed_at":"2022-09-18T10:42:59.320Z","dependency_job_id":null,"html_url":"https://github.com/mac-/opter","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac-%2Fopter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac-%2Fopter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac-%2Fopter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac-%2Fopter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mac-","download_url":"https://codeload.github.com/mac-/opter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227922961,"owners_count":17840940,"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":[],"created_at":"2024-12-03T13:09:47.013Z","updated_at":"2024-12-03T13:09:47.782Z","avatar_url":"https://github.com/mac-.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opter\n\nOpter provides an easy way to specify options for your application. It uses [commander](https://github.com/visionmedia/commander.js) to parse command line arguments and display option help information. In addition to reading from command line options, it can also read values from environment variables and a json/yaml file (opter.json) that lives in the same directory as the file being run by NodeJS. If no values were found in the command line arguments, environment variables, or the JSON/YAML config file, then it will assign the default value (if provided). The priority is:\n\n1. command line args\n2. environment variables\n3. JSON/YAML config file\n4. default value\n\n[![Build Status](https://secure.travis-ci.org/mac-/opter.png)](http://travis-ci.org/mac-/opter)\n[![Coverage Status](https://coveralls.io/repos/mac-/opter/badge.png)](https://coveralls.io/r/mac-/opter)\n[![Code Climate](https://codeclimate.com/github/mac-/opter.png)](https://codeclimate.com/github/mac-/opter)\n[![NPM version](https://badge.fury.io/js/opter.png)](http://badge.fury.io/js/opter)\n[![Dependency Status](https://david-dm.org/mac-/opter.png)](https://david-dm.org/mac-/opter)\n\n[![NPM](https://nodei.co/npm/opter.png?downloads=true\u0026stars=true)](https://nodei.co/npm/opter/)\n\n## Contributing\n\nThis module makes use of a `Makefile` for building/testing purposes. After obtaining a copy of the repo, run the following commands to make sure everything is in working condition before you start your work:\n\n\tmake install\n\tmake test\n\nBefore committing a change to your fork/branch, run the following commands to make sure nothing is broken:\n\n\tmake test\n\tmake test-cov\n\nDon't forget to bump the version in the `package.json` using the [semver](http://semver.org/spec/v2.0.0.html) spec as a guide for which part to bump. Submit a pull request when your work is complete.\n\n***Notes:***\n* Please do your best to ensure the code coverage does not drop. If new unit tests are required to maintain the same level of coverage, please include those in your pull request.\n* Please follow the same coding/formatting practices that have been established in the module.\n\n## Installation\n\n\tnpm install opter\n\n## Usage\n\nThe opter function takes three parameters:\n\n* An object containing the options to configure\n* The version of your app (easily retrieved by running ```require('./package.json').version```)\n* [optional] A location to a file that contains the config to read. Note: Command line options and env vars trump any values in this file. If not specified, it defaults to a file called `opter.json`. All relative paths are assumed to be relative the file being executed by Node.\n\nThe object containing the options should be formatted like so:\n\n\t{\n\t\tmyOption: {\t\t\t\t\t// correlates to command line option \"--my-option\" and environment variable \"myOption\" and environment variable \"MYOPTION\" and opter.json property \"myOption\"\n\t\t\tcharacter: 'm',\t\t\t// optional, used as the short option for the command line. If not provided opter will try to pick one for you based on your option name.\n\t\t\targument: 'string',\t\t// optional, describes what the value should be. If not provided, it defaults to the \"type\" within the schema if set, otherwise to \"string\". If the schema type is \"boolean\", no argument is required.\n\t\t\tdefaultValue: 'fnord',\t// optional, the value to set the option to if it wasn't specified in the args or env vars\n\t\t\trequired: true, \t\t// optional, if set to true and no value is found, opter will throw an error. defaults to false.\n\t\t\tschema: {\t\t\t\t// optional, a JSONSchema definition to validate the value against. If the \"type\" property is used, opter will also try to convert the value to that type before validating it.\n\t\t\t\ttype: 'string',\t\t// optional, the type that the value should conform to\n\t\t\t\tdescription: ''\t\t// optional, describes the option and is used when generating the command line help\n\t\t\t}\t\t\t\t\n\t\t}\n\t}\n\nNote: If `argument` is missing or falsey and `type` is not `Boolean`, an error will be thrown.\n\nThe function returns an object containing the keys that were specified in the options that were passed along with the values that opter found from the args, env vars, or default values. For example, calling the opter function with the above sample options object, the result might look like:\n\n\t{\n\t\tmyOption: 'fnord'\n\t}\n\nHere is an example on how to use opter:\n\n\t// app.js\n\tvar opter = require('opter'),\n\t\tappVersion = require('./package.json').version,\n\t\topts = {\n\t\t\tmyOption: {}\n\t\t},\n\t\toptions = opter(opts, appVersion);\n\nWith the example above, here are some sample ways to invoke the app:\n\n\t$ node app.js -m test\n\t$ node app.js --my-option test\n\t$ export myOption=test \u0026\u0026 node app.js\n\t$ node app.js -h\n\t$ node app.js -V\n\nWhen an app using opter is run with the \"-h\" option, something similar will be displayed in the console:\n\n```\n$ node app.js -h\n\n  Usage: app.js [options]\n\n  Options:\n\n    -h, --help                          output usage information\n    -V, --version                       output the version number\n    -m, --my-option \u003cvalue\u003e             (Optional) Enables some cool funcitonality. Defaults to: true\n```\n\nHere is an example opter.json file:\n\n\t{\n\t\t\"myOption\": \"fnord\"\n\t}\n\n### Nested Options\n\nYou can also specify option names with dots (.) to denote a nested property within your `opter.json` file. However, when using dots in the name, the environment variable will have the dots replaced with underscores (_). Here is an example:\n\n\nOpter options:\n\n```\n{\n\t'statsd.host': {\n\t\tcharacter: 's',\n\t\targument: 'host',\n\t\tdefaultValue: 'localhost:8125'\n\t},\n\t'statsd.prefix': {\n\t\tchatacter: 'S',\n\t\targument: 'string'\n\t}\n};\n\n```\n\nCorresponding commandline arguments:\n\n```\n... --statsd.host=localhost:8125 --statsd.prefix=myApp\n```\n\nCorresponding environment variables:\n\n```\nstatsd_host=localhost:8125\nstatsd_prefix=myApp\n```\n\nCorresponding opter.json:\n\n```\n{\n\tstatsd: {\n\t\thost: 'localhost:8125',\n\t\tprefix: 'myApp'\n\t}\n}\n```\n\nThe object returned by the opter function:\n\n```\n{\n\tstatsd: {\n\t\thost: 'localhost:8125',\n\t\tprefix: 'myApp'\n\t}\n}\n```\n\nAs you can see, the object returned by opter will look identical to what you put in the `opter.json` file, as long as ll the properties in the opter.json file match the configuration options passed to the opter method.\n\n## License\n\nThe MIT License (MIT) Copyright (c) 2013 Mac Angell\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac-%2Fopter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmac-%2Fopter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac-%2Fopter/lists"}