Provided by: shellia_5.9_all 
NAME
shellia - library for interactive shell scripts
SYNOPSIS
. /usr/share/shellia/ia[.interactive|.check|.debug|]
eval "$ia_init"
[[ia_nocheck [-f]] | [[ia_stdout|ia_ignore regex] ...]]
ia_add command-sequence
dbg [debug-level [debug-topic ...]] debug-output
ia [-c|-C] [-x]
ENVIRONMENT
If ia_logfile contains the path to a writeable file, logfile output as seen by ia is appended to that
file.
DESCRIPTION
shellia is a library that allows to run shell scripts silently or interactive and helps to check errors
of commands that are combined in steps.
Each function of a shell programm (including the main shell programm) can include a group of steps. A
group of steps should always be enclosed between an initializing line eval "$ia_init" and the line with
command ia which starts the execution of the steps. Each step is a command-sequence given as string
argument to ia_add The command-sequence contained in the string has the same requirements as if it would
be given to the shell command eval.
OPTIONS
. /usr/share/shellia/ia[.interactive|.check|.debug|]
To only load the shellia interactive library for basic interactive features use .
/usr/share/shellia/ia.interactive. To only load shellia check library to check stderr, stdout and
exit-value of steps use . /usr/share/shellia/ia.check. TO only load the shellia debug library, to
add debug-output to a shell script use . /usr/share/shellia/ia.debug. To source all shellia
libraries listed above is the suggested method and can be done with . /usr/share/shellia/ia.
ia_nocheck
This command can be used, if the following ia command has enabled check-mode with option [-c|-C]
for its group of steps. This will disable the check of stderr and stdout in the next single
ia_add step. With opiton -f added, it will also disable checking the exit value of the next
single step. Also if a step may exit the script, ia_nocheck can be used to prevent the message
ERROR: ia premature exit of ....
ia_stdout regex
to use this command, the following ia command has to be used with option -c. regex is a regualar
expressions as defined in gawk(1), to define which output of the following step defined with
ia_add will be standard output of the step. Each step can be preceded with any number of
ia_stdout regex commands. Because the user can not suppress output allowed with ia_stodut with
the option -s, ia_stdout should only be used, if the output is intendet to be piped to another
programm. regex only needs to handle text without color-control-codes.
ia_ignore regex
to use this command, the following ia command has to be used with either option -c or -C. regex
is a regualar expressions as defined in gawk(1), to define which output of the following step
defined with ia_add will be ignored. Each step can be preceded with any number of ia_ignore regex
commands. regex only needs to handle text without color-control-codes.
-c if this option is given to ia all steps previous added with ia_add will be checked with check-mode
option -c (see check-mode below)
-C if this option is given to ia all steps previous added with ia_add will be checked with check-mode
option -C. (see check-mode below)
-x if this option is given to ia all steps previous added with ia_add will use trace-mode. (see
trace-mode below)
USAGE
The examples listed below try to show the technical features of shellia in very small examples.
Be aware that the step size in the example listed below is only reasonable to demonstrate shellia
features. Please read shellia(7) NOTES, to learn about a reasonable size of interactive steps.
Basic features
A script using the basic features to print hello world may look like:
01 #!/bin/sh
02 . /usr/share/shellia/ia.interactive
03 eval "$ia_init"
04 ia_add "echo \"hello\""
05 ia_add "echo \"world\""
06 ia
In line 02 the shellia library ia.interactive is loaded. Line 03 initializes shellia and is needed
before shellia functions can be used. It also consumes all shellia standard options, so that the
remaining options will be script-specific-options. Line 04 and 05 are using ia_add to add the echo
commands. The execution starts in line 06 with the ia command.
If the script is called without options, it only prints hello and world. If it is called with option -i
it will run in interactive mode, as discussed in shellia(1) Basic features.
On debian systems this script may be found at /usr/share/doc/shellia/examples/hello_world.
Interactive-mode
A script using a function in interactive-mode may look like:
01 . /usr/share/shellia/ia.interactive
02 say_hello()
03 {
04 local name
05 eval "$ia_init"
06 ia_add "name=\"$1\""
07 ia_add "echo \"hello \$name\""
08 ia
09 }
10 eval "$ia_init"
11 ia_add "say_hello <-i> -- \"$1\""
12 ia
Line 01, 10, 12 are equivalent as in the previous example. Line 02, 03, 04, 07 and 09 are normal shell
statements, with no additional comments. Line 05 to initialize shellia has to be done in each function.
Line 06 sets variable name to $1. Line 08 starts the steps and is needed in all functions. Line 11 uses
the special syntax <-i> which allows to switch -i in interactive-mode.
On debian systems this script may be found at /usr/share/doc/shellia/examples/hello_world_fun.
See shellia(1) Interactive-mode to read about using this script.
check-mode
Before demonstrating how to use the check-mode option -c or -C we first start with the following script,
without any check-mode option:
01 . /usr/share/shellia/ia
02 say_hello()
03 {
04 echo "hello $1"
05 echo "end of function say_hello" >&2
06 return 5
07 }
08 eval "$ia_init"
09 ia_add "say_hello \"$1\""
10 ia
If we run this script we get the following output and exit value:
01 $ ./hello_world_check "shellia user"
02 hello shellia user
03 end of function say_hello
04 $ echo $?
05 5
In the script lines 02 to 07 the function say_hello is defined. To call this function shellia specific
syntax is used in script line 08 to 10. Let's assume the function say_hello may represent an external
programm, that we have to use, but are not allowed to change it. But we want to change the output
presented to the user:
• the output "end of function say_hello" makes no sense for the user. We know it is harmless, and we
just want to suppress it.
• output starting with "hello" is what we want. But any other output, that we may not have seen until
now, should be displayed as error.
• We want to see every nonzero exit value as an error. Only an exit value of 5 seems to be ok and
should not be displayed as error.
We can get this with check-mode option -c or -C. There is a disccussion about which option to use in
shellia(7) When to use check option -c and -C.
check-mode -c
To get the wanted behaviour described in previous chapter with check-mode option -c we change script line
10 to:
10 ia -c
and get the following output:
01 $ ./hello_world_check "shellia user"
02 --- output with ERROR from <hello_world_check> running <say_hello "shellia user"> ---
03 e:hello
04 e:end of function say_hello
05 e:exit=5
06 --- (q)uit (r)edo (i)gnore (s)witch interactive ---
07 ?
Output line 01 shows where errors happended. The output lines 03 to 05 start with e: to classify the
output as errors. Line 03 is also shown as error, because shellia does not know, that it is the wanted
output. Line 04 is what we want to be suppressed. And line 05 now shows every nonzero exit as an error.
To make the program to behave as wanted we can add the folloging lines +a, +b and +c before script line
09:
+a ia_stdout "^hello "
+b ia_ignore "end of function say_hello$"
+c ia_ignore "^exit=5$"
09 ia_add "say_hello \"$1\""
Line +a will display the output we want to see, and line +b and +c will ignore and suppresses what we do
not want to see.
check-mode -C
A file that starts to fix say_hello with check-mode option -C is provided as example and the usage is
explaind in shellia(1). On debian systems this script may be found at
/usr/share/doc/shellia/examples/hello_world_error. The changed script line from the example in chapter
check-mode is:
10 ia -C
and gives the following output:
01 $ ./hello_world_error "shellia user"
02 --- output with ERROR from <hello_world_error> running <say_hello "shellia user"> ---
03 e:end of function say_hello
04 e:exit=5
05 s:hello
--- (q)uit (r)edo (i)gnore (s)witch interactive ---
?
In line 05 s: already classifies the ouput as stdout. To make the program behave as wanted we can add
the folloging lines +a and +b before script line 09:
+a ia_ignore "end of function say_hello$"
+b ia_ignore "^exit=5$"
09 ia_add "say_hello \"$1\""
debug-mode
The library ia.debug includes functions to add debug-output to a shell script. The script.using.shellia
can then be called with a debug-runtime-config to define the debug-level and to select debug-topics. See
shellia(1) debug-mode to learn about debug-runtime-config.
A simple script to add debug-output without debug-level or debug-topics is:
01 . /usr/share/shellia/ia
02 say_hello_world()
03 {
04 dbg "say_hello function start"
05 echo "hello world"
06 dbg "say_hello function end"
07 }
08 eval "$ia_init"
09 ia_add "dbg \"main program\""
10 ia_add say_hello_world
11 ia
Line 01, 08, 10 and 11 are already explained in a previous example. Line 04, 06 and 09 adds
debug-output. Because no debug-level is defined the lowest possible value 1 is used.
In this script debug-output can be turned on when the script is started with a runtime debug-level
greater or equal to 1.
If you want to use debug-level 3 in the function, you can change the following lines:
04 dbg 3 "say_hello function start"
06 dbg 3 "say_hello function end"
Now a debug-runtime-level of at least 3 is needed to produce output for the changed lines.
Sometimes it is not enough to have debug-levels and you need debug-topics to define which debug-output
has to be shown. You can give a free defined debug-topic to each debug-statement line. Normally you
should only use a limited number of debug-topics to make things not to complicated.
We change 2 lines to the free invented debug-topics called start and end:
04 dbg 3 start "say_hello function start"
06 dbg 3 end "say_hello function end"
The script now should look like the hello_world_debug script, that on debian systems may be found at
/usr/share/doc/shellia/examples/hello_world_debug.
See shellia(1) debug-mode to read about using this script.
log-mode
The library ia.log includes functions to add logging to a shell script.
In the logfile each line starts with a number of bars. Following lines with the same number of bars,
result from the same function, which is used as header.
A simple script with logging called hello_world_log is provided as example. On debian systems it may be
found at /usr/share/doc/shellia/examples/hello_world_log. A part of this script is:
01 ia_logfile="$(mktemp)"
02 export ia_logfile
03 . /usr/share/shellia/ia
04 say_hello()
05 {
06 local name
07 eval "$ia_init"
08 ia_add "dbg \"function say_hello called with $# arguments\""
09 ia_add "name=\"$1\""
10 ia_stdout "^hello"
11 ia_add "echo \"hello \$name\""
12 ia -c
13 }
14 eval "$ia_init"
15 ia_add "dbg \"main program begin\""
16 ia_nocheck # do not check the already checked output of next line
17 ia_add "say_hello <-i> -- \"$1\""
18 ia -c
In line 03 the ia library is loaded, which also loads ia.log. The logging is simply enabled by setting
variable ia_logfile in line 01 with the path to the logfile and exporting it in line 02. The new logfile
output will be appended to the logfile.
To see 2 levels of logging in the logfile we have a main program and a function in the example. Both use
check-mode with ia -c in line 07 and 14 which allows to log checked output. To not double check the
function say_hello in the main program line 16 ia_nocheck is added to not check the output of line 17.
The output to the logfile is discussed in shellia(1).
trace-mode
Trace-mode can be enabled with ia -x for a group of steps. When tracemode is enabled, before each step
set -x is called and after each stet set +x is called. This way, no shellia internal commands are
traced.
A simple script with trace-mode called hello_world_trace is provided as example. On debian systems it
may be found at /usr/share/doc/shellia/examples/hello_world_trace. A part of this script is:
01 . /usr/share/shellia/ia
02 write_file() {
03 eval "$ia_init"
04 ia_add "echo \"hello $2\" >$1"
05 ia -c -x
06 }
07 show_file() {
08 eval "$ia_init"
09 ia_stdout "^hello"
10 ia_add "cat $1"
11 ia -c -x
12 }
13 eval "$ia_init"
14 ia_add "file=\"\$(mktemp)\""
15 ia_add "write_file <-i> -- \"\$file\" \"$1\""
16 ia_stdout "."
17 ia_add "show_file <-i> -- \"\$file\""
18 ia_add "rm -f \"\$file\""
19 ia -c -x
Without trace-mode (without -x in line 05 11 and 19) this script would just print one line starting with
hello. The following output is printed when calling
$ /usr/share/doc/shellia/examples/hello_world_trace "shellia user"
+ mktemp
+ file=/tmp/tmp.zCDaHg9dFP
+ echo hello shellia user
+ write_file -- /tmp/tmp.zCDaHg9dFP shellia user
+ cat /tmp/tmp.zCDaHg9dFP
+ show_file -- /tmp/tmp.zCDaHg9dFP
hello shellia user
+ rm -f /tmp/tmp.zCDaHg9dFP
Because log-mode is enabled the following log is written:
|hello_world_trace
|+ mktemp
|+ file=/tmp/tmp.zCDaHg9dFP
||hello_world_trace/write_file
||+ echo hello shellia user
|+ write_file -- /tmp/tmp.zCDaHg9dFP shellia user
||hello_world_trace/show_file
||+ cat /tmp/tmp.zCDaHg9dFP
||s:hello shellia user
|+ show_file -- /tmp/tmp.zCDaHg9dFP
|s:hello shellia user
|+ rm -f /tmp/tmp.zCDaHg9dFP
The log shows, that trace-mode output is included in the log-mode output hierarchie. To get trace-mode
output in a logfile, it is important that log-mode and also check-mode is enabled.
Also if no-check is used for a step, this step will not create trace-mode output in the logfile.
variable in Interactive-mode
If you want to enable the user to see the value of a variable, before it is used, with key press v, you
can write $<var> instead of \$var or \${var}.
HIGH LEVEL FUNCTIONS
ia_ssh
ia_add "ia_ssh ssh-options [--fd fd] [--vars vars] destination shellia-script"
Options:
<ssh-options> ssh options described in ssh(1)
<fd> the filedescriptors <fd> will be transfered
<vars> the variables <vars> will be provided
<destination> ssh destination described in ssh(1)
<shellia-script> script that can use the transferred filedescriptors
and variables
ia_ssh transfers additional to the filedescriptors stderr and stdout the shellia filescriptors
$ia_direct_stderr_fd and $ia_log_fd with ssh. Also the variables listed in $ia_inherit_vars are provided
to the remote shellia-script.
With $ia_log_fd the remote shellia-script does not need to use an own logfile and the log can be written
to the local logfile.
Warning: The order of data transferred by filedescriptors may change within a single shellia step.
PREFIX
Commands or global variables brought by shellia normally start with ia (see NAME in shellia(7)). If
ia.debug is used there will also be commands and global variables that start with dbg. But if you
already use one or both of this prefixes, you can change them, while loading the library.
The example changes ia to mycmd and dbg to myprnt:
ia_prefix=mycmd
dbg_prefix=myprnt
. /usr/share/shellia/ia
Now the new prefixes have to be used, e.g. ia_add is now mycmd_add.
WARNING
It is not always possible to separate sellia's internal variables from script variables. For this reason
variable names starting with ia_ should not be used in scripts.
SEE ALSO
shellia(1), shellia(7), gawk(1)
AUTHOR
bernd.schumacher@hpe.com
License: GNU General Public License, version 3
COPYRIGHT
Bernd Schumacher <bernd.schumacher@hpe.com> (2007-2020)