Let's call minimal example a script that accepts some arguments and prints their values.
Let's consider a positional, optional, optional boolean,
--help arguments with parsing code embedded in the script.
First of all, we can generate the template using
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:
argbash-inithas 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
- Definitions of arguments are placed before the script body.
bashpoint of view, they are commented out, so the "template" can be a syntactically valid script.
- You access the values of argument
$_arg_foo_baretc. (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
.. 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
.. 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
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
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
.. literalinclude:: ../resources/examples/simple-parsing.m4 :language: bash
Then, let's take a look at the script's template body (i.e. the
.. 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.sh) is found, a parsing script is produced out of it (otherwise, an error occurs).
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:
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
We want to wrap the
However, since the script doesn't include any command definitions, we have to wrap the parsing component
The script's template is still quite simple:
.. literalinclude:: ../resources/examples/simple-wrapper.m4 :language: bash
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.
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
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
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