"Fossies" - the Fresh Open Source Software Archive

Member "argbash-2.10.0/doc/guide.rst" (22 Sep 2020, 34799 Bytes) of package /linux/privat/argbash-2.10.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "guide.rst": 2.9.0_vs_2.10.0.

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

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:

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 wit 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:

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

Optional arguments

Special arguments

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:

You have these possibilities:

Convenience macros

Plus, there are convenience macros:

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!

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).

Available shell stuff

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:

  1. All letters are made lower-case
  2. Dashes are transliterated to underscores (include-batteries becomes include_batteries)
  3. _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.

  1. 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.↩︎