Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ARGPARSE(1)			  fish-shell			   ARGPARSE(1)

NAME
       argparse	- parse	options	passed to a fish script	or function

SYNOPSIS
	  argparse [OPTIONS] OPTION_SPEC... -- [ARG...]

DESCRIPTION
       This command makes it easy for fish scripts and functions to handle ar-
       guments like how	fish builtin commands handle their arguments. You pass
       arguments that define the known options,	followed by a literal --, then
       the arguments to	be parsed (which might also  include  a	 literal  --).
       argparse	 then sets variables to	indicate the passed options with their
       values, and sets	$argv (and always $argv) to the	 remaining  arguments.
       More on this in the usage section below.

       Each  option  specification (OPTION_SPEC) is written in the domain spe-
       cific language described	below. All OPTION_SPECs	must appear after  any
       argparse	flags and before the --	that separates them from the arguments
       to be parsed.

       Each option that	is seen	in the ARG list	will result in a var  name  of
       the  form  _flag_X,  where X is the short flag letter and the long flag
       name. The OPTION_SPEC always requires a short flag even if it can't  be
       used. So	there will always be _flag_X var set using the short flag let-
       ter if the corresponding	short or long flag is seen. The	long flag name
       var  (e.g.,  _flag_help)	 will  only  be	defined, obviously, if the OP-
       TION_SPEC includes a long flag name.

       For example _flag_h and _flag_help if -h	or --help  is  seen.  The  var
       will  be	 set  with local scope (i.e., as if the	script had done	set -l
       _flag_X). If the	flag is	a boolean (that	is, it just is passed or  not,
       it  doesn't have	a value) the values are	the short and long flags seen.
       If the option is	not a boolean the values will be zero or  more	values
       corresponding  to  the values collected when the	ARG list is processed.
       If the flag was not seen	the flag var will not be set.

OPTIONS
       The following argparse options are available. They must	appear	before
       all OPTION_SPECs:

       o -n  or	 --name	 is the	command	name for use in	error messages.	By de-
	 fault the current function name will be used, or argparse if run out-
	 side of a function.

       o -x  or	 --exclusive  should  be followed by a comma separated list of
	 short or long options that are	mutually exclusive. You	can  use  this
	 more than once	to define multiple sets	of mutually exclusive options.

       o -N  or	 --min-args is followed	by an integer that defines the minimum
	 number	of acceptable non-option arguments. The	default	is zero.

       o -X or --max-args is followed by an integer that defines  the  maximum
	 number	of acceptable non-option arguments. The	default	is infinity.

       o -i  or	 --ignore-unknown  ignores  unknown  options, keeping them and
	 their arguments in $argv instead.

       o -s or --stop-nonopt causes scanning the arguments to stop as soon  as
	 the  first  non-option	 argument is seen. Among other things, this is
	 useful	to implement subcommands that have their own options.

       o -h or --help displays help about using	this command.

USAGE
       Using this command requires first passing  option  specifications  (OP-
       TION_SPEC  below), then a mandatory --, and then	the arguments you want
       to have parsed. More about this below but here is a simple example that
       might be	used in	a function named my_function:

	  argparse --name=my_function 'h/help' 'n/name=' -- $argv
	  or return

       If  $argv  is empty then	there is nothing to parse and argparse returns
       zero to indicate	success. If $argv is not empty then it is checked  for
       flags  -h,  --help,  -n	and --name. If they are	found they are removed
       from the	arguments and local variables are set so the script can	deter-
       mine  which  options were seen. Assuming	$argv doesn't have any errors,
       such as a missing mandatory value for an	option,	 then  argparse	 exits
       with  status  zero.  Otherwise  it writes appropriate error messages to
       stderr and exits	with a status of one.

       The -- argument is required. You	do not have to include	any  arguments
       after  the -- but you must include the --. For example, this is accept-
       able:

	  set -l argv
	  argparse 'h/help' 'n/name' --	$argv

       But this	is not:

	  set -l argv
	  argparse 'h/help' 'n/name' $argv

       The first -- seen is what allows	the argparse command to	reliably sepa-
       rate the	option specifications from the command arguments.

OPTION SPECIFICATIONS
       Each option specification is a string composed of

       o A  short flag letter (which is	mandatory). It must be an alphanumeric
	 or "#". The "#" character is special and means	that  a	 flag  of  the
	 form -123 is valid. The short flag "#"	must be	followed by "-"	(since
	 the short name	isn't otherwise	valid since _flag_# is not a valid var
	 name) and must	be followed by a long flag name	with no	modifiers.

       o A  /  if  the short flag can be used by someone invoking your command
	 else -	if it should not be exposed as a valid short flag. If there is
	 no  long  flag	 name these characters should be omitted. You can also
	 specify a '#' to indicate the short and long flag names can  be  used
	 and  the  value  can be specified as an implicit int; i.e., a flag of
	 the form -NNN.

       o A long	flag name which	is optional. If	 not  present  then  only  the
	 short flag letter can be used.

       o Nothing  if the flag is a boolean that	takes no argument or is	an im-
	 plicit	int flag, else

       o = if it requires a value and only the last instance of	 the  flag  is
	 saved,	else

       o =?  it	takes an optional value	and only the last instance of the flag
	 is saved, else

       o =+ if it requires a value and each instance of	the flag is saved.

       o Optionally a !	followed by fish script	to validate the	 value.	 Typi-
	 cally	this will be a function	to run.	If the exit status is zero the
	 value for the flag is valid. If non-zero the value  is	 invalid.  Any
	 error messages	should be written to stdout (not stderr). See the sec-
	 tion on Flag Value Validation for more	information.

       See the fish_opt	command	for a friendlier but more verbose way to  cre-
       ate option specifications.

       In  the following examples if a flag is not seen	when parsing the argu-
       ments then the corresponding _flag_X var(s) will	not be set.

FLAG VALUE VALIDATION
       Sometimes you need to validate the option values. For example, that  it
       is  a valid integer within a specific range, or an ip address, or some-
       thing entirely different. You can always	do this	after argparse returns
       but  you	 can also request that argparse	perform	the validation by exe-
       cuting arbitrary	fish script. To	do so simply  append  an  !  (exclama-
       tion-mark)  then	 the fish script to be run. When that code is executed
       three vars will be defined:

       o _argparse_cmd will be set to the value	of the value of	 the  argparse
	 --name	value.

       o _flag_name  will  be  set  to	the short or long flag that being pro-
	 cessed.

       o _flag_value will be set to the	value associated with the  flag	 being
	 processed.

       If  you	do  this  via  a  function  it	should	be  defined  with  the
       --no-scope-shadowing flag. Otherwise it	won't  have  access  to	 those
       variables.

       The  script  should  write any error messages to	stdout,	not stderr. It
       should return a status of zero if the flag value	is valid  otherwise  a
       non-zero	status to indicate it is invalid.

       Fish ships with a _validate_int function	that accepts a --min and --max
       flag. Let's say your command accepts a -m or --max flag and the minimum
       allowable  value	is zero	and the	maximum	is 5. You would	define the op-
       tion like this: m/max=!_validate_int --min 0 --max 5.  The  default  if
       you just	call _validate_int without those flags is to simply check that
       the value is a valid integer with no limits on the min or max value al-
       lowed.

EXAMPLE	OPTION_SPECS
       Some OPTION_SPEC	examples:

       o h/help	means that both	-h and --help are valid. The flag is a boolean
	 and can be used more than once. If either flag	is used	 then  _flag_h
	 and _flag_help	will be	set to the count of how	many times either flag
	 was seen.

       o h-help	means that only	--help is valid. The flag is a boolean and can
	 be  used  more	 than  once. If	the long flag is used then _flag_h and
	 _flag_help will be set	to the count of	how many times the  long  flag
	 was seen.

       o n/name=  means	that both -n and --name	are valid. It requires a value
	 and can be used at most once. If the flag is seen  then  _flag_n  and
	 _flag_name  will  be  set  with the single mandatory value associated
	 with the flag.

       o n/name=? means	that both -n and --name	are valid. It accepts  an  op-
	 tional	 value	and can	be used	at most	once. If the flag is seen then
	 _flag_n and _flag_name	will be	set with the value associated with the
	 flag if one was provided else it will be set with no values.

       o n-name=+ means	that only --name is valid. It requires a value and can
	 be used more than  once.  If  the  flag  is  seen  then  _flag_n  and
	 _flag_name  will  be  set with	the values associated with each	occur-
	 rence of the flag.

       o x means that only -x is valid.	It is a	boolean	that can be used  more
	 than once. If it is seen then _flag_x will be set to the count	of how
	 many times the	flag was seen.

       o x=, x=?, and x=+ are similar to the n/name examples above  but	 there
	 is no long flag alternative to	the short flag -x.

       o x-  is	 not  valid since there	is no long flag	name and therefore the
	 short flag, -x, has to	be usable.

       o #-max means that flags	matching the regex "^--?d+$" are  valid.  When
	 seen  they  are  assigned  to the variable _flag_max. This allows any
	 valid positive	or negative integer to be specified  by	 prefixing  it
	 with a	single "-". Many commands support this idiom. For example head
	 -3 /a/file to emit only the first three lines of /a/file.

       o n#max means that flags	matching the regex "^--?d+$" are  valid.  When
	 seen  they  are assigned to the variables _flag_n and _flag_max. This
	 allows	any valid positive or negative integer to be specified by pre-
	 fixing	 it  with  a single "-". Many commands support this idiom. For
	 example head -3 /a/file  to  emit  only  the  first  three  lines  of
	 /a/file.  You can also	specify	the value using	either flag: -n	NNN or
	 --max NNN in this example.

       After parsing the arguments the argv var	is set with local scope	to any
       values  not  already  consumed during flag processing. If there are not
       unbound values the var is set but count $argv will be zero.

       If an error occurs during argparse  processing  it  will	 exit  with  a
       non-zero	status and print error messages	to stderr.

COPYRIGHT
       2019, fish-shell	developers

3.1				 Aug 11, 2020			   ARGPARSE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | OPTION SPECIFICATIONS | FLAG VALUE VALIDATION | EXAMPLE OPTION_SPECS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=argparse&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help