{"action":"created","issue":{"url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/331","labels_url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/331/labels{/name}","comments_url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/331/comments","events_url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/331/events","html_url":"https://github.com/bpinto/oh-my-fish/pull/331","id":54895633,"number":331,"title":"fish getopts plugin","user":{"login":"bucaran","id":8317250,"avatar_url":"https://avatars.githubusercontent.com/u/8317250?v=3","gravatar_id":"","url":"https://api.github.com/users/bucaran","html_url":"https://github.com/bucaran","followers_url":"https://api.github.com/users/bucaran/followers","following_url":"https://api.github.com/users/bucaran/following{/other_user}","gists_url":"https://api.github.com/users/bucaran/gists{/gist_id}","starred_url":"https://api.github.com/users/bucaran/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bucaran/subscriptions","organizations_url":"https://api.github.com/users/bucaran/orgs","repos_url":"https://api.github.com/users/bucaran/repos","events_url":"https://api.github.com/users/bucaran/events{/privacy}","received_events_url":"https://api.github.com/users/bucaran/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":9,"created_at":"2015-01-20T15:24:13Z","updated_at":"2015-01-20T18:34:03Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/bpinto/oh-my-fish/pulls/331","html_url":"https://github.com/bpinto/oh-my-fish/pull/331","diff_url":"https://github.com/bpinto/oh-my-fish/pull/331.diff","patch_url":"https://github.com/bpinto/oh-my-fish/pull/331.patch"},"body":"## _getopts_ plugin\r\n> a friendly [`getopts`](http://en.wikipedia.org/wiki/Getopts) for [fish](https://fishshell.com) :fish:\r\n\r\n## Tests\r\n\r\nTests are implemented via [Oh-My-Fish](https://github.com/bpinto/oh-my-fish) spec runner _fish-spec_.\r\n\r\n## Premise\r\nEvery utility / function needs to handle arguments. What usually happens is that every function does all the grunt work to parse `$argv` itself, and while some patterns do tend to recur, it's different almost every time. Enter fish `getopts`.\r\n\r\n## Synopsis\r\n  `getopts <option string> [ARGV...]`\r\n\r\n## Options\r\n#### `<option string> [:][<letter>:][<word>[:[^]]]`\r\n\r\nA string containing the option characters recognized by the utility calling `getopts`. If a `<letter>` or `<word>` ends in `:`, the option is expected to have an argument, which may be supplied separately or next to the option without spaces in the same string.\r\n\r\nTo indicate long options: `<letter>:<word>` and `<word>` are both valid option strings that will attempt to match `-<letter>` and `--<word>`.\r\n\r\nTo indicate optional arguments, use a `^` character after a `:` at the end of the option in the option string. For example `<letter>:^` and `<letter>:<word>:^` are both valid. Optional arguments should be supplied in the same string as the option and without spaces, e.g, `-<letter>value` will correctly assign `value` as the argument to the the option `<letter>`, but `-<letter>` value, will parse `value` as the next argument in `<ARGV>`.\r\n\r\nTo specify optional arguments using the option's long form, use a `=` character after the option: `--<word>=value`.\r\n\r\nUse a `:` at the beginning of the option string to enable strict mode. If enabled, `getopts` will exit with a status __> 0__ if or when an unknown option is found. See _DIAGNOSTICS_.\r\n\r\n#### `<ARGV>`\r\n\r\nList of options and operands to parse. `getopts` prints any matched options as well as available argument separated by a \\n to stdout and returns with a status of __0__ if there are still arguments; else returns with a status __> 0__ if the end of the options is reached or an error occurs. See _DIAGNOSTICS_.\r\n\r\n## Description\r\n`getopts` obtains options and their arguments from a list of parameters that, as indicated by <option string>, are single letters preceded by a `-` or words preceded by `--` and possibly followed by an argument value.\r\n\r\nfish `getopts` follows the specifications described in the [Utility Syntax Guidelines](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html). The following is a summary of the features:\r\n\r\n+ Short options; single letters preceded by `-`, and long options; words preceded by `--`, are both supported.\r\n\r\n+ Single letters may be grouped. `-abc` → `-a -b -c`\r\n\r\n+ Options required to take an argument can specify the argument either in the same string as the option or separated from the by a space. (1) `-a argument`, (2) `-aargument`\r\n\r\n+ Options that can take an argument optionally shall specify the argument in the same string as the option argument if in short option style: `-aargument`, or separated by a `=` if in long form: `--long-form=argument`. If a blank space is used, the following argument will be treated independently.\r\n\r\n+ Options can appear multiple times in the same argument list. `getopts` will print every match sequentally on each call, and should default to the short form of the option if available.\r\n\r\n+ The option delimiter `:` and optional argument character `^` shall not be used as an option.\r\n\r\n+ `getopts` will return the remaining operands when the end of the options is reached, i.e, a `--` argument that is not an option is found, or an argument that does not begin with `-` is found.\r\n\r\n## Environment Variables\r\nThe following environment variables are used internally by `getopts`. These variables are erased from memory when the functions returns 1.\r\n\r\n+ `__getopts_optstr` _Whitespace trimmed option string._\r\n\r\n+ `__getopts_argv` _Preprocessed copy of arguments._\r\n\r\n+ `__getopts_index` _Index of the next argument to handle._\r\n\r\n+ `__getopts_required` _List of options with required arguments._\r\n\r\n+ `__getopts_optional` _List of options with optional arguments._\r\n\r\n## Diagnostics\r\nPossible exit status values are:\r\n\r\n+ __0__: An argument formed like an option was found. This causes getopts to print the option short-style and its argument if avaiable. If strict-mode is enabled setting the first character of the option to `:`, an unknown option will cause `getopts` to fail. See below.\r\n\r\n+ __1__: The end of the options is reached. Also sends remaining operands to stdout.\r\n\r\n+ __2__: An option argument was missing.\r\n\r\n+ __3__: An unknown option was found. Only if strict-mode is enabled.\r\n\r\n## Examples\r\n```fish\r\n  function my_utility\r\n    while set optarg (getopts \"l:long x: o:optional:^\" $argv)\r\n      switch $optarg[1]\r\n        case l\r\n          echo handle `-l --long`\r\n        case x\r\n          echo handle `-x` w/ argument `$optarg[2]`\r\n        case o\r\n          echo handle `-o --optional` w/ optional argument `$optarg[2]`\r\n        case \\*\r\n          echo unknown option `$optarg[1]`\r\n      end\r\n    end\r\n    echo -n operands: \"`$optarg`\"\r\n  end\r\n```\r\n\r\n## Links\r\n+ [UNIX Utility Conventions](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html)\r\n   \r\n## License\r\n[MIT](http://opensource.org/licenses/MIT) © [Jorge Bucaran](http://bucaran.me)\r\n"},"comment":{"url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/comments/70706451","html_url":"https://github.com/bpinto/oh-my-fish/pull/331#issuecomment-70706451","issue_url":"https://api.github.com/repos/bpinto/oh-my-fish/issues/331","id":70706451,"user":{"login":"bucaran","id":8317250,"avatar_url":"https://avatars.githubusercontent.com/u/8317250?v=3","gravatar_id":"","url":"https://api.github.com/users/bucaran","html_url":"https://github.com/bucaran","followers_url":"https://api.github.com/users/bucaran/followers","following_url":"https://api.github.com/users/bucaran/following{/other_user}","gists_url":"https://api.github.com/users/bucaran/gists{/gist_id}","starred_url":"https://api.github.com/users/bucaran/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bucaran/subscriptions","organizations_url":"https://api.github.com/users/bucaran/orgs","repos_url":"https://api.github.com/users/bucaran/repos","events_url":"https://api.github.com/users/bucaran/events{/privacy}","received_events_url":"https://api.github.com/users/bucaran/received_events","type":"User","site_admin":false},"created_at":"2015-01-20T18:34:03Z","updated_at":"2015-01-20T18:34:03Z","body":"[Looking at the travis build for 145](https://travis-ci.org/bpinto/oh-my-fish/builds/47682700)\r\n```\r\n$ git clone --depth=50 git://github.com/bpinto/oh-my-fish.git bpinto/oh-my-fish\r\nCloning into 'bpinto/oh-my-fish'...\r\n```\r\nWhy?"}}