{"id":13878626,"url":"https://github.com/piotrmurach/tty-option","last_synced_at":"2025-06-12T13:09:25.720Z","repository":{"id":40716399,"uuid":"248992999","full_name":"piotrmurach/tty-option","owner":"piotrmurach","description":"A declarative command-line parser","archived":false,"fork":false,"pushed_at":"2025-04-28T19:58:58.000Z","size":537,"stargazers_count":87,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-01T08:58:50.215Z","etag":null,"topics":["command-line-parser","option-parser","rubygem"],"latest_commit_sha":null,"homepage":"https://ttytoolkit.org/","language":"Ruby","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/piotrmurach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"piotrmurach"}},"created_at":"2020-03-21T14:28:58.000Z","updated_at":"2025-04-28T19:59:01.000Z","dependencies_parsed_at":"2024-01-13T20:35:26.827Z","dependency_job_id":"dfc06578-3167-4e3e-a032-80dc50a0b72e","html_url":"https://github.com/piotrmurach/tty-option","commit_stats":{"total_commits":406,"total_committers":4,"mean_commits":101.5,"dds":0.007389162561576401,"last_synced_commit":"dcdcea08880030b3db3a3a6bda6ca312b0faa6eb"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/piotrmurach/tty-option","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-option","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-option/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-option/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-option/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-option/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-option/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259470951,"owners_count":22862999,"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":["command-line-parser","option-parser","rubygem"],"created_at":"2024-08-06T08:01:55.130Z","updated_at":"2025-06-12T13:09:25.700Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":["Ruby"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://ttytoolkit.org\"\u003e\u003cimg width=\"130\" src=\"https://github.com/piotrmurach/tty/raw/master/images/tty.png\" alt=\"TTY Toolkit logo\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# TTY::Option\n\n[![Gem Version](https://badge.fury.io/rb/tty-option.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-option/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/gxml9ttyvgpeasy5?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/1083a2fd114d6faf5d65/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-option/badge.svg)][coverage]\n\n[gem]: https://badge.fury.io/rb/tty-option\n[gh_actions_ci]: https://github.com/piotrmurach/tty-option/actions/workflows/ci.yml\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-option\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-option/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-option\n\n\u003e Parser for command line arguments, keywords, options and environment variables\n\n## Features\n\n* Parse command line **arguments**, **keywords**, **flags**, **options**\nand **environment variables**.\n* Define command line parameters with **DSL** or **keyword arguments**.\n* Access all parameter values from hash-like **params**.\n* Define **global parameters** with inheritance.\n* Accept command line parameters in **any order**.\n* Handle complex inputs like **lists** and **maps**.\n* **Convert** inputs to basic and more complex object types.\n* Generate **help** from parameter definitions.\n* Customise help with **usage** methods such as **header**, **example** and more.\n* Collect parsing **errors** for a better user experience.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"tty-option\"\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install tty-option\n\n## Contents\n\n* [1. Usage](#1-usage)\n* [2. API](#2-api)\n  * [2.1 argument](#21-argument)\n  * [2.2 keyword](#22-keyword)\n  * [2.3 option](#23-option)\n  * [2.4 environment](#24-environment)\n  * [2.5 parameter settings](#25-parameter-settings)\n    * [2.5.1 arity](#251-arity)\n    * [2.5.2 convert](#252-convert)\n    * [2.5.3 default](#253-default)\n    * [2.5.4 description](#254-description)\n    * [2.5.5 hidden](#255-hidden)\n    * [2.5.6 long](#256-long)\n    * [2.5.7 name](#257-name)\n    * [2.5.8 optional](#258-optional)\n    * [2.5.9 permit](#259-permit)\n    * [2.5.10 required](#2510-required)\n    * [2.5.11 short](#2511-short)\n    * [2.5.12 validate](#2512-validate)\n  * [2.6 parse](#26-parse)\n    * [2.6.1 :raise_on_parse_error](#261-raise_on_parse_error)\n    * [2.6.2 :check_invalid_params](#262-check_invalid_params)\n  * [2.7 params](#27-params)\n    * [2.7.1 errors](#271-errors)\n    * [2.7.2 remaining](#272-remaining)\n    * [2.7.3 valid?](#273-valid)\n  * [2.8 usage](#28-usage)\n    * [2.8.1 header](#281-header)\n    * [2.8.2 program](#282-program)\n    * [2.8.3 command](#283-command)\n    * [2.8.4 banner](#284-banner)\n    * [2.8.5 description](#285-description)\n    * [2.8.6 example](#286-example)\n    * [2.8.7 footer](#287-footer)\n  * [2.9 help](#29-help)\n    * [2.9.1 sections](#291-sections)\n    * [2.9.2 :indent](#292-indent)\n    * [2.9.3 :order](#293-order)\n    * [2.9.4 :param_display](#294-param_display)\n    * [2.9.5 :width](#295-width)\n\n## 1. Usage\n\nInclude the `TTY::Option` module and define parameters to parse command\nline input.\n\nChoose from [arguments](#21-argument), [keywords](#22-keyword),\n[flags](#23-option), [options](#23-option) and\n[environment variables](#24-environment).\n\nFor example, here is a quick demo of how to create a command that mixes\nall parameter types:\n\n```ruby\nclass Command\n  include TTY::Option\n\n  usage do\n    program \"dock\"\n\n    command \"run\"\n\n    desc \"Run a command in a new container\"\n\n    example \"Set working directory (-w)\",\n            \"  $ dock run -w /path/to/dir/ ubuntu pwd\"\n\n    example \u003c\u003c~EOS\n    Mount volume\n      $ dock run -v `pwd`:`pwd` -w `pwd` ubuntu pwd\n    EOS\n  end\n\n  argument :image do\n    required\n    desc \"The name of the image to use\"\n  end\n\n  argument :command do\n    optional\n    desc \"The command to run inside the image\"\n  end\n\n  keyword :restart do\n    default \"no\"\n    permit %w[no on-failure always unless-stopped]\n    desc \"Restart policy to apply when a container exits\"\n  end\n\n  flag :detach do\n    short \"-d\"\n    long \"--detach\"\n    desc \"Run container in background and print container ID\"\n  end\n\n  flag :help do\n    short \"-h\"\n    long \"--help\"\n    desc \"Print usage\"\n  end\n\n  option :name do\n    required\n    long \"--name string\"\n    desc \"Assign a name to the container\"\n  end\n\n  option :port do\n    arity one_or_more\n    short \"-p\"\n    long \"--publish list\"\n    convert :list\n    desc \"Publish a container's port(s) to the host\"\n  end\n\n  def run\n    if params[:help]\n      print help\n    elsif params.errors.any?\n      puts params.errors.summary\n    else\n      pp params.to_h\n    end\n  end\nend\n```\n\nThen create a command instance:\n\n```ruby\ncmd = Command.new\n```\n\nAnd given the following input on the command line:\n\n```\nrestart=always -d -p 5000:3000 5001:8080 --name web ubuntu:16.4 bash\n```\n\nRead the command line input (aka `ARGV`) with [parse](#26-parse):\n\n```ruby\ncmd.parse\n```\n\nOr provide an array of inputs:\n\n```ruby\ncmd.parse(%w[restart=always -d -p 5000:3000 5001:8080 --name web ubuntu:16.4 bash])\n```\n\nFinally, run the command to see parsed values:\n\n```ruby\ncmd.run\n# =\u003e\n# {:help=\u003efalse,\n#  :detach=\u003etrue,\n#  :port=\u003e[\"5000:3000\", \"5001:8080\"],\n#  :name=\u003e\"web\",\n#  :restart=\u003e\"always\",\n#  :image=\u003e\"ubuntu:16.4\",\n#  :command=\u003e\"bash\"}\n```\n\nUse the [params](#27-params) to access all parameters:\n\n```ruby\ncmd.params[:name]     # =\u003e \"web\"\ncmd.params[\"command\"] # =\u003e \"bash\n```\n\nGiven the `--help` flag on the command line:\n\n```ruby\ncmd.parse(%w[--help])\n```\n\nUse the [help](#29-help) method to print help information to the terminal:\n\n```ruby\nprint cmd.help\n```\n\nThis will result in the following output:\n\n```\nUsage: dock run [OPTIONS] IMAGE [COMMAND] [RESTART=RESTART]\n\nRun a command in a new container\n\nArguments:\n  IMAGE    The name of the image to use\n  COMMAND  The command to run inside the image\n\nKeywords:\n  RESTART=RESTART  Restart policy to apply when a container exits (permitted:\n                   no, on-failure, always, unless-stopped) (default \"no\")\n\nOptions:\n  -d, --detach        Run container in background and print container ID\n  -h, --help          Print usage\n      --name string   Assign a name to the container\n  -p, --publish list  Publish a container's port(s) to the host\n\nExamples:\n  Set working directory (-w)\n    $ dock run -w /path/to/dir/ ubuntu pwd\n\n  Mount volume\n    $ dock run -v `pwd`:`pwd` -w `pwd` ubuntu pwd\n```\n\nGiven an invalid command line input:\n\n```ruby\ncmd.parse(%w[--unknown])\n```\n\nUse the [errors](#271-errors) method to print all errors:\n\n```ruby\nputs params.errors.summary\n```\n\nThis will print a summary of all errors:\n\n```\nErrors:\n  1) Invalid option '--unknown'\n  2) Option '--publish' should appear at least 1 time but appeared 0 times\n  3) Option '--name' must be provided\n  4) Argument 'image' must be provided\n```\n\n## 2. API\n\n### 2.1 argument\n\nUse the `argument` method to parse positional arguments.\n\nProvide a name as a string or symbol to define an argument. The name will\nserve as a default label for the help display and a key to retrieve\na value from the [params](#27-params):\n\n```ruby\nargument :foo\n```\n\nGiven the following command line input:\n\n```\n11 12 13\n```\n\nThis would result only in one argument parsed and the remaining ignored:\n\n```ruby\nparams[:foo] # =\u003e \"11\"\n```\n\nThe `argument` method accepts a block to define\n[parameter settings](#25-parameter-settings).\n\nFor example, use the [arity](#251-arity) and [convert](#252-convert) settings\nto parse many positional arguments:\n\n```ruby\nargument :foo do\n  name \"foo(int)\"             # name for help display\n  arity one_or_more           # how many times can appear\n  convert :int_list           # convert input to a list of integers\n  validate -\u003e(v) { v \u003c 14 }   # validation rule\n  desc \"Argument description\" # description for help display\nend\n```\n\nParser would collect all values and convert them to integers given\nprevious input:\n\n```ruby\nparams[:foo] # =\u003e [11, 12, 13]\n```\n\nThe `argument` method can also accept settings as keyword arguments:\n\n```ruby\nargument :foo,\n  name: \"foo(int)\",\n  arity: \"+\",\n  convert: :int_list,\n  validate: -\u003e(v) { v \u003c 14 },\n  desc: \"Argument description\"\n```\n\n### 2.2 keyword\n\nUse the `keyword` method to parse keyword arguments.\n\nProvide a name as a string or symbol to define a keyword argument. The name\nwill serve as a command line input name, a default label for the help\ndisplay and a key to retrieve a value from the [params](#27-params):\n\n```ruby\nkeyword :foo\n```\n\nParser will use the parameter name to match the input name on the command\nline by default.\n\nGiven the following command line input:\n\n```\nfoo=11\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"11\"\n```\n\nNote that the parser performs no conversion of the value.\n\nThe `keyword` method accepts a block to define\n[parameter settings](#25-parameter-settings).\n\nFor example, use the [arity](#251-arity) and [convert](#252-convert)\nsettings to parse many keyword arguments:\n\n```ruby\nkeyword :foo do\n  required                   # by default keyword is not required\n  arity one_or_more          # how many times can appear\n  convert :int_list          # convert input to a list of integers\n  validate -\u003e(v) { v \u003c 14 }  # validation rule\n  desc \"Keyword description\" # description for help display\nend\n```\n\nGiven the following command line input:\n\n```\nfoo=10,11 foo=12 13\n```\n\nThis would result in an array of integers:\n\n```ruby\nparams[:foo] # =\u003e [10, 11, 12, 13]\n```\n\nThe `keyword` method can also accept settings as keyword arguments:\n\n```ruby\nkeyword :foo,\n  required: true,\n  arity: :+,\n  convert: :int_list,\n  validate: -\u003e(v) { v \u003c 14 },\n  desc: \"Keyword description\"\n```\n\n### 2.3 option\n\nUse the `flag` or `option` methods to parse options.\n\nProvide a name as a string or symbol to define an option. The name will\nserve as a command line input name, a label for the help display and\na key to retrieve a value from the [params](#27-params):\n\n```ruby\noption :foo\n```\n\nParser will use the parameter name to generate a long option name by default.\n\nGiven the following command line input:\n\n```\n--foo\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e true\n```\n\nThe `flag` and `option` methods accept a block to define\n[parameter settings](#25-parameter-settings).\n\nFor example, to specify a different name for the parsed option,\nuse the [short](#2511-short) and [long](#256-long) settings:\n\n```ruby\noption :foo do\n  short \"-f\"    # define a short name\n  long \"--foo\"  # define a long name\nend\n```\n\nGiven the following short name on the command line:\n\n```\n-f\n```\n\nThis would result in:\n\n```\nparams[:foo] # =\u003e true\n```\n\nAn option can accept an argument. The argument can be either required\nor optional. To define a required argument, provide an extra label\nin `short` or `long` settings. The label can be any string. When\nboth `short` and `long` names are present, only specify an argument\nfor the long name.\n\nFor example, for both short and long names to accept a required\ninteger argument:\n\n```ruby\noption :foo do\n  short \"-f\"\n  long \"--foo int\"\n  # or\n  long \"--foo=int\"\nend\n```\n\nGiven the following command line input:\n\n```\n--foo=11\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"11\"\n```\n\nNote that the parser performs no conversion of the argument.\n\nTo define an optional argument, surround it with square brackets.\n\nFor example, to accept an optional integer argument:\n\n```ruby\noption :foo do\n  long \"--foo [int]\"\nend\n```\n\nUse the [arity](#251-arity) and [convert](#252-convert) settings to parse\nmany options given as a list of integers:\n\n```ruby\noption :foo do\n  required                   # by default option is not required\n  arity one_or_more          # how many times option can appear\n  short \"-f\"                 # declare a short flag name\n  long \"--foo ints\"          # declare a long flag with a required argument\n  convert :int_list          # convert input to a list of integers\n  validate -\u003e(v) { v \u003c 14 }  # validation rule\n  desc \"Option description\"  # description for help display\nend\n```\n\nGiven the following command line input:\n\n```\n--foo=10,11 -f 12 13\n```\n\nThis would result in an array of integers:\n\n```ruby\nparams[:foo] # =\u003e [10, 11, 12, 13]\n```\n\nThe option method can also accept settings as keyword arguments:\n\n```ruby\noption :foo,\n  required: true,\n  arity: :+,\n  short: \"-f\",\n  long: \"--foo ints\",\n  convert: :int_list,\n  validate: -\u003e { |v| v \u003c 14 },\n  desc: \"Option description\"\n```\n\nThere is a convenience `flag` method to specify a command line option that\naccepts no argument:\n\n```ruby\nflag :foo\n```\n\nFor example, a typical scenario is to specify the help flag:\n\n```ruby\nflag :help do\n  short \"-h\"\n  long \"--help\"\n  desc \"Print usage\"\nend\n```\n\n### 2.4 environment\n\nUse the `environment` or `env` methods to parse environment variables.\n\nProvide a name as a string or symbol to define an environment variable.\nThe name will serve as a command line input name, a default label for the\nhelp display and a key to retrieve a value from the [params](#27-params):\n\n```ruby\nenvironment :foo\n# or\nenv :foo\n```\n\nParser will use the parameter name to match the input name on the command\nline by default.\n\nGiven the following command line input:\n\n```\nFOO=11\n```\n\nThe result would be:\n\n```ruby\nparams[:foo] # =\u003e \"11\"\n```\n\nNote that the parser performs no conversion of the value.\n\nThe `environment` method accepts a block to define\n[parameter settings](#25-parameter-settings).\n\nFor example, use the [name](#257-name) setting to change a default\nvariable name:\n\n```ruby\nenvironment :foo do\n  name \"FOO_ENV\"\nend\n```\n\nGiven the following command line input:\n\n```\nFOO_ENV=11\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"11\"\n```\n\nFor example, use the [arity](#251-arity) and [convert](#252-convert) settings\nto parse many environment variables given as a list of integers:\n\n```ruby\nenvironment :foo do\n  required                        # by default environment is not required\n  arity one_or_more               # how many times env var can appear\n  name \"FOO_ENV\"                  # the command line input name\n  convert :int_list               # convert input to a map of integers\n  validate -\u003e(v) { v \u003c 14 }       # validation rule\n  desc \"Environment description\"  # description for help display\nend\n```\n\nGiven the following command line input:\n\n```\nFOO_ENV=10,11 FOO_ENV=12 13\n```\n\nThis would result in an array of integers:\n\n```ruby\nparams[:foo] # =\u003e [10, 11, 12, 13]\n```\n\nThe `environment` method can also accept settings as keyword arguments:\n\n```ruby\nenvironment :foo,\n  required: true,\n  arity: :+,\n  name: \"FOO_ENV\",\n  convert: :int_list,\n  validate: -\u003e(v) { v \u003c 14 },\n  desc: \"Environment description\"\n```\n\n### 2.5 parameter settings\n\nAll parameter types support the following settings except for\n`short` and `long`, which are [option](#23-option) specific.\n\n#### 2.5.1 arity\n\nUse the `arity` setting to describe how many times a given parameter may\nappear on the command line.\n\nEvery parameter can appear only once by default. In the case of arguments,\nthe parser will match the first input and ignore the rest. For other\nparameter types, any extra parameter occurrence will override previously\nparsed input. Setting the arity requirement overrides this behaviour.\n\nFor example, to match an argument exactly two times:\n\n```ruby\nargument :foo do\n  arity 2\nend\n```\n\nGiven the following command line input:\n\n```ruby\nbar baz\n```\n\nThis would result in an array of strings:\n\n```ruby\nparams[:foo] # =\u003e [\"bar\", \"baz\"]\n```\n\nAnother example is to match exactly three occurrences of a keyword:\n\n```ruby\nkeyword :foo do\n  arity 3\nend\n```\n\nAnd then given the following on the command line:\n\n```\nfoo=1 foo=2 foo=3\n```\n\nThis would result in an array of strings:\n\n```ruby\nparams[:foo] # =\u003e [\"1\", \"2\", \"3\"]\n```\n\nUse `:any`, `:*`, `-1`, `any` or `zero_or_more` to specify that parameter\nmay appear any number of times.\n\nFor example, to expect an argument to appear zero or more times:\n\n```ruby\nargument :foo do\n  arity zero_or_more\nend\n```\n\nUse `:+` or `one_or_more` to specify that parameter must appear at least once.\n\nFor example, to expect an option with an argument to appear one or more times:\n\n```ruby\noption :foo do\n  arity one_or_more\n  short \"-f\"\n  long \"--foo string\"\nend\n```\n\nUse `at_least` to specify the least number of times a parameter can appear:\n\nFor example, to expect a keyword to appear at least three times:\n\n```ruby\nkeyword :foo do\n  arity at_least(3)\nend\n```\n\nThe [help](#29-help) method will handle the arity for the usage banner.\n\nFor example, given the following argument definition:\n\n```ruby\nargument :foo do\n  arity one_or_more\nend\n```\n\nThe usage banner would display:\n\n```\nUsage: foobar FOO [FOO...]\n```\n\n#### 2.5.2 convert\n\nUse the `convert` setting to transform any parameter argument to another type.\n\nThe `convert` accepts a conversion name as a predefined symbol or class.\n\nFor example, to convert an argument to an integer:\n\n```ruby\nargument :foo do\n  convert :int\n  # or\n  convert Integer\nend\n```\n\nThe supported conversion types are:\n\n* `:bool` or `:boolean` - e.g. `yes,1,y,t` becomes `true`,\n`no,0,n,f` becomes `false`\n* `:date` - e.g. `28/03/2020` becomes `#\u003cDate: 2020-03-28...\u003e`\n* `:float` - e.g. `-1` becomes `-1.0`\n* `:int` or `:integer` - e.g. `+1` becomes `1`\n* `:path` or `:pathname` - e.g. `/foo/bar/baz` becomes\n`#\u003cPathname:/foo/bar/baz\u003e`\n* `:regex` or `:regexp` - e.g. `foo|bar` becomes `/foo|bar/`\n* `:uri` - e.g. `foo.com` becomes `#\u003cURI::Generic foo.com\u003e`\n* `:sym` or `:symbol` - e.g. `foo` becomes `:foo`\n* `:list` or `:array` - e.g. `a,b,c` becomes `[\"a\", \"b\", \"c\"]`\n* `:map` or `:hash` - e.g. `a:1 b:2 c:3` becomes `{a: \"1\", b: \"2\", c: \"3\"}`\n\nTo convert to an array of a given type, specify plural or append an `array`\nor`list` to any base type:\n\n* `:bools`, `:bool_array` or `:bool_list` - e.g. `t,f,t` becomes\n`[true, false, true]`\n* `:floats`, `:float_array` or `:float_list` - e.g. `1,2,3` becomes\n`[1.0, 2.0, 3.0]`\n* `:ints`, `:int_array` or `:int_list` - e.g. `1,2,3` becomes `[1, 2, 3]`\n\nOr, use the `list_of` method and pass the type as a first argument.\n\nTo convert to a hash with values of a given type, append a `hash` or `map` to\nany base type:\n\n* `:bool_hash` or `:bool_map` - e.g `a:t b:f c:t` becomes\n`{a: true, b: false, c: true}`\n* `:float_hash` or `:float_map` - e.g `a:1 b:2 c:3` becomes\n`{a: 1.0, b: 2.0, c: 3.0}`\n* `:int_hash` or `:int_map` - e.g `a:1 b:2 c:3` becomes `{a: 1, b: 2, c: 3}`\n\nOr, use the `map_of` method and pass the type as a first argument.\n\nFor example, given options with a required list and map arguments:\n\n```ruby\noption :foo do\n  long \"--foo list\"\n  convert :bools\n  # or\n  convert list_of(:bool)\nend\n\noption :bar do\n  long \"--bar map\"\n  convert :int_map\n  # or\n  convert map_of(:int)\nend\n```\n\nAnd then parsing the following command line input:\n\n```\n--foo t,f,t --bar a:1 b:2 c:3\n```\n\nThis would result in an array of booleans and a hash with integer values:\n\n```ruby\nparams[:foo] # =\u003e [true, false, true]\nparams[:bar] # =\u003e {:a=\u003e1, :b=\u003e2, :c=\u003e3}\n```\n\nUse a `Proc` object to define custom conversion.\n\nFor example, to convert the command line input to uppercase:\n\n```ruby\noption :foo do\n  long \"--foo string\"\n  convert -\u003e(val) { val.upcase }\nend\n```\n\n#### 2.5.3 default\n\nUse the `default` setting to specify a default value for an optional parameter.\nThe parser will use default when the command line input isn't present.\n\nFor example, given the following option definition:\n\n```ruby\noption :foo do\n  long \"--foo string\"\n  default \"bar\"\nend\n```\n\nWhen the option `--foo` isn't present on the command line, the `params`\nwill have a default value set:\n\n```ruby\nparams[:foo] # =\u003e \"bar\"\n```\n\nOr, use a `Proc` object to specify a default value:\n\n```ruby\noption :foo do\n  long \"--foo string\"\n  default -\u003e { \"bar\" }\nend\n```\n\nA parameter cannot be both required and have a default value. This will raise\n`ConfigurationError`. The parser treats positional arguments as required.\nTo have a default for a required argument make it [optional](#258-optional):\n\n```ruby\nargument :foo do\n  optional\n  default \"bar\"\n  desc \"Argument description\"\nend\n```\n\nThe usage description for a given parameter will display the default value:\n\n```\nUsage: foobar [FOO]\n\nArguments:\n  FOO  Argument description (default \"bar\")\n```\n\n#### 2.5.4 description\n\nUse the `description` or `desc` setting to provide a summary for\na parameter. The [help](#29-help) method uses a parameter\ndescription to generate a usage display.\n\nFor example, given an option with a description:\n\n```ruby\noption :foo do\n  desc \"Option description\"\nend\n```\n\nThis will result in the following help display:\n\n```\nUsage: foobar [OPTIONS]\n\nOptions:\n  --foo  Option description\n```\n\n#### 2.5.5 hidden\n\nUse the `hidden` setting to hide a parameter from the [help](#29-help) display.\n\nFor example, given a standard argument and a hidden one:\n\n```ruby\nargument :foo\n\nargument :bar do\n  hidden\nend\n```\n\nThe above will hide the `:bar` parameter from the usage banner:\n\n```\nUsage: foobar FOO\n```\n\n#### 2.5.6 long\n\nOnly [flag](#23-option) and [option](#23-option) parameters can use\nthe `long` setting.\n\nUse the `long` setting to define a long name for an option. By convention,\na long name uses a double dash followed by many characters.\n\nWhen you don't specify a short or long name, the parameter name\nwill serve as the option's long name by default.\n\nFor example, to define the `--foo` option:\n\n```ruby\noption :foo\n```\n\nTo change the default name to the `--fuu` option:\n\n```ruby\noption :foo do\n  long \"--fuu\"\nend\n```\n\nA long option can accept an argument. The argument can be either required\nor optional. To define a required argument, separate it from the option\nname with a space or an equal sign.\n\nFor the `:foo` option to accept a required integer argument:\n\n```ruby\noption :foo do\n  long \"--foo int\"\nend\n```\n\nThese are all equivalent ways to define a long option with a required\nargument:\n\n```ruby\nlong \"--foo int\"\nlong \"--foo=int\"\n```\n\nTo define an optional argument, surround it with square brackets. Like\nthe required argument, separate it from the option name with a space\nor an equal sign. It is possible to skip the space, but that would\nmake the option description hard to read.\n\nFor the `:foo` option to accept an optional integer argument:\n\n```ruby\noption :foo do\n  long \"--foo [int]\"\nend\n```\n\nThese are all equivalent ways to define a long option with\nan optional argument:\n\n```ruby\nlong \"--foo [int]\"\nlong \"--foo=[int]\"\nlong \"--foo[int]\"\n```\n\nWhen specifying short and long option names, only define the argument\nfor the long name.\n\nFor example, to define an option with short and long names that accepts\na required integer argument:\n\n```ruby\noption :foo do\n  short \"-f\"\n  long \"--foo int\"\nend\n```\n\nNote that the parser performs no conversion of the argument. Use the\n[convert](#252-convert) setting to transform the argument type.\n\n#### 2.5.7 name\n\nThe parser will use a parameter name to match command line inputs by default.\nIt will convert underscores in a name into dashes when matching input.\n\nFor example, given the `:foo_bar` keyword definition:\n\n```ruby\nkeyword :foo_bar\n```\n\nAnd the following command line input:\n\n```\nfoo-bar=baz\n```\n\nThis would result in:\n\n```ruby\nparams[:foo_bar] # =\u003e \"baz\"\n```\n\nUse the `name` setting to change the parameter default input name.\n\n```ruby\nkeyword :foo_bar do\n  name \"fum\"\nend\n```\n\nGiven the following command line input:\n\n```\nfum=baz\n```\n\nThis would result in:\n\n```ruby\nparams[:foo_bar] # =\u003e \"baz\"\n```\n\nUse uppercase characters when changing the input name for\nenvironment variables:\n\n```ruby\nenv :foo do\n  name \"FOO_VAR\"\nend\n```\n\n#### 2.5.8 optional\n\nAll parameters are optional apart from positional arguments.\n\nUse the `optional` setting to mark a parameter as optional.\n\nFor example, given a required argument and an optional one:\n\n```ruby\nargument :foo do\n  desc \"Foo argument description\"\nend\n\nargument :bar do\n  optional\n  desc \"Bar argument description\"\nend\n```\n\nAnd given the following command line input:\n\n```\nbaz\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"baz\"\nparams[:bar] # =\u003e nil\n```\n\nThe usage banner will display an optional argument surrounded by brackets:\n\n```\nUsage: foobar FOO [BAR]\n\nArguments:\n  FOO  Foo argument description\n  BAR  Bar argument description\n```\n\n#### 2.5.9 permit\n\nUse the `permit` setting to restrict input to a set of possible values.\n\nFor example, to restrict the `:foo` option to only `\"bar\"` and `\"baz\"` strings:\n\n```ruby\noption :foo do\n  long \"--foo string\"\n  permit %w[bar baz]\nend\n```\n\nGiven the following command line input:\n\n```\n--foo bar\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"bar\"\n```\n\nGiven not permitted value `qux` on the command line:\n\n```\n--foo qux\n```\n\nThis would raise a `TTY::Option::UnpermittedArgument` error and\nmake the [params](#27-params) invalid.\n\nThe parser checks permitted values after applying conversion first. Because\nof this, permit setting needs its values to be already of the correct type.\n\nFor example, given integer conversion, permitted values need to\nbe integers as well:\n\n```ruby\noption :foo do\n  long \"--foo int\"\n  convert :int\n  permit [11, 12, 13]\nend\n```\n\nThen given not permitted integer:\n\n```\n--foo 14\n```\n\nThis would invalidate `params` and collect the\n`TTY::Option::UnpermittedArgument` error.\n\nThe [help](#29-help) method displays permitted values in the\nparameter description.\n\nFor example, given the following option:\n\n```ruby\noption :foo do\n  short \"-f\"\n  long \"--foo string\"\n  permit %w[a b c d]\n  desc \"Option description\"\nend\n```\n\nThen the description for the option would be:\n\n```\nUsage: foobar [OPTIONS]\n\nOptions:\n  -f, --foo string  Option description (permitted: a, b, c, d)\n```\n\n#### 2.5.10 required\n\nParser only requires arguments to be present on the command line by default.\nAny other parameters like options, keywords and environment variables\nare optional.\n\nUse the `required` setting to force parameter presence in command line input.\n\nFor example, given a required keyword and an optional one:\n\n```ruby\nkeyword :foo do\n  required\n  desc \"Foo keyword description\"\nend\n\nkeyword :bar do\n  desc \"Bar keyword description\"\nend\n```\n\nAnd given the following command line input:\n\n```\nfoo=baz\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"baz\"\nparams[:bar] # =\u003e nil\n```\n\nGiven the following command line input without the `foo` keyword:\n\n```\nbar=baz\n```\n\nThis would raise a `TTY::Option::MissingParameter` error.\n\nThen printing [errors](#271-errors) summary would display the following\nerror description:\n\n```\nError: keyword 'foo' must be provided\n```\n\nThe usage banner displays the required parameters first. Then surrounds any\noptional parameters in brackets.\n\nThe [help](#29-help) display for the above keywords would be:\n\n```\nUsage: foobar FOO=FOO [BAR=BAR]\n\nKeywords:\n  FOO=FOO  Foo keyword description\n  BAR=BAR  Bar keyword description\n```\n\n#### 2.5.11 short\n\nOnly [flag](#23-option) and [option](#23-option) parameters can use\nthe `short` setting.\n\nUse the `short` setting to define a short name for an option. By convention,\na short name uses a single dash followed by a single alphanumeric character.\n\nFor example, to define the `-f` option:\n\n```ruby\noption :foo do\n  short \"-f\"\nend\n```\n\nA short option can accept an argument. The argument can be either required\nor optional. To define a required argument, separate it from the option\nname with a space or an equal sign. It is possible to skip the space,\nbut that would make the option description hard to read.\n\nFor the `:foo` option to accept a required integer argument:\n\n```ruby\noption :foo do\n  short \"-f int\"\nend\n```\n\nThese are all equivalent ways to define a short option with a required\nargument:\n\n```ruby\nshort \"-f int\"\nshort \"-f=int\"\nshort \"-fint\"\n```\n\nTo define an optional argument, surround it with square brackets. Like\nthe required argument, separate it from the option name with a space\nor an equal sign. It is possible to skip the space, but that would\nmake the option description hard to read.\n\nFor the `:foo` option to accept an optional integer argument:\n\n```ruby\noption :foo do\n  short \"-f [int]\"\nend\n```\n\nThese are all equivalent ways to define a short option with\nan optional argument:\n\n```ruby\nshort \"-f [int]\"\nshort \"-f=[int]\"\nshort \"-f[int]\"\n```\n\nWhen specifying short and long option names, only define the argument\nfor the long name.\n\nFor example, to define an option with short and long names that accepts\na required integer argument:\n\n```ruby\noption :foo do\n  short \"-f\"\n  long \"--foo int\"\nend\n```\n\nNote that the parser performs no conversion of the argument. Use\nthe [convert](#252-convert) setting to transform the argument type.\n\n#### 2.5.12 validate\n\nUse the `validate` setting to ensure that inputs match a validation rule.\nThe rule can be a string, a regular expression or a `Proc` object.\n\nFor example, to ensure the `--foo` option only accepts digits:\n\n```ruby\noption :foo do\n  long \"--foo int\"\n  validate \"\\d+\"\nend\n```\n\nGiven the following command line input:\n\n```\n--foo bar\n```\n\nThis would raise a `TTY::Option::InvalidArgument` error that would\nmake `params` invalid.\n\nThen printing [errors](#271-errors) summary would output:\n\n```\nError: value of `bar` fails validation for '--foo' option\n```\n\nTo define a validation rule as a `Proc` object that accepts\nan argument to check:\n\n```ruby\nkeyword :foo do\n  convert :int\n  validate -\u003e(val) { val \u003c 12 }\nend\n```\n\nThe parser validates a value after applying conversion first. Because of\nthis, the value inside a validation rule is already of the correct type.\n\nGiven the following command line input:\n\n```\nfoo=13\n```\n\nThis would raise a `TTY::Option::InvalidArgument` error and make\n`params` invalid.\n\nThen using the [errors](#271-errors) summary would print the following error:\n\n```\nError: value of `13` fails validation for 'foo' keyword\n```\n\n### 2.6 parse\n\nUse the `parse` method to match command line inputs against defined parameters.\n\nThe `parse` method reads the input from the command line (aka `ARGV`) and\nthe environment variables (aka `ENV`) by default. It also accepts inputs\nas an argument. This is useful when testing commands.\n\nFor example, given the following parameter definitions:\n\n```ruby\nargument :foo\n\nflag :bar\n\nkeyword :baz\n\nenv :qux\n```\n\nThen parsing the command line inputs:\n\n```ruby\nparse(%w[12 --bar baz=a QUX=b])\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e \"12\"\nparams[:bar] # =\u003e true\nparams[:baz] # =\u003e \"a\"\nparams[:qux] # =\u003e \"b\"\n```\n\nThe parser doesn't force any order for the parameters except for arguments.\n\nFor example, reordering inputs for the previous parameter definitions:\n\n```ruby\nparse(%w[12 QUX=b --bar baz=a])\n```\n\nThis would result in the same values:\n\n```ruby\nparams[:foo] # =\u003e \"12\"\nparams[:bar] # =\u003e true\nparams[:baz] # =\u003e \"a\"\nparams[:qux] # =\u003e \"b\"\n```\n\nThe parser handles compact shorthand options that start with\na single dash. These must be boolean options except for\nthe last one that can accept an argument.\n\nFor example, passing three flags and an option with an argument to parse:\n\n```\nparse(%w[-f -b -q -s 12])\n```\n\nThis is equivalent to parsing:\n\n```\nparse(%w[-fbqs 12])\n```\n\nParameter parsing stops at the `--` terminator. The parser collects leftover\ninputs and makes them accessible with the [remaining](#272-remaining) method.\n\nFor example, given extra input after the terminator:\n\n```ruby\nparse(%w[12 baz=a QUX=b -- --fum])\n```\n\nThis would result in:\n\n```ruby\nparams[:foo] # =\u003e 12\nparams[:bar] # =\u003e false\nparams[:baz] # =\u003e \"a\"\nparams[:qux] # =\u003e \"b\"\nparams.remaining # =\u003e [\"--fum\"]\n```\n\n#### 2.6.1 :raise_on_parse_error\n\nThe `parse` method doesn't raise any errors by default. Why? Displaying\nerror backtraces in the terminal output may not be helpful for users.\nInstead, the parser collects any errors and exposes them through the\n[errors](#271-errors) method.\n\nUse the `:raise_on_parse_error` keyword set to `true` to raise parsing errors:\n\n```ruby\nparse(raise_on_parse_error: true)\n```\n\nParsing errors inherit from `TTY::Option::ParseError`.\n\nFor example, to catch parsing errors:\n\n```ruby\nbegin\n  parse(raise_on_parse_error: true)\nrescue TTY::Option::ParseError =\u003e err\n  ...\nend\n```\n\n#### 2.6.2 :check_invalid_params\n\nUsers can provide any input, including parameters the parser\ndidn't expect and define.\n\nWhen the parser finds an unknown input on the command line, it raises\na `TTY::Option::InvalidParameter` error and adds it to the\n[errors](#271-errors) array.\n\nUse the `:check_invalid_params` keyword set to `false` to ignore unknown\ninputs during parsing:\n\n```ruby\nparse(check_invalid_params: false)\n```\n\nThis way, the parser will collect all the unrecognised inputs into the\n[remaining](#272-remaining) array.\n\n### 2.7 params\n\nAll defined parameters are accessible from the `params` object.\n\nThe `params` object behaves like a hash with indifferent access. It doesn't\ndifferentiate between arguments, keywords, options or environment variables.\nBecause of that, each parameter needs to have a unique name.\n\nFor example, given a command with all parameter types:\n\n```ruby\nclass Command\n  include TTY::Option\n\n  argument :foo\n\n  keyword :bar\n\n  option :baz do\n    long \"--baz string\"\n  end\n\n  env :qux\n\n  def run\n    print params[:foo]\n    print params[\"bar\"]\n    print params[\"baz\"]\n    print params[:qux]\n  end\nend\n```\n\nAnd the following command line input:\n\n```\na bar=b --baz c QUX=d\n```\n\nThen instantiating the command:\n\n```ruby\ncmd = Command.new\n```\n\nAnd parsing command line input:\n\n```ruby\ncmd.parse\n```\n\nAnd running the command:\n\n```ruby\ncmd.run\n```\n\nThis would result in the following output:\n\n```\nabcd\n```\n\n#### 2.7.1 errors\n\nThe `parse` method only raises configuration errors. The parsing errors are\nnot raised by default. Instead, the `errors` method on the `params` object\ngives access to any parsing error.\n\n```ruby\nparams.errors # =\u003e TTY::Option::AggregateErrors\n```\n\nThe `errors` method returns an `TTY::Option::AggregateErrors` object that\nis an `Enumerable`.\n\nFor example, to iterate over all the errors:\n\n```ruby\nparams.errors.each do |error|\n  ...\nend\n```\n\nThe `TTY::Option::AggregateErrors` object has the following\nconvenience methods:\n\n* `messages` - an array of all error messages\n* `summary` - a string of formatted error messages ready to display\nin the terminal\n\nFor example, given an argument that needs to appear at least two times in\nthe command line input:\n\n```ruby\nargument :foo do\n  arity at_least(2)\nend\n```\n\nAnd parsing only one argument from the command line input:\n\n```ruby\nparse(%w[12])\n```\n\nThen printing errors summary:\n\n```ruby\nputs params.errors.summary\n```\n\nThis would print the following error message:\n\n```\nError: argument 'foo' should appear at least 2 times but appeared 1 time\n```\n\nAdding integer conversion to the previous example:\n\n```ruby\nargument :foo do\n  arity at_least(2)\n  convert :int\nend\n```\n\nAnd given only one invalid argument to parse:\n\n```ruby\nparse(%w[zzz])\n```\n\nThe summary would be:\n\n```\nErrors:\n  1) Argument 'foo' should appear at least 2 times but appeared 1 time\n  2) Cannot convert value of `zzz` into 'int' type for 'foo' argument\n```\n\nUse the [:raise_on_parse_error](#261-raise_on_parse_error) keyword to raise\nparsing errors on invalid input.\n\nConsider using the [tty-exit](https://github.com/piotrmurach/tty-exit) gem\nfor more expressive exit code reporting.\n\nFor example, the `TTY::Exit` module provides the `exit_with` method:\n\n```ruby\nclass Command\n  include TTY::Exit\n  include TTY::Option\n\n  def run\n    if params.errors.any?\n      exit_with(:usage_error, params.errors.summary)\n    end\n    ...\n  end\nend\n```\n\n#### 2.7.2 remaining\n\nWhen the parser finds an unknown input on the command line, it raises\na `TTY::Option::InvalidParameter` error and adds it to the\n[errors](#271-errors) array.\n\nUse the [:check_invalid_params](#262-check_invalid_params) keyword\nset to `false` to ignore unknown inputs during parsing:\n\n```ruby\nparse(check_invalid_params: false)\n```\n\nThis way, the parser will collect all the unrecognised inputs\ninto an array. The `remaining` method on the `params` gives access\nto all invalid inputs.\n\nFor example, given an unknown option to parse:\n\n```ruby\nparse(%w[--unknown])\n```\n\nThen inspecting the `remaining` inputs:\n\n```ruby\nparams.remaining # =\u003e [\"--unknown\"]\n```\n\nThe parser leaves any inputs after the `--` terminator alone. Instead,\nit collects them into the remaining array. This is useful when passing\ninputs over to other command line applications.\n\n#### 2.7.3 valid?\n\nUse the `valid?` method to check that command line inputs meet all\nvalidation rules.\n\nThe `valid?` method is available on the `params` object:\n\n```ruby\nparams.valid? # =\u003e true\n```\n\nUse the [errors](#271-errors) method to check for any errors and not only\nvalidation rules:\n\n```ruby\nparams.errors.any?\n```\n\n### 2.8 usage\n\nThe `usage` method accepts a block that configures the\n[help](#29-help) display.\n\n#### 2.8.1 header\n\nUse the `header` setting to display information above the banner.\n\nFor example, to explain a program's purpose:\n\n```ruby\nusage do\n  header \"A command line interface for foo service\"\nend\n```\n\nThis would print:\n\n```\nA command line interface for foo service\n\nUsage: foo [OPTIONS]\n```\n\nThe `header` setting accepts many arguments, each representing a single\nparagraph. An empty string displays as a new line.\n\nFor example, to create an introduction with two paragraphs separated by\nan empty line:\n\n```ruby\nusage do\n  header \"A command line interface for foo service\",\n         \"\",\n         \"Access and retrieve data from foo service\"\nend\n```\n\nOr, add two paragraphs using the `header` setting twice:\n\n```ruby\nusage do\n  header \"A command line interface for foo service\"\n\n  header \"Access and retrieve data from foo service\"\nend\n```\n\nBoth would result in the same output:\n\n```\nA command line interface for foo service\n\nAccess and retrieve data from foo service\n\nUsage: foo [OPTIONS]\n```\n\n#### 2.8.2 program\n\nThe `program` setting uses an executable file name to generate a program\nname by default.\n\nFor example, to override the default name:\n\n```ruby\nusage do\n  program \"custom-name\"\nend\n```\n\nThen usage banner will display a custom program name:\n\n```\nUsage: custom-name\n```\n\n#### 2.8.3 command\n\nThe `command` setting uses a class name to generate a command name by default.\nIt converts a class name into a dash case.\n\nFor example, given the following command class name:\n\n```ruby\nclass NetworkCreate\n  include TTY::Option\nend\n```\n\nThe command name would become `network-create`.\n\nUse the `command` or `commands` setting to change the default command name.\n\nFor example, to change the previous class's default command name:\n\n```ruby\nclass NetworkCreate\n  include TTY::Option\n\n  usage do\n    command \"net-create\"\n  end\nend\n```\n\nThe usage banner would be:\n\n```\nUsage: program net-create\n```\n\nUse the `commands` setting for naming a subcommand.\n\nFor example, to add `create` command as a subcommand:\n\n```ruby\nmodule Network\n  class Create\n    include TTY::Option\n\n    usage do\n      commands \"network\", \"create\"\n    end\n  end\nend\n```\n\nThis will result in the following usage banner:\n\n```\nUsage: program network create\n```\n\nUse the `no_command` setting to skip having a command name:\n\n```ruby\nusage do\n  no_command\nend\n```\n\nThis will display only the program name:\n\n```\nUsage: program\n```\n\n#### 2.8.4 banner\n\nThe `banner` setting combines program, command and parameter names\nto generate usage banner.\n\nFor example, given the following usage and parameter definitions:\n\n```ruby\nusage do\n  program \"prog\"\n\n  command \"cmd\"\nend\n\nargument :foo\n\nkeyword :bar\n\noption :baz\n\nenv :qux\n```\n\nThen usage banner would print as follows:\n\n```\nUsage: prog cmd [OPTIONS] [ENVIRONMENT] FOO [BAR=BAR]\n```\n\nThe [help](#29-help) generator displays the usage banner first\nunless a [header](#281-header) is set.\n\nUse the `banner` setting to create a custom usage display.\n\nFor example, to change the parameters format:\n\n```ruby\nusage do\n  program \"prog\"\n\n  command \"cmd\"\n\n  banner \"Usage: #{program} #{command.first} \u003copts\u003e \u003cenvs\u003e foo [bar=bar]\"\nend\n```\n\nThis would display as:\n\n```\nUsage: prog cmd \u003copts\u003e \u003cenvs\u003e foo [bar=bar]\n```\n\nUse the [:param_display](#294-param_display) setting to change the banner\nparameters format.\n\n#### 2.8.5 description\n\nUse `description` or `desc` setting to display information right after\nthe usage banner.\n\nFor example, to give extra information:\n\n```ruby\nusage do\n  desc \"A description for foo service\"\nend\n```\n\nThis would print:\n\n```\nUsage: foo [OPTIONS]\n\nA description for foo service\n```\n\nThe `desc` setting accepts many arguments, each representing a single\nparagraph. An empty string displays as a new line.\n\nFor example, to create a description with two paragraphs separated by\nan empty line:\n\n```ruby\nusage do\n desc \"A description for foo service\",\n      \"\",\n      \"Learn more about foo service\\nby reading tutorials\"\nend\n```\n\nOr, add two paragraphs using the `desc` setting twice:\n\n```ruby\nusage do\n  desc \"A description for foo service\",\n\n  desc \u003c\u003c~EOS\n  Learn more about foo service\n  by reading tutorials\n  EOS\nend\n```\n\nBoth would result in the same output:\n\n```\nUsage: foo [OPTIONS]\n\nA description for foo service\n\nLearn more about foo service\nby reading tutorials\n```\n\n#### 2.8.6 example\n\nUse the `example` or `examples` setting to add a usage examples section\nto the help display.\n\nThe `example` setting accepts many arguments, each representing a single\nparagraph. An empty string displays as a new line.\n\nFor instance, to create an example usage displayed on two lines:\n\n```ruby\nusage do\n  example \"Some example how to use foo\",\n          \" $ foo bar\"\nend\n```\n\nThis will result in the following help output:\n\n```\nExamples:\n  Some example how to use foo\n    $ foo bar\n```\n\nOr, add two examples using the `example` setting twice:\n\n\n```ruby\nusage do\n  example \"Some example how to use foo\",\n          \" $ foo bar\"\n\n  example \u003c\u003c~EOS\n  Another example how to use foo\"\n    $ foo baz\n  EOS\nend\n```\n\nThe examples section would display the following:\n\n```\nExamples:\n  Some example how to use foo\n    $ foo bar\n\n  Another example how to use foo\n    $ foo baz\n```\n\n#### 2.8.7 footer\n\nUse the `footer` setting to display text after all information\nin the usage help.\n\nFor example, to reference further help:\n\n```ruby\nusage do\n  footer \"Run a command followed by --help to see more info.\"\nend\n```\n\nThis would print as follows:\n\n```\nUsage: foo [OPTIONS]\n\nRun a command followed by --help to see more info.\n```\n\nThe `footer` setting accepts many arguments, each representing a single\nparagraph. An empty string displays as a new line.\n\nFor example, to display further help with two paragraphs separated by\nan empty line:\n\n```ruby\nusage do\n  footer \"Run a command followed by --help to see more info.\",\n         \"\",\n         \"Report bugs to the mailing list.\"\nend\n```\n\nOr, add two paragraphs using the `footer` setting twice:\n\n```ruby\nusage do\n  footer \"Run a command followed by --help to see more info.\"\n\n  footer \"Report bugs to the mailing list.\"\nend\n```\n\nBoth would result in the same output:\n\n```\nUsage: foo [OPTIONS]\n\nRun a command followed by --help to see more info.\n\nReport bugs to the mailing list.\n```\n\n### 2.9 help\n\nUse the `help` method to generate usage information about defined parameters.\n\nThe [usage](#28-usage) describes how to add different sections to the\nhelp display.\n\nFor example, given the following command class definition with\na `run` method that prints help:\n\n\n```ruby\nclass Command\n  include TTY::Option\n\n  usage do\n    program \"foobar\"\n    no_command\n    header \"foobar CLI\"\n    desc \"CLI description\"\n    example \"Example usage\"\n    footer \"Run --help to see more info\"\n  end\n\n  argument :foo, desc: \"Argument description\"\n  keyword :bar, desc: \"Keyword description\"\n  option :baz, desc: \"Option description\"\n  env :qux, desc: \"Environment description\"\n\n  flag :help do\n    short \"-h\"\n    long  \"--help\"\n    desc \"Print usage\"\n  end\n\n  def run\n    if params[:help]\n      print help\n      exit\n    end\n  end\nend\n```\n\nRunning the command with `--help` flag:\n\n```ruby\ncmd = Command.new\ncmd.parse(%w[--help])\ncmd.run\n```\n\nThis would result in the following help display:\n\n```\nfoobar CLI\n\nUsage: foobar [OPTIONS] [ENVIRONMENT] FOO [BAR=BAR]\n\nCLI description\n\nArguments:\n  FOO  Argument description\n\nKeywords:\n  BAR=BAR  Keyword description\n\nOptions:\n      --baz   Option description\n  -h, --help  Print usage\n\nEnvironment:\n  QUX  Environment description\n\nExamples:\n  Example usage\n\nRun --help to see more info\n```\n\n#### 2.9.1 sections\n\nPass a block to the `help` method to change generated usage information.\nThe block accepts a single argument, a `TTY::Option::Sections` object.\nThis object provides hash-like access to each named part of the help display.\n\nThe following are the names of all supported sections ordered by help display\nfrom top to bottom:\n\n* `:header`\n* `:banner`\n* `:description`\n* `:arguments`\n* `:keywords`\n* `:options`\n* `:environments`\n* `:examples`\n* `:footer`\n\nAccessing a named section returns a `TTY::Option::Section` object\nwith `name` and `content` methods.\n\nFor example, to access the arguments section content:\n\n```ruby\nhelp do |sections|\n  sections[:arguments].content # =\u003e \"\\nArguments:\\n  FOO  Argument description\"\nend\n```\n\nTo add a new section, use the `add_after` and `add_before` methods. These\nmethods accept three arguments. The first argument is the section name\nto add after or before. The second argument is a new section name,\nand the last is content to add.\n\nFor example, to insert a new commands section after the description:\n\n```ruby\nhelp do |sections|\n  sections.add_after :description, :commands, \u003c\u003c~EOS.chomp\n\n  Commands:\n    create  Create command description\n    delete  Delete command description\n  EOS\nend\n```\n\nGiven the following usage and parameter definition:\n\n```ruby\nusage do\n  program \"prog\"\n\n  command \"cmd\"\n\n  desc \"Program description\"\nend\n\nargument :foo do\n  desc \"Foo argument description\"\nend\n```\n\nThe help display would be:\n\n```\nUsage: prog cmd FOO\n\nProgram description\n\nCommands:\n  create  Create command description\n  delete  Delete command description\n\nArguments:\n  FOO  Argument description\n```\n\nUse `delete` and `replace` methods to change existing sections.\n\nFor example, to remove a header section:\n\n```ruby\nhelp do |sections|\n  sections.delete :header\nend\n```\n\nOr, to replace the content of a footer section:\n\n```ruby\nhelp do |sections|\n  sections.replace :footer, \"\\nReport bugs to the mailing list.\"\nend\n```\n\n#### 2.9.2 :indent\n\nThe help output has no indentation except for displaying parameters by default.\n\nUse the `:indent` keyword to change the indentation of the help display.\n\nFor example, to indent help display by two spaces:\n\n```ruby\nhelp(indent: 2)\n```\n\n#### 2.9.3 :order\n\nThe help generator orders parameters alphabetically within\neach section by default.\n\nUse the `:order` keyword to change the default ordering.\n\nThe `:order` expects a `Proc` object as a value. The `Proc` accepts\na single argument, an array of parameters within a section.\n\nFor example, to preserve the parameter definition order:\n\n```ruby\nhelp(order: -\u003e(params) { params })\n```\n\n#### 2.9.4 :param_display\n\nThe usage banner displays positional and keyword arguments\nin uppercase letters by default.\n\nFor example, given the following parameter definitions:\n\n```ruby\nusage do\n  program \"prog\"\nend\n\nargument :foo, desc: \"Argument description\"\n\nkeyword :bar, desc: \"Keyword description\"\n\noption :baz, desc: \"Option description\"\n\nenv :qux, desc: \"Environment description\"\n```\n\nThe usage banner would print as follows:\n\n```\nUsage: prog [OPTIONS] [ENVIRONMENT] FOO [BAR=BAR]\n```\n\nUse the `:param_display` keyword to change the banner parameter formatting.\n\nThe `:param_display` expects a `Proc` object as a value. The `Proc` accepts\na single argument, a parameter name within a section.\n\nFor example, to lowercase and surround parameters with `\u003c` and `\u003e` brackets:\n\n```ruby\nhelp(param_display: -\u003e(param) { \"\u003c#{param.downcase}\u003e\" })\n```\n\nThis would result in the following usage banner and parameter sections:\n\n```\nUsage: prog [\u003coptions\u003e] [\u003cenvironment\u003e] \u003cfoo\u003e [\u003cbar\u003e=\u003cbar\u003e]\n\nArguments:\n  \u003cfoo\u003e  Argument description\n\nKeywords:\n  \u003cbar\u003e=\u003cbar\u003e  Keyword description\n\nOptions:\n  --baz  Option description\n\nEnvironment:\n  QUX  Environment description\n```\n\n#### 2.9.5 :width\n\nThe help generator wraps content at the width of `80` columns by default.\n\nUse the `:width` keyword to change it, for example, to `120` columns:\n\n```ruby\nhelp(width: 120)\n```\n\nUse the [tty-screen](https://github.com/piotrmurach/tty-screen) gem\nto change the help display based on terminal width.\n\nFor example, to expand the help display to the full width of\nthe terminal window:\n\n```ruby\nhelp(width: TTY::Screen.width)\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\nThen, run `rake spec` to run the tests. You can also run `bin/console`\nfor an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\nTo release a new version, update the version number in `version.rb`, and then\nrun `bundle exec rake release`, which will create a git tag for the version,\npush git commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/piotrmurach/tty-option. This project is intended to be\na safe, welcoming space for collaboration, and contributors are expected\nto adhere to the [code of conduct](https://github.com/piotrmurach/tty-option/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Option project's codebases, issue trackers,\nchat rooms and mailing lists is expected to follow the\n[code of conduct](https://github.com/piotrmurach/tty-option/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2020 Piotr Murach. See LICENSE for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-option","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-option","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-option/lists"}