example.rst

Examples

Templates

Minimal example

Let's call minimal example a script that accepts some arguments and prints their values. Let's consider a positional, optional, optional boolean, --version and --help arguments with parsing code embedded in the script. First of all, we can generate the template using argbash-init. Then, we will edit it and add the script body.

First of all, we go examine argbash-init help --- either by running argbash-init -h or :ref:`looking into the documentation <argbash_init_general>`. We find out that we can have argbash-init generate the positional, optional arguments and help, so we go ahead:

.. literalinclude:: _static/minimal_init-create.txt
   :language: bash

The output of argbash-init looks like this:

.. literalinclude:: ../resources/examples/minimal-raw.m4
   :language: bash

We add useful information and the line with the --version macro (by looking it up in the API docs) and the template finally looks better. Plus, we append the actual script body to the template:

.. literalinclude:: ../resources/examples/minimal.m4
   :language: bash

Here, we can notice multiple notable things:

1. argbash-init has produced code that warn us if we treat the template as a script (i.e. if we execute it). This code will not be in the final script --- it will disappear as we pass the template to argbash.
2. Definitions of arguments are placed before the script body. From bash point of view, they are commented out, so the "template" can be a syntactically valid script.
3. You access the values of argument foo-bar as $_arg_foo_bar etc. (this is covered more in-depth in :ref:`argument_names`).

So let's try the script in action! We have to generate it first by passing the template to argbash:

.. literalinclude:: _static/minimal_argbash-create.txt
   :language: text

This has produced the code :ref:`we can observe below <src_minimal>` (notice that the leading "this is not a script error" lines have disappeared). Let's see what happens when we pass the -h option:

.. literalinclude:: _static/minimal-output-help.txt
   :language: text

OK, so it seems that passing it one (mandatory) positional arg will do the trick:

.. literalinclude:: _static/minimal-output-noverbose.txt
   :language: text

Oops, we have forgot to turn print on! Let's fix that...

.. literalinclude:: _static/minimal-output-foobar.txt
   :language: text

Separating the parsing code

Let's take a look at a script that takes filename as the only positional argument and prints size of the corresponding file. The caller can influence the unit of display using optional argument --unit. This script is a bit artificial, but hang on --- we will try to use it from within a wrapping script.

This time, we will :ref:`separate the parsing code and the script itself <file_layout>`. The parsing code will be in the simple-parsing.sh file and the script then in simple.sh.

Note

This is the manual approach. A simpler way would be calling argbash-init in the :ref:`managed or decoupled mode <argbash_init_modes>` --- it will create the basic templates as in the previous example.

The template for the script's parsing section is really simple. Below are the sole contents of simple-parsing.m4 file:

.. literalinclude:: ../resources/examples/simple-parsing.m4
   :language: bash

Then, let's take a look at the script's template body (i.e. the simple.m4 file):

.. literalinclude:: ../resources/examples/simple.m4
   :language: bash

We obtain the script from the template by running argbash over it --- it detects the parsing template and interconnects those two.

argbash simple.m4 -o simple.sh

In other words, it will examine the simple.m4 template, finding out that there is the :ref:`INCLUDE_PARSING_CODE <parsing_code>` macro. If the parsing template (in our case simple-parsing.m4 or simple-parsing.sh) is found, a parsing script is produced out of it (otherwise, an error occurs). Finally, the simple.sh script is (re)generated --- basically only the source directive is added, see those few lines:

.. literalinclude:: ../resources/examples/simple.sh
   :language: bash
   :end-before: # [ <-

When invoked with the help option, we get:

.. literalinclude:: _static/simple-output-help.txt
   :language: text

It will work as long as the parsing code's location (next to the script itself) doesn't change:

Wrapping scripts

We will show how to write a script that accepts a list of directories and a glob pattern, combines them together, and displays size of files using the previous script. In order to do this, we will introduce positional argument that can accept an arbitrary amount of values and we will also use the wrapping functionality that Argbash possesses.

We want to wrap the simple.m4 (or simple.sh). However, since the script doesn't include any command definitions, we have to wrap the parsing component simple-parsing.. The script's template is still quite simple:

.. literalinclude:: ../resources/examples/simple-wrapper.m4
   :language: bash

The simple-parsing in :ref:`ARGBASH_WRAP <argbash_wrap>` argument refers to the parsing part of the script from the previous section. Remember, we say that we are wrapping a script, but in fact, we just inherit a subset of its arguments and the actual wrapping (i.e. calling the wrapped script) is still up to us, although it is made easy by a great deal. The filename argument means that our wrapping script won't "inherit" the filename argument --- that's correct, it is the wrapping script that decides what arguments make it to the wrapped one.

When invoked with the help option, we get:

.. literalinclude:: _static/wrapper-output-help.txt
   :language: text

So let's try it!

.. literalinclude:: _static/wrapper-output-action.txt
   :language: text

Source

Minimal example

Let's examine the generated :ref:`minimal example script <minimal_example>` (the contents are displayed below).

We can see that the header still contains the Argbash definitions. They are not there for reference only, you can actually change them and re-run Argbash on the script again to get an updated version! Yes, you don't need the .m4 template, the .sh file serves as a template that is equally good!

.. literalinclude:: ../resources/examples/minimal.sh
   :language: bash