github-mirror/oh-my-fish
2
0
Fork 0
mirror of https://github.com/oh-my-fish/oh-my-fish.git synced 2024-11-23 23:13:45 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

[split] Move getopts plugin to oh-my-fish/plugin-getopts

Browse Source 
https://github.com/oh-my-fish/plugin-getopts
This commit is contained in:
Justin Hileman 2015-05-31 08:30:48 -07:00
parent 978d946c22
commit 00323c3948
3 changed files with 0 additions and 669 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
plugins/getopts/README.md
View File

@ -1,110 +0,0 @@
# getopts
> friendly [`getopts`](http://en.wikipedia.org/wiki/Getopts) for [fish](https://fishshell.com) :fish:
## Usage
```fish
Add `getopts` to your `$fish_plugins` or import directly into your library via `import plugins/getopts`.
```
## Premise
Every 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`.
## Synopsis
`getopts <option string> [ARGV...]`
## Options
#### `<option string> [:][<letter>][[:]<word>[:[^]]]`
A 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.
To indicate long options: `<letter>:<word>` and `<word>` are both valid option strings that will attempt to match `-<letter>` and `--<word>`.
To indicate _only_ short options, do not specify a `:<word>` after `<letter>`. For example, `a b` will match `-a` or `-b`.
To 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>`.
To specify optional arguments using the option's long form, use a `=` character after the option: `--<word>=value`.
Use 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](#diagnostics).
#### `<ARGV>`
List 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](#diagnostics).
#### Summary
| Option String | Argument | Short Style | Long Style |
|:---------------:|:--------------:|------------------|:--------------------:|
`"q:qqq:"` | Required | `-q1` `-q 1` | `--qqq 1` |
`"q:qqq:^"` | Optional | `-q1` | `--qqq=3` |
## Description
`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.
fish `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:
+ Short options; single letters preceded by `-`, and long options; words preceded by `--`, are both supported.
+ Single letters may be grouped. `-abc` → `-a -b -c`
+ 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`
+ 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.
+ 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.
+ The option delimiter `:` and optional argument character `^` shall not be used as an option.
+ `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.
## Environment Variables
The following environment variables are used internally by `getopts`. These variables are erased from memory when the function returns 1.
+ `__getopts_optstr` _Whitespace trimmed option string._
+ `__getopts_argv` _Preprocessed copy of arguments._
+ `__getopts_index` _Index of the next argument to handle._
+ `__getopts_required` _List of options with required arguments._
+ `__getopts_optional` _List of options with optional arguments._
## <a name="diagnostics"></a>Diagnostics
Possible exit status values are:
+ __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.
+ __1__: The end of the options was reached. Remaining operands are also sent to stdout.
+ __2__: An option argument was missing.
+ __3__: An unknown option was found. Only if strict-mode is enabled.
## Examples
```fish
function my_utility
while set optarg (getopts "l:long x: o:optional:^" $argv)
switch $optarg[1]
case l
echo handle `-l --long`
case x
echo handle `-x` w/ argument `$optarg[2]`
case o
echo handle `-o --optional` w/ optional argument `$optarg[2]`
case \*
echo unknown option `$optarg[1]`
end
end
echo -n operands: "`$optarg`"
end
```
## Links
+ [UNIX Utility Conventions](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html)
## License
[MIT](http://opensource.org/licenses/MIT) © [Jorge Bucaran](http://bucaran.me)

409
plugins/getopts/getopts.fish
View File

@ -1,409 +0,0 @@
# NAME
# getopts -- getopts for fish
#
# SYNOPSIS
# getopts <option string> [ARGV...]
#
# OPTIONS
# <option string> [:][<letter>][[:]<word>[:[^]]]
#
# A 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.
#
# To indicate long options: <letter>:<word> and <word> are both valid
# option strings that will attempt to match -<letter> and --<word>.
#
# For only short options, do not specify a :<word> after <letter>.
# For example, `a b` will match `-a` and/or `-b`.
#
# To 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>.
#
# To specify optional arguments using the option's long form, use a
# `=` character after the option: --<word>=value.
#
# Use 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.
#
# <ARGV>
#
# List 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.
#
# DESCRIPTION
# 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.
#
# fish getopts follows the specifications described in the Utility Syntax
# Guidelines (see LINKS); the following is a summary of the features:
#
# + Short options; single letters preceded by -, and long options;
# words preceded by --, are both supported.
#
# + Single letters may be grouped. -abc → -a -b -c
#
# + 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
#
# + 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.
#
# + 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.
#
# + The option delimiter `:` and optional argument character `^`
# shall not be used as an option.
#
# + 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.
#
# ENVIRONMENT VARIABLES
# The following environment variables are used internally by getopts.
# These variables are erased from memory when the functions returns 1.
#
# + __getopts_optstr Whitespace trimmed option string.
# + __getopts_argv Preprocessed copy of arguments.
# + __getopts_index Index of the next argument to handle.
# + __getopts_required List of options with required arguments.
# + __getopts_optional List of options with optional arguments.
#
# DIAGNOSTICS
# Possible exit status values are:
#
# 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.
#
# 1 The end of the options was reached. Remaining operands are also
# sent to stdout.
#
# 2 An option argument was missing.
#
# 3 An unknown option was found. Only if strict-mode is enabled.
#
# EXAMPLES
# function my_utility
# while set optarg (getopts "l:long x: o:optional:^" $argv)
# switch $optarg[1]
# case l
# echo handle `-l --long`
# case x
# echo handle `-x` w/ argument `$optarg[2]`
# case o
# echo handle `-o --optional` w/ optional argument `$optarg[2]`
# case \*
# echo unknown option `$optarg[1]`
# end
# end
# echo -n operands: "`$optarg`"
# end
#
# LINKS
# UNIX Utility Conventions
# → http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html
#
# AUTHORS
# Jorge Bucaran <jbucaran@me.com>
#/
function getopts
# Currently supported return success/error conditions.
set -l __CONTINUE 0
set -l __END_OF_OPTIONS 1
set -l __OPTION_ARGUMENT_EXPECTED 2
set -l __UNKNOWN_OPTION_FOUND 3
# Self-destroying global variable cleanup utility.
# Should be called before returning 1.
function __getopts_cleanup
set -e __getopts_optstr
set -e __getopts_argv
set -e __getopts_index
set -e __getopts_required
set -e __getopts_optional
set -e __getopts_strict_mode
functions -e __getopts_increase_index
end
function __getopts_increase_index
set __getopts_index (math $__getopts_index + 1)
end
# Options string pre-processing.
if not set -q __getopts_optstr
set -g __getopts_optstr $argv[1]
set -e argv[1]
# Trim option string and collect required / optional options.
if [ -n "$__getopts_optstr" ]
set __getopts_optstr (printf $__getopts_optstr | tr -s '[:space:]' \n)
# Setting the first token of the option string to `:` enables
# strict mode. This causes getopts to abort the process if an
# unknown option is found.
set -l first_token (printf $__getopts_optstr | head -c1)
if [ : = "$first_token" ]
set -g __getopts_strict_mode --true
# We can safely remove the `:` character now.
set __getopts_optstr[1] (printf $__getopts_optstr[1] | cut -c2-)
end
# Collect options with optional and required option-arguments.
function __getopts_collect_optargs
for string in (printf "%s\n" $__getopts_optstr)
set -l token (printf $string | tail -c1)
set -l split_string (printf "%s\n" $string | tr : \n)
# Erase last to make sure not to append `^` token.
switch $token
case :
set -g __getopts_required $__getopts_required $split_string
set -e __getopts_required[-1]
case \^
set -g __getopts_optional $__getopts_optional $split_string
set -e __getopts_optional[-1]
end
end
functions -e __getopts_collect_optargs
end
__getopts_collect_optargs
end
end
# Sanitize arguments. Break up flags: -abc → -a -b -c, but skip optional
# arguments. If -w is a flag that can take an optional argument, -abw123
# should be parsed to → -a -b -w 123.
if not set -q __getopts_argv
function __getopts_sanitize_argv
for token in $argv
switch $token
case --\* # Skip!
case -\*
# Split each token into single characters with `.`
for char in (printf "%s" $token | cut -c2- | grep --only-matching .)
# Do not split short option characters if this option can
# take optional required arguments.
if [ -z "$suspend_break" ]
printf "-%s\n" $char
else
printf "%s" $char
end
# Suspend option break-up if the current option is either
# a required or an optional option type.
contains -- $char $__getopts_required $__getopts_optional
and set suspend_break --true
set last_char $char
end
# Break options if we were in suspend mode and reset flag.
# This makes sure to add a blank space if no argument was
# specified for the optional option-argument, but not for
# the required option-argument.
if [ -n "$suspend_break" ]
not contains -- $last_char $__getopts_required
and printf "\n"
set suspend_break ""
end
continue
end
printf "%s\n" $token
end
functions -e __getopts_sanitize_argv
end
set -g __getopts_argv (__getopts_sanitize_argv $argv)
end
# Always use our preprocessed argument list.
set argv $__getopts_argv
if not set -q __getopts_index
set -g __getopts_index 1
end
# Handle next argument as indicated by the current index.
if set -q argv[$__getopts_index]
set -l option $argv[$__getopts_index]
# Potential matches for $option are: (1) end of arguments `--`,
# (2) long/short options --* or -* or (3) begin of operands, if
# (1) and (2) fail.
switch $option
# End of arguments. Assume everything from this point are operands.
case --
set -e argv[1..$__getopts_index]
printf "%s\n" $argv
__getopts_cleanup
return $__END_OF_OPTIONS
# Looks like we have a well-formed long/short option. Parse.
case --\* -\*
# It will be useful later to know if the current option is in long
# style. Notice we add a leading blank, because cut fails when the
# first character is a dash `-`.
set -e is_long_option
test (printf " "$option | cut -c2-3) = "--"
and set -l is_long_option
# Trim leading dashes and prepare to match with valid options.
set option (printf "%s" $option | sed 's/^-*//g')
for substring in $__getopts_optstr
# Split up by token separator `:`. The resulting list contains
# all valid options, both in short and long style.
set -l tokens (printf $substring | tr : \n)
# Start last to first to avoid mistaking long w/ short options.
for index in (seq (count $tokens) -1 1)
set -l last_token (printf $substring | tail -c1)
# Find options with optional argument in long-style and
# try to split by required delimiter `=`
# Note: Optional values shall be separated from options in
# long style by an equals sign. See documentation.
if [ $last_token = \^ ]
if set -q is_long_option
set -l option_value (printf "%s" $option | tr = \n)
if set -q option_value[2]
# Check if it is a valid option match.
if [ $option_value[1] = $tokens[$index] ]
printf "%s\n" $tokens[1]
printf $option_value[2]
__getopts_increase_index
return $__CONTINUE
end
end
end
end
# We are already inside a possible short/long option match.
# Option is the argument in __getopts_argv[__getopts_index]
# The following compares option against each valid argument
# in the option string __getopts_optstr. If no match can be
# found, print the argument after the loop.
switch $option
case $tokens[$index]
# Success. Send first token to stdout to make sure short
# options, if available, always get the highest priority.
printf "%s\n" $tokens[1]
switch $last_token
# At this point, both required and optional arguments
# look the same to the parser, so we match last_token
# to either `:` required or `^` optional tokens. This
# is the result of preprocessing __getopts_argv.
case : \^
# Find options with optional argument in long-style.
if [ $last_token = \^ ]
if set -q is_long_option
# An optional argument in long-style here means it
# didn't split by = in previous checks, so we can
# handle it as a missing argument option and exit.
# Print any non-empty list character.
printf "\n"
__getopts_increase_index
return $__CONTINUE
end
end
# If we reach this, we are either handling a required
# option or an optional in short-style form. Both are
# seen by the parser the same after preprocessing.
# For example:
# Given the option string `a b:^`, -abX → -a -b X
# We need to peek at the next option
__getopts_increase_index
# Check if next argument exists.
if set -q argv[$__getopts_index]
# Sanitize the option-argument.
set -l value (printf "%s" $argv[$__getopts_index])
if [ -z "$value" ]
# Print any non-empty list character.
printf "\n"
else
printf $value
end
__getopts_increase_index
return $__CONTINUE
else
__getopts_cleanup
return $__OPTION_ARGUMENT_EXPECTED
end
# Option was a flag that takes no arguments.
case \*
__getopts_increase_index
return $__CONTINUE
end
end
end
end
# No match found. Print unknown option to stdout first, and
# if strict mode is enabled, abort, else continue.
printf $option
__getopts_increase_index
# If the first character of the option string is a `:`, this
# enables strict mode and any unknown options will cause the
# process to return > 0.
if set -q __getopts_strict_mode
__getopts_cleanup
return $__UNKNOWN_OPTION_FOUND
else
return $__CONTINUE
end
# Looks like we run out of options. Print operands return.
case \*
if [ $__getopts_index -gt 1 ]
# Sans the current index, get rid of everything up to here.
set -e argv[1..(math $__getopts_index-1)]
end
printf "%s\n" $argv
__getopts_cleanup
return $__END_OF_OPTIONS
end
else
# End of arguments, cleanup and exit.
__getopts_cleanup
return $__END_OF_OPTIONS
end
end

150
plugins/getopts/getopts.spec.fish
View File

@ -1,150 +0,0 @@
import plugins/fish-spec
import plugins/getopts
function describe_getotps -d "fish getopts"
function __getopts
set -l options $argv[1]
set -e argv[1]
while set option (getopts $options $argv)
if [ (count $option) -gt 1 ] # w/ argument
set result "$result$option[1]($option[2])"
else
set result "$result$option"
end
end
printf "$result$option"
end
function it_returns_1_if_empty
getopts
expect $status --to-equal 1
end
function it_handles_a_single_short_option
expect (__getopts "a" -a) --to-equal a
end
function it_handles_a_single_long_option
expect (__getopts "aa" --aa) --to-equal aa
end
function it_handles_short_options
set -l options "a b c x y z"
set -l expected abcxyz
expect (__getopts $options -abc -xyz) --to-equal $expected
and expect (__getopts $options -a -b -c -x -y -z) --to-equal $expected
end
function it_handles_long_options
expect (__getopts "x-rays ye zombie" --ye --zombie --x-rays) \
--to-equal yezombiex-rays
end
function it_handles_long_options_only
expect (__getopts "all blink crunch" --all --blink --crunch) \
--to-equal allblinkcrunch
end
function it_handles_all_options
expect (__getopts "g:get p:put u:update d:delete t:post" -tud --put --get) \
--to-equal tudpg
end
function it_handles_operands
expect (__getopts "" 1 2 3 4 5) --to-equal "1 2 3 4 5"
end
function it_handles_options_and_operands
expect (__getopts "g:get p:put u:update d:delete t:post" \
-ud --put --get --post url1 url2 user:password) \
--to-equal "udpgturl1 url2 user:password"
end
function it_handles_end_of_args_separator
expect (__getopts "a b c d" -abcd -- -x -y -z) --to-equal "abcd-x -y -z"
end
function it_detects_end_of_args
expect (__getopts "a b c" -abc 1 2 3 -x) --to-equal "abc1 2 3 -x"
end
function it_returns_unknown_option_error_on_strict_mode
while set option (getopts ":a b c d e f" -abcXdef 1 2 3)
set result "$result$option"
end
expect $status --to-equal 3
end
function it_handles_valid_options_while_on_strict_mode
while set option (getopts ":a b c d e f" -fed -cba 1 2 3)
set result "$result$option"
end
expect "$result" --to-equal fedcba
and expect "$option" --to-equal "1 2 3"
end
function it_returns_argument_missing_error_if_argument_is_missing
while set option (getopts "x y z:" -xy -z)
end
expect $status --to-equal 2
end
function it_handles_options_normally_until_an_error_is_found
while set option (getopts ":a b c d e f" -abcXdef 1 2 3)
set result "$result$option"
end
expect "$result" --to-equal abc
expect "$option" --to-equal X
end
function it_handles_short_options_separated_by_blanks
expect (__getopts "a: b: c:" -a '1st arg' -b '2nd arg' -c '3rd arg') \
--to-equal "a(1st arg)b(2nd arg)c(3rd arg)"
end
function it_handles_a_short_option_w_required_argument_without_space_separation
expect (__getopts "a: b:" -adarwin -blinux) --to-equal "a(darwin)b(linux)"
end
function it_handles_a_short_option_w_optional_argument_with_space_separation
expect (__getopts "a: b:^" -a darwin -b linux) --to-equal "a(darwin)b()linux"
end
function it_handles_options_w_argument
set -l url "http://github.com"
set -l expected "pg($url)"
set -l options "g:get: p:put"
expect (__getopts $options -pg$url) --to-equal $expected
and expect (__getopts $options -p --get $url) --to-equal $expected
end
function it_handles_options_w_optional_argument
set -l url "http://github.com"
set -l expected "pg($url)"
set -l options "g:get:^ p:put"
expect (__getopts $options -pg$url) --to-equal $expected
and expect (__getopts $options -p --get=$url) --to-equal $expected
and expect (__getopts $options -pg) --to-equal "pg()"
end
function it_handles_a_contrived_example
set -l options "A b c: x y z: long long-req: long-opt:^"
set -l args -xyz777 -Abc100 --long --long-req 32 --long-opt=!!! D O N E
expect (__getopts $options $args) --to-equal \
"xyz(777)Abc(100)longlong-req(32)long-opt(!!!)D O N E"
end
function it_handles_multiline_option_strings
set -l multiline_options "a:aaa
b:bbb
c:ccc
d:ddd"
expect (__getopts $multiline_options -dcbabcd) --to-equal "dcbabcd"
end
end
spec.run $argv