Template writing guide¶
This section tells you how to write templates, the next one is about argbash
script invocation.
Definitions¶
Positional and optional arguments¶
There are two major types of arguments — take an example:
ls -l --sort time /home
- Optional arguments are
-l
and--sort
, while we have only one - positional argument —
/home
.
Here, the argument -l
is optional of a boolean type (it is either on or off), --sort
is also optional, taking exactly one value (in this case time
).
-l
and --sort
are called options, hence the name optional arguments.
The common pattern is that optional arguments are not required, being there just in the case you need them.
The /home
argument is a positional one.
In case of ls
, the positional argument has a default — running ls
without parameters is the same as running ls "."
.
ls
itself accepts an arbitrary number of positional arguments and it treats them all in the same way.
On the other hand, the grep
command requires at least one positional argument.
The first one is supposed to be the regular expression you want to match against, and the other ones correspond to filenames, so they are not treated the same.
The first positional argument grep
accepts (i.e. the regular expression), doesn’t have a default, whereas the second one normally defaults to -
, which means grep
will try to read input from stdin
.
Option, Value, and others¶
We have positional and optional arguments sorted out, so let’s define some other terms now keeping the example of ls -l --sort time /home
:
Option (also
flag
orswitch
): The string that identifies optional arguments on the command-line, can have a short (dash and a character, e.g.-l
,-?
) or long (double dash and string, e.g.--sort
) form. POSIX conventions mention only short options, whereas the GNU conventions mention long options.Value: In connection with optional arguments, value of an argument is the string that follows it (provided that the argument expects a value to be given). Concerning positional arguments, it is simply the string on the command-line (whose location matches the location in which we expect the given positional argument). So in our example, the values are
time
andhome
.Name: Both positional and optional arguments have a name. In case of optional argument, the name is what appears after the long option’s the double dash, e.g. name of
--project-path
isproject-path
. The argument’s name is used in help and later in your script when you access argument’s value. Names of positional arguments are much less visible to the script’s user — one can see them only in the help message.Argument: An argument is the high-level concept. On command-line, arguments are identified by options (which themselves may or may be not followed by values). Although this is confusing, it is a common way of putting it. In our example, we have
-l
— this argument has only the option, but never accepts values.--sort
— this argument accepts exactly one value (in this case, the stringtime
). If you don’t provide a value, you will get an error.
Argbash
exposes values of passed arguments as environmental variables.Default: In case of positional and boolean arguments, you may specify their default values.
Note
General notice: There is no way of how to find out whether an argument was passed or not just by looking at the value of the corresponding environmental variable in the script.
bash
doesn’t distinguish between empty variables and variables containing an empty string. Also note that it is perfectly possible to pass an empty string as an argument value.
So let’s get back to argument types.
Below, is a list of argument types and macros that you have to write to support those (e.g. ARGBASH_GO
is a macro and ARG_OPTIONAL_BOOLEAN([verbose], [Verbose mode])
is a macro called with two arguments — verbose
and Verbose mode
).
Place those macros in your files as bash
comments.
Your script¶
You have to decide what arguments should your script support.
As of this version, Argbash
lets you choose from:
- Single-value positional arguments (with optional defaults),
- single-value optional arguments,
- boolean optional arguments,
- action optional arguments (i.e. the
--version
and--help
type of args) and - incremental arguments that “remember” how many times they have been repeated (e.g.
--verbose
) and - repeatable arguments that sequentially store their values into an array (e.g.
-I
).
Plus, there are convenience macros that don’t relate to argument parsing, but they might help you to write better scripts and a helper that enables you to easily wrap other Argbash
-aware scripts without fuss.
Take a look at the API and place the declarations either to your script or in a separate file.
Let yourself be inspired by the resources/examples/simple.m4
example (bash
syntax highlighting is recommended, despite the extension).
Then, run the following command to your file:
bin/argbash myfile.m4 -o myfile.sh
to either get a script that should just work, or a file that you include in your script.
Argbash API¶
Put macro parameters in square brackets. Parameters marked as optional can be left out blank.
The following code leaves second and last parameters blank.
Values of first and third parameters are verbose
and Turn on verbose mode
respectively.
ARG_OPTIONAL_BOOLEAN([verbose], , [Turn on verbose mode], )
Positional arguments¶
Single-value positional argument (with optional default):
ARG_POSITIONAL_SINGLE([argument-name], [help message (optional)], [default (optional)])
The argument is mandatory, unless you specify a default.
If you leave the default blank, it is understood that you don’t want one (and that the argument is mandatory). If you really want to have an explicit default of empty string, pass a quoted empty string (i.e.
""
or''
).Multi-value positional argument (with optional defaults):
ARG_POSITIONAL_MULTI([argument-name], [help message (optional)], [number of arguments], ..., [default for the second-to-last (i.e. penultimate) argument (optional)], [default for the last argument (optional)])
Given that your argument accepts \(n\) values, you can specify \(m\) defaults, \((m \leq n)\) for last \(m\) values.
For example, consider that your script makes use of only one multi-value argument, which accepts 3 values with two defaults
bar
andbaz
. Then, it is imperative that at least one value is specified on the command-line. So If you pass a valueval1
on the command-line, you will be able to retrieveval1
,bar
andbaz
inside the script. If you passval1
andval2
, you will be able to retrieveval1
,val2
andbaz
. If you pass nothing, or more than three values, an error will occur.Arguments are available as a
bash
array (first element has index of 0).Infinitely many-valued positional argument (with optional defaults):
ARG_POSITIONAL_INF([argument-name], [help message (optional)], [minimal number of arguments (optional, default=0)], [default for the first non-required argument (optional)], ...)
Argbash
supports arguments with arbitrary number of values. However, you can require a minimal amount of values the caller has to provide and you can also assign defaults for the values that are not required. Given that your argument accepts at least \(n\) values, you can specify defaults for \((n + 1)\)th argument (and so on).For example, consider that your script makes use of infinitely many-valued argument, which accepts at least 1 value and also has two defaults
bar
andbaz
. Then, it is imperative that at least one value is specified on the command-line. So If you pass a valueval1
on the command-line, you will be able to retrieveval1
,bar
andbaz
inside the script. If you passval1
,val2
,val3
andval4
, you will be able to retrieveval1
,val2
val3
andval4
.Arguments are available as a
bash
array (first element has index of 0).Note
The main difference between
ARG_POSITIONAL_MULTI
andARG_POSITIONAL_INF
is in handling of defaults. InARG_POSITIONAL_MULTI
, defaults determine the number of values that are required to be supplied. InARG_POSITIONAL_INF
, you determine the number of required values and defaults follow.End of optional arguments and beginning of positional ones (the double-dash
--
):ARG_POSITIONAL_DOUBLEDASH()
You are encouraged to add this to your script if you use both positional and optional arguments.
This pattern is known for example from the
grep
command. The idea is that you specify optional arguments first and then, whatever argument follows it, it is considered to be a positional one no matter how it looks. For example, if your script accepts a--help
optional argument and you want it to be recognized as positional, using the double-dash is the only way.
Optional arguments¶
Single-value optional arguments:
ARG_OPTIONAL_SINGLE([argument-name-long], [argument-name-short (optional)], [help message (optional)], [default (optional)])
The default default is an empty string.
Boolean optional arguments:
ARG_OPTIONAL_BOOLEAN([argument-name-long], [argument-name-short (optional)], [help message (optional)], [default (optional)])
The default default is
off
(the only alternative ison
).Incremental optional arguments:
ARG_OPTIONAL_INCREMENTAL([argument-name-long], [argument-name-short (optional)], [help message (optional)], [default (optional)])
The default default is 0. The argument accepts no values on command-line, but it tracks a numerical value internally. That one increases with every argument occurrence.
Repeated optional arguments:
ARG_OPTIONAL_REPEATED([argument-name-long], [argument-name-short (optional)], [help message (optional)], [default (optional)])
The default default is an empty array. The argument can be repeated multiple times, but instead of the later specifications overriding earlier ones (s.a.
ARG_OPTIONAL_SINGLE
does), arguments are gradually appended to an array. The form of the default is what you normally put between the brackets when you createbash
arrays, so put whitespace-separated values in there, for example:ARG_OPTIONAL_REPEATED([include], [I], [Directories where to look for include files], ['/usr/include' '/usr/local/include'])
The specified values are appended to defaults, so if you consider a script that accepts the
--include
argument due to the directive above, if you pass it-I src/include
, the argument-holding array will have three elements —/usr/include
,/usr/local/include
andsrc/include
.Unlike the rest of the Argbash macros, you are responsible to quote the defaults properly. Therefore, if you pass
"one two three"
as default, it will translate to a 1-element array with the sole element"one two three
. Typically, you will wantone two three
, or maybe even"${one_to_nineteen[@]}" twenty "twenty one"
passed to the macro.Action optional arguments (i.e. the
--version
and--help
type of comments):ARG_OPTIONAL_ACTION([argument-name-long], [argument-name-short (optional)], [help message (optional)], [code to execute when specified])
The scripts exits after the argument is encountered. You can specify a name of a function,
echo "my-script: v0.5"
and whatever else. This is simply a shell code that will be executed as-is (including"
and'
quotes) when the argument is passed. It can be multi-line, but if you need something sophisticated, it is recommended to define a shell function in your script template and call that one instead.
Special arguments¶
Help argument (a special case of an optional action argument):
ARG_HELP([short program description (optional)], [long program description (optional)], [short option (optional, "h" by default)], [long option (optional, "help" by default)], [option description (optional, "Prints help" by default)])
By default, it will generate the
--help
and-h
action arguments that will print the usage information. You can use the last three arguments to override the default help argument handling. If you wish to disable the short argument for the help, just leave it blank, and specify either the long argument, or the description. Notice that the usage information is generated even if this macro is not used — we print it when we think that there is something wrong with arguments that were passed.The long program description is a string quoted in double quotation marks (so you may use environmental variables in it) and additionally, occurrences of
\n
will be translated to a line break with indentation (use\\n
to have the actual\n
in the help description). If you want to have environmental variables and newlines, you have to make sure that the env variable contains literal newlines/tabs — you can either use thefoo=$'broken\nline'
pattern, or you can use quotes to define the variable so it contains real literal newlines / tabs.Example invocation:
ARG_HELP([My app], [Parses arguments ...\n... perfectly.], [], [?])
Version argument (a special case of an action argument):
ARG_VERSION([code to execute when specified], [short option (optional, "v" by default)], [long option (optional, "version" by default)], [option description (optional, "Prints version" by default)])
By default, it will generate the
--version
and-v
action arguments that will print the version information. You can use the last three arguments to override the default version argument handling. If you wish to disable the short argument for the version, just leave it blank, and specify either the long argument, or the description.Enhanced version argument (a special case of an action argument):
ARG_VERSION_AUTO([version number or macro containing it], [additional version message (optional)], [short option (optional, "v" by default)], [long option (optional, "version" by default)], [option description (optional, "Prints version" by default)])
The macro will take it’s first argument, expands it, and treats it as a version number. This allows you to use a quoted macro containing the version number as the first argument. Then, it attempts to detect the basename of the generated script and outputs a version message out of those two.
If the
ARG_HELP([MSG], ...)
macro has been used before, it also outputs theMSG
below the program name — version pair.For example, for argbash, it yields
argbash 2.10.0 Argbash is an argument parser generator for Bash.
Verbose argument (a special case of a repeated argument):
ARG_VERBOSE([short arg name])
Default default is 0, so you can use a
test $_arg_verbose -ge 1
pattern in your script.Collect leftovers:
ARG_LEFTOVERS([help text (optional)])
This macro allows your script to accept more arguments and collect them consequently in the
_arg_leftovers
array.A use case for this is wrapping of scripts that are completely
Argbash
-agnostic. Therefore, your script can take its own arguments and the rest that is not recognized can go to the wrapped script.
Typing macros¶
Warning
Features described in this section are experimental. Macros in the type-related section below are not an official part of the API yet — their names and/or signature may change.
The documentation here is just a peek into the Argbash
future.
Please raise an issue if you feel you can provide helpful feedback!
Argbash
supports typed argument values.
For example, you can declare that a certain argument requires an integer value, and if its value by the time of conclusion of the parsing part of the script is not of an integer type, an error is raised.
The validator sometimes returns the value in a canonical form (e.g. it may trim leading and trailing whitespaces).
Note
Users of your script have to have a working grep
in order to use this.
Generally, macros accept these parameters:
- Type code. In some cases, you make it up and in other cases, you have to know the right one. End-users of your script won’t even see it.
- Type string. This is used in the script’s help.
- List of arguments whose values are of the given type.
Typically,
[arg1, arg2]
is OK[*].
[*] | Passing arg1, arg2 won’t work (of course — this represents two arguments, not one that is a list), [arg1, arg2] will work in most cases (when neither arg1 or arg2 have been defined as a macro), whereas [[arg1],[arg2]] will work no matter what. |
You have these possibilities:
Built-in types:
ARG_TYPE_GROUP([type code], [type string], [list of arguments of that type])
Type code is a code of one of the types that are supported, type string is used in help.
Type code Description int integer pint positive integer nnint non-negative integer float floating-point number (e.g. 4.2e1) decimal float without the exponential stuff (e.g. 42.0) string anything [†] [†] The type
string
is used as a means to modify the help message, no validation or conversion takes place.As an example, if you have an argument
--iterations
that accepts a value representing how many times to repeat something, you useARG_TYPE_GROUP([nnint], [COUNT], [iterations])
One-of values (i.e. values are restricted to be members of a set).
ARG_TYPE_GROUP_SET([type code], [type string], [list of arguments of that type], [list of values of that type], [suffix of the index variable (optional)])
If the suffix of the index variable is provided, each argument of the type will have a variable
_arg_<stem>_<suffix>
that contains the 0-based index of the argument value in the allowed values list. You will typically want to use it as described in the next example:Remarks:
- Pass the list of values without shell-quoting. Double quotes will be applied later.
ARG_TYPE_GROUP_SET([operations], [OPERATION], [start-with,stop-with], [configure,make,install], [index])
and later in the code, you can use a construct like
# fail e.g. when we start-with make and stop-with configure. # It would work if it was the other way. test "$_arg_stop_with_index" -gt "$_arg_start_with_index" \ || die "The last operation has to be a successor of the first one, which is not the case."
Convenience macros¶
Plus, there are convenience macros:
Set the indentation in the parsing part of the script:
ARGBASH_SET_INDENT([indentation character(s)])
The default indentation is one tab per level. If you wish to use two spaces as the Google style recommends, simply pass two spaces (in square brackets!) as an argument to the macro.
Set the delimiter between option and value:
ARGBASH_SET_DELIM([option-value delimiter character(s)])
The default delimiter is either space or equal sign. You can either restrict delimiter to only space or only equal sign, or you can keep both. Assuming you have an option accepting value (can be either single-valued or repeated)
--option
with short option-o
, the following works with these arguments to the macro:ARGBASH_SET_DELIM([ ])
: Either of--option value
,--o value
assigns value to theoption
argument.--option=value
will be considered as a single positional argument.ARGBASH_SET_DELIM([=])
: Either of--option=value
,--o value
assigns value to theoption
argument.--option value
will result in both--option
andvalue
to be considered as two positional arguments.-o=value
will also be considered as a positional argument.ARGBASH_SET_DELIM([= ])
(or[ =]
): Either of--option=value
,--o value
,--option value
assigns value to theoption
argument; they are treated the same way. This is the default behavior.
Add a line where the directory where the script is running is stored in an environmental variable:
DEFINE_SCRIPT_DIR([variable name (optional, default is 'script_dir')])
You can use this variable to e.g. source
bash
snippets that are in a known location relative to the script’s parent directory.DEFINE_SCRIPT_DIR_GNU([variable name (optional, default is 'script_dir')])
Does the same as
DEFINE_SCRIPT_DIR
, but it uses thereadlink -e
to determine the real script directory by resolving symlinks.Warning
This command is available only on GNU systems, so be very careful with its usage — it won’t work for OSX users, and for users on non-GNU based Linux distributions (s.a. Alpine Linux). Don’t use it unless you need the functionality AND you are sure that the script will be used only on systems with GNU coreutils.
Add a function that you can use to source modules relative to the script’s location
DEFINE_LOAD_LIBRARY([loader function name (optional, default is load_lib_relativepath)])
Defines a function (
load_lib_relativepath
by default) that takes a path relative to the script’s directory as an input, and attempts to source a file at that path. In case of failure,die
is called, displays an error message, and quits the program.
Include a file (let’s say a
parse.sh
file) that is in the same directory during runtime. If you use this in your script,Argbash
finds out and attempts to regenerateparse.sh
usingparse.sh
orparse.m4
if the former is not available. Thanks to this, managing a script with body and parsing logic in separate files is really easy.INCLUDE_PARSING_CODE([filename], [SCRIPT_DIR variable name (optional, default is script_dir)])
In order to make use of
INCLUDE_PARSING_CODE
, you have to useDEFINE_SCRIPT_DIR
on preceding lines, but you will be told so if you don’t.See also
Check out the example: Separating the parsing code
Point to a script that uses
Argbash
(or to its template), and your script will inherit its arguments (unless you exclude some of them).ARGBASH_WRAP(filename stem, [list of long options to exclude], [flags to exclude certain arg types, default is HV for (h)elp and (v)ersion])
Given that you have a script
process_single.sh
and you write its wrapperprocess_file.sh
Imagine that one reads a file and passes data from every line toprocess_single.sh
along with some options thatprocess_file.sh
accepts.In this case, you write
ARGBASH_WRAP([process_single], [operation])
to yourprocess_file.m4
template.Filename stem is a filename without a directory component or an extension. Stems are searched for in search paths (current directory, directory of the template) and extensions
.m4
and.sh
are tried out.The list of long options is a list of first arguments to functions such as
ARG_POSITIONAL_SINGLE
,ARG_OPTIONAL_SINGLE
,ARG_OPTIONAL_BOOLEAN
, etc. Therefore, don’t include leading double dash to any of the list items that represent blacklisted optional arguments. To blacklist the double dash positional argument feature, add the--
symbol to the list.Flags is a string that may contain some characters. If a flag is set, a class of arguments is excluded from the file. The default
HVIS
should be enough in most scenarios — you want your own help, version info, indentation and option–value separator, not ones from the wrapped script, right?Following flags are supported:
Character Meaning H Don’t include help. V Don’t include version info. I Don’t use wrapped script’s indentation S Don’t use wrapped script’s option–value separator
As a convenience feature, if you wrap a script with stem
process_single
, all options that are part of the wrapped script’s interface (both arguments and values) are stored in an array_args_process_single
. In the case where there may be issues with positional arguments (they are order-dependent and the wrapping script may want to inject its own to the wrapped script), you can use_args_process_single_opt
, or_args_process_single_pos
, where only optional/positional arguments are stored. Therefore, when you finally decide to callprocess-single.sh
in your script with all wrapped arguments (e.g.--some-opt foo --bar
), all you have to do is to write./process-single.sh "${_args_process_single_opt[@]}"
which is exactly the same as
MAYBE_BAR= test $_arg_bar = on && MAYBE_BAR='--bar' ./process-single.sh --some-opt "$_arg_some_opt" $MAYBE_BAR
The stem to array name conversion is the same as with argument names except the prefix
_args_
is prepended.Note
The wrapping functionality actually only makes your script to inherit (all or some of the) the wrapped script’s arguments. If you really wish to call the wrapped script, it is your responsibility to know its location,
Argbash
essentially can’t and won’t help you with that.However, if you know the relative location of the wrapped script to the wrapper, you can use the DEFINE_SCRIPT_DIR macro.
See also
Check out the example: Wrapping scripts
The wrap functionality works recursively, so you can wrap scripts that wrap scripts in a similar manner as you use class inheritance in object-oriented programming languages. More precisely, it is like the private inheritance — the
_args_...
variables will be generated only for first-order wrapped scripts.
Warning
Features described at the rest of this section are experimental. Convenience macros below are not an official part of the API yet — their names and/or signature may change.
The documentation here is just a peek into the Argbash
future.
Please raise an issue if you feel you can provide helpful feedback!
Declare that your script uses an environment variable, set a default for it if it is blank upon the script’s invocation and optionally mention it in the script’s help:
ARG_USE_ENV([variable name], [default if empty (optional)], [help message (optional)])
For instance, if you declare
ARG_USE_ENV([ENVIRONMENT], [production], [The default environment])
, the value of theENVIRONMENT
environmental variable won’t be empty — if the user doesn’t do anything, it will beproduction
and if the user overrides it, it will stay that way. It is undefined whether the user can override it so it has a blank value in the script due to the user override (i.e. it is not possible now, but it may become possible in a later release.).Declare that your script calls a program and enable the caller to set it using an environmental variable.
ARG_USE_PROGRAM([program name], [env variable name (optional)], [message if not found (optional)], [help message (optional)])
For instance, if you use
ARG_USE_PROGRAM([python], [PYTHON], [], [The preferred Python interpreter])
in your script, you can use constructs s.a."$PYTHON" script.py
later in the script body.Remarks:
- If the environment variable is not given, it defaults to the transliteration of the command. Lowercase characters are converted to uppercase, the dashes are converted to underscore.
- If the script is called with the environment variable defined, then no checking will be done — the variable contents are trusted, and passed on.
- If the environment variable is empty, the program will be given to
command -v
as an argument. If that doesn’t succeed, a default or provided message will be displayed, and the script will terminate.
Declare every variable related to every positional argument:
ARG_DEFAULTS_POS()
By default, only variables with defaults are declared. Since values are assigned using
eval
, static analysis tools s.a. shellcheck may complain about referencing undeclared variables. This macro helps to ensure that there are not these false positives.Activate Argbash-powered scripts strict mode:
ARG_RESTRICT_VALUES([mode code])
The mode code restricts allowed values for all arguments.
Mode code What is restricted none nothing is restricted (default behavior) no-any-options anything that looks like as an option (be it long or short) no-local-options option (long or short) of any optional argument this script supports You may want to restrict argument values in order to prevent these possible confusions:
- The user forgets to supply value to an optional argument, so the next argument is mistaken for it.
For example, when we leave
time
fromls --sort time --long /home/me/*
, we get a syntactically valid command-linels --sort --long /home/me/*
, where--long
is identified as value of the argument--sort
instead an argument on its own. - The user intends to pass an optional argument on the command-line (e.g.
--sort
), but makes a typo, (e.g.--srot
), or the script actually doesn’t support that argument. As an unwanted consequence, it is interpreted as a positional argument.
- The user forgets to supply value to an optional argument, so the next argument is mistaken for it.
For example, when we leave
Make Argbash-powered scripts getopts-compatible:
ARG_OPTION_STACKING([mode code])
The mode code either enables getopt-like grouping (a.k.a. stacking) of short arguments according to Guideline 5, or disables it.
Mode code What is restricted none no grouping support getopts support full getopts-like functionality (default behavior)
Action macro¶
Finally, you have to express your desire to generate the parsing code, help message etc. You do it by specifying an “action macro” past all arguments definitions.
You can either let the parsing code to be executed (carefree mode), or you can just generate parsing functions and call them yourself (DIY mode).
Carefree mode: Use action macro
ARGBASH_GO
. The macro doesn’t take any parameters.ARGBASH_GO
DIY mode: Use action macro
ARGBASH_PREPARE
. The macro doesn’t take any parameters.If you are not familiar with the DIY mode, generate the script with embedded helpful comments that tell you what functions you have to call in your code to fully use the Argbash potential.
ARGBASH_PREPARE
Warning
This feature is under development and not part of the stable API.
Available shell stuff¶
Variable
script_dir
that is available if the DEFINE_SCRIPT_DIR is used.Function
die
.Accepts two parameters — string that is printed to
stderr
and exit status number (optional, default is 1). If an environmental variable_PRINT_HELP
is set toyes
, it prints help before the error message.
Using parsing results¶
The key is that parsing results are saved in shell variables that relate to argument (long) names. The argument name is transliterated like this:
- All letters are made lower-case
- Dashes are transliterated to underscores (
include-batteries
becomesinclude_batteries
) _arg_
is prepended to the string. So given that you have an argument--include-batteries
that expects a value, you can access it via shell variable_arg_include_batteries
.
- Boolean arguments have values either
on
oroff
. If (a boolean argument)--quiet
is passed, value of_arg_quiet
is set toon
. Conversely, if--no-quiet
is passed, value of_arg_quiet
is set tooff
. - Repeated arguments collect values to a bash array.
- Incremental arguments have a default value (0 by default) and their value in the script corresponds to the default plus the number of times the argument was specified.