Provided by: shellia_5.7.1_all 
NAME
shellia - library for interactive shell scripts
SYNOPSIS
script.using.shellia [-i|-s|-m] [-d debug-runtime-config] [-a] [--]
[script-specific-options]
DESCRIPTION
shellia is a library that allows to run shell scripts interactive and helps to familiarize
oneself with large shell scripts, find the cause of unexpected behaviour in shell scripts,
and run shell scripts silently, while checking them step by step.
A script.using.shellia can be called with option -i to run in interactive-mode. This
means that the user can start steps of the script.
If the script.using.shellia uses check-mode, output and return values of internal steps
are checked. If something unexpected happens, the script can either stop or ask the user
what to do.
OPTIONS
General options
-i use interactive-mode
-s be silent
-m minimal control
-d debug-runtime-config
Turn debug-mode on from the beginning. You also may turn debug on and off while
running in interactive-mode.
-a Use only ascii without colour in interactive-mode and logging-mode
EXAMPLE
Be aware that the step sizes in the examples listed below are only reasonable to
demonstrate shellia features and for no other purpose. Please read shellia(7) NOTES, to
learn about a reasonable step size.
Basic features
On debian systems the following described script hello_world may be found at
/usr/share/doc/shellia/examples/hello_world.
If called without option, it will just print the words hello and world:
$ /usr/share/doc/shellia/examples/hello_world
hello
world
If called with option -i, you will have some interactive choices:
$ /usr/share/doc/shellia/examples/hello_world -i
=== hello_world ===
1 echo "hello"
2 echo "world"
c continue without questionsq quit
? [1]
Entering 1 would execute the first step and print the word hello. Actually, because 1 is
preselected as shown in the last line, just entering RETURN, would do the same. Step 2 is
equivalent to step 1. After step 2 the preselection would change to q. q means quit and
can be pressed anytime to leave the current step level, Which would leave the shell script
in our case. Instead of entering 1, 2 and q, c could have been entered to continue
automatically.
A discussion of the source of this shell script can be found in shellia(3) Basic features.
Interactive-mode
In Basic features all steps shown in Interactive-mode have been at the same level. In
Interactive-mode muliple levels are supported.
On debian systems the following described script hello_world_fun may be found at
/usr/share/doc/shellia/examples/hello_world_fun.
If called without shellia specific option, but with the name "Test User", the output will
be:
$ /usr/share/doc/shellia/examples/hello_world_fun "Test User"
hello Test User
If additionally called with option -i, you will have some interactive choices:
$ /usr/share/doc/shellia/examples/hello_world_fun -i -- "Test User"
=== hello_world_fun ===
1 say_hello -i -- "Test User"
i toggle -i flag
q quit?
[1]
Entering i turns -i on and off as shown above and in the next line:
1 say_hello -- "Test User"
If we would press 1 while -i is off, the function say_hello would be executed at once.
Pressing 1 while -i is on would start function say_hello in interactive-mode and display
the following menu with steps in a deeper level:
=== hello_world_fun/say_hello ===
1 name="Test User"
2 echo "hello $name"
c continue without questions
q quit?
[1]
In the heading we can see, the name of the current function. Because we have to start
with the first step in this function again 1 is preselected. To run all steps in this
function we can press c. After executing, we will return to the previous menu and can
press RETURN to select the preselected quit.
A discussion of the source of this shell script can be found in shellia(3)
Interactive-mode.
Debug-mode
Each debug-statement in a script-using-shellia has additionally to the debug-output a
debug-statement-level, and a debug-statement-topic with the defaults 1 and none.
At runtime the script gets a debug-runtime-level and a debug-runtime-topic list with the
defaults 0 and empty.
The debug-output will be shown if the, the debug-runtime-level is higher or equal to the
debug-statement-level and either the debug-statement-topic is in the debug-runtime-topic
list, or the debug-runtime-topic list is empty.
On debian systems the example script hello_world_debug may be found at
/usr/share/doc/shellia/examples/hello_world_debug.
In the header of the script we can read, that the used debug-topics are none, start and
end and that the higest debug-level is 3.
To see all debug-output we can start with an empty debug-runtime-topic list and the very
high debug-runtime-level 99:
$ /usr/share/doc/shellia/examples/hello_world_debug -d 99
DEBUG main program
DEBUG say_hello function start
hello world
DEBUG say_hello function end
To see only the debug-topics none and start in interactive-mode we can call:
$ /usr/share/doc/shellia/examples/hello_world_debug -d "99 none start"
=== hello_world_debug ===
1 dbg "main program"
2 say_hello_world
d ... change dbg: 99 none start
c continue without questions
q quit
? [1]
If we now change our mind, to not see the debug-topic start anymore and to change the
debug-level 2 we can change this by entering d start 2 before continuing with c:
? [1] d start 2
=== hello_world_debug ===
1 dbg "main program"
2 say_hello_world
d ... change dbg: 2 none
c continue without questions
q quit
? [1] c
DEBUG main program
hello world
The interactive-mode can be used to turn on debug-output only in steps where we need it.
Log-mode
If the script-using-shellia creates a logfile as described in shellia(3) logfile-mode, the
created logfile has some features as shown in the example script hello_world_log. On
debian systems it may be found at /usr/share/doc/shellia/examples/hello_world_log. The
example script will automatically display the logfile at the end.
First we call it without options:
$ /usr/share/doc/shellia/examples/hello_world_log "shellia user"
hello shellia user
--- LOGFILE ---
|hello_world_log
||hello_world_log/say_hello
||s:hello shellia user
---------------
The first line shows how the script is called. The second line shows the output of the
script hello shellia user Then the logfile is displayed in two lines starting with dashes.
The first line of the logfile has one bar, indicating that we are in the first level,
which is the main script in file hello_world_log The second line of the logfile has two
bars, indicating we are in the next level, followed by the filename and the function name.
The third line is from the same function and show with an s:, that stdout hello shellia
user has been created by this function.
We will now run the same script with all debug output enabled to see debug information
with the word DEBUG added
$ /usr/share/doc/shellia/examples/hello_world_log -d 99 "shellia user"
DEBUG main program begin
DEBUG function say_hello called with 1 arguments
hello shellia user
DEBUG function say_hello end
DEBUG main program end
--- LOGFILE ---
|hello_world_log
|DEBUG main program begin
||hello_world_log/say_hello
||DEBUG function say_hello called with 1 arguments
||s:hello shellia user
||DEBUG function say_hello end
|DEBUG main program end
---------------
Another way is to start in interactive mode, manually select the function with 2, continue
all steps in the function with c and then quit with q. Now also the interactive input and
output will be logged and the logfile will be too large, to display it here.
variable in Interactive-mode
If you see $<var> in interactive mode, the meaning is like \${var}, but you can press v to
see the actual value of the variable. If you press v again, the name of the variable is
shown as before.
NOTES
shellia is tested successful with bash, dash, busybox sh, mksh and posh. To use shellia
with posh the nounset option (set -o nounset or set -u) is not supported because of Bug
#913718 (posh can not use "$@" together with set -u). Because of Bug #910275 (posh does
never execute an "EXIT trap", if it is created with the "trap" command in a sub shell)
remaining files named "/tmp/shellia.??????????" should be deleted manual, after using
shellia with posh. shellia can not be used in ksh, because the shell does not support the
local command.
ERROR MESSAGES
ERROR: ia premature exit of command unchecked output: unchecked output
Before output of a command issued with check-mode can be printed, it will be collected
and checked. If the script.using.shellia exits premature, the already collected
unchecked output is printed with this error message.
SEE ALSO
shellia(3), shellia(7)
AUTHOR
bernd.schumacher@hpe.com
License: GNU General Public License, version 3
COPYRIGHT
Bernd Schumacher <bernd.schumacher@hpe.com> (2007-2020)