shellia

NAME

shellia - library for interactive shell scripts

SYNOPSIS

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

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:
If called with option -i, you will have some interactive choices:
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:
If additionally called with option -i, you will have some interactive choices:
Entering i turns -i on and off as shown above and in the next line:
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:
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:
To see only the debug-topics none and start in interactive-mode we can call:
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:
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:
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
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

SEE ALSO

shellia(3), shellia(7)

AUTHOR

[email protected] License: GNU General Public License, version 3

COPYRIGHT

Bernd Schumacher <[email protected]> (2007-2020)