.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SHELLIA" 1 "2020-08-07" "0.1" "shell library"
.SH NAME
shellia \- library for interactive shell scripts
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
\fIscript.using.shellia\fP [\fB\-i|\-s|\-m\fP] [\fB\-d\fP \fIdebug\-runtime\-config\fP] [\fB\-a\fP] [\-\-] [\fIscript\-specific\-options\fP]
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBshellia\fP 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 \fBstep\fP by \fBstep\fP\&.
.sp
A \fIscript.using.shellia\fP can be called with option \fB\-i\fP to run in
\fBinteractive\-mode\fP\&.
This means that the user can start \fBsteps\fP of the script.
.sp
If the \fIscript.using.shellia\fP uses \fBcheck\-mode\fP,
output and return values of internal \fBsteps\fP are checked.
If something unexpected happens, the script can either stop or ask the user
what to do.
.SH OPTIONS
.SS General options
.INDENT 0.0
.TP
.B \fB\-i\fP
use \fBinteractive\-mode\fP
.TP
.B \fB\-s\fP
be silent
.TP
.B \fB\-m\fP
minimal control
.TP
.B \fB\-d\fP \fIdebug\-runtime\-config\fP
Turn \fBdebug\-mode\fP on from the beginning. You also may turn debug on and off
while running in \fBinteractive\-mode\fP\&.
.TP
.B \fB\-a\fP
Use only ascii without colour in \fBinteractive\-mode\fP and \fBlogging\-mode\fP
.UNINDENT
.SH EXAMPLE
.sp
Be aware that the \fBstep\fP sizes in the examples listed below are only
reasonable to demonstrate shellia features and for no other purpose.
Please read shellia(7) \fBNOTES\fP, to learn about a reasonable \fBstep\fP size.
.SS Basic features
.sp
On \fBdebian\fP systems the following described script \fIhello_world\fP may be
found at \fI/usr/share/doc/shellia/examples/hello_world\fP\&.
.sp
If called without option, it will just print the words \fIhello\fP and \fIworld\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world
hello
world
.EE
.UNINDENT
.UNINDENT
.sp
If called with option \fB\-i\fP, you will have some interactive choices:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world \-i
=== hello_world ===
1 echo \(dqhello\(dq
2 echo \(dqworld\(dq
c continue without questionsq quit
? [1]
.EE
.UNINDENT
.UNINDENT
.sp
Entering \fI1\fP would execute the first \fBstep\fP and print the word \fIhello\fP\&.
Actually, because \fI1\fP is preselected as shown in the last line, just entering
\fIRETURN\fP, would do the same.
Step \fI2\fP is equivalent to \fBstep\fP \fI1\fP\&.
After \fBstep\fP \fI2\fP the preselection would change to \fIq\fP\&.
\fIq\fP means \fIquit\fP and can be pressed anytime to leave the current \fBstep\fP level,
Which would leave the shell script in our case.
Instead of entering \fI1\fP, \fI2\fP and \fIq\fP, \fIc\fP could have been entered to continue
automatically.
.sp
A discussion of the source of this shell script can be found in shellia(3)
\fBBasic features\fP\&.
.SS Interactive\-mode
.sp
In \fBBasic features\fP all \fBsteps\fP shown in \fBInteractive\-mode\fP
have been at the same level.
In \fBInteractive\-mode\fP muliple levels are supported.
.sp
On \fBdebian\fP systems the following described script \fIhello_world_fun\fP may be
found at \fI/usr/share/doc/shellia/examples/hello_world_fun\fP\&.
.sp
If called without \fBshellia\fP specific option, but with the name \(dqTest User\(dq,
the output will be:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world_fun \(dqTest User\(dq
hello Test User
.EE
.UNINDENT
.UNINDENT
.sp
If additionally called with option \fB\-i\fP, you will have some interactive
choices:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world_fun \-i \-\- \(dqTest User\(dq
=== hello_world_fun ===
1 say_hello \-i \-\- \(dqTest User\(dq
i toggle \-i flag
q quit?
[1]
.EE
.UNINDENT
.UNINDENT
.sp
Entering \fIi\fP turns \fB\-i\fP on and off as shown above and in the next line:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
1 say_hello \-\- \(dqTest User\(dq
.EE
.UNINDENT
.UNINDENT
.sp
If we would press \fI1\fP while \fB\-i\fP is off, the function \fIsay_hello\fP would be
executed at once.
Pressing \fI1\fP while \fB\-i\fP is on would start function \fIsay_hello\fP in
\fBinteractive\-mode\fP and display the following menu with \fBsteps\fP in a deeper
level:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
=== hello_world_fun/say_hello ===
1 name=\(dqTest User\(dq
2 echo \(dqhello $name\(dq
c continue without questions
q quit?
[1]
.EE
.UNINDENT
.UNINDENT
.sp
In the heading we can see, the name of the current function.
Because we have to start with the first \fBstep\fP in this function again \fI1\fP is
preselected.
To run all \fBsteps\fP in this function we can press \fIc\fP\&. After executing,
we will return to the previous menu and can press \fIRETURN\fP to select
the preselected \fIquit\fP\&.
.sp
A discussion of the source of this shell script can be found in shellia(3)
\fBInteractive\-mode\fP\&.
.SS Debug\-mode
.sp
Each \fIdebug\-statement\fP in a \fIscript\-using\-shellia\fP has additionally to the
\fBdebug\-output\fP a \fBdebug\-statement\-level\fP, and a \fBdebug\-statement\-topic\fP
with the defaults \fI1\fP and \fInone\fP\&.
.sp
At runtime the script gets a \fBdebug\-runtime\-level\fP and a
\fBdebug\-runtime\-topic\fP list with the defaults \fI0\fP and empty.
.sp
The \fBdebug\-output\fP will be shown if the, the \fBdebug\-runtime\-level\fP is higher
or equal to the \fBdebug\-statement\-level\fP and either the
\fBdebug\-statement\-topic\fP is in the \fBdebug\-runtime\-topic\fP list, or
the \fBdebug\-runtime\-topic\fP list is empty.
.sp
On \fBdebian\fP systems the example script \fIhello_world_debug\fP may be
found at \fI/usr/share/doc/shellia/examples/hello_world_debug\fP\&.
.sp
In the header of the script we can read, that the used \fBdebug\-topics\fP are
\fInone\fP, \fIstart\fP and \fIend\fP and that the higest \fBdebug\-level\fP is 3.
.sp
To see all \fBdebug\-output\fP we can start with an empty
\fBdebug\-runtime\-topic\fP list and the very high \fBdebug\-runtime\-level\fP \fI99\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /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
.EE
.UNINDENT
.UNINDENT
.sp
To see only the \fBdebug\-topics\fP \fInone\fP and \fIstart\fP in \fBinteractive\-mode\fP
we can call:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world_debug \-d \(dq99 none start\(dq
=== hello_world_debug ===
1 dbg \(dqmain program\(dq
2 say_hello_world
d ... change dbg: 99 none start
c continue without questions
q quit
? [1]
.EE
.UNINDENT
.UNINDENT
.sp
If we now change our mind, to not see the \fBdebug\-topic\fP \fIstart\fP anymore and
to change the  \fBdebug\-level\fP \fI2\fP we can change this by entering \fId start 2\fP
before continuing with \fIc\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
? [1] d start 2
=== hello_world_debug ===
1 dbg \(dqmain program\(dq
2 say_hello_world
d ... change dbg: 2 none
c continue without questions
q quit
? [1] c
DEBUG main program
hello world
.EE
.UNINDENT
.UNINDENT
.sp
The \fBinteractive\-mode\fP can be used to turn on \fBdebug\-output\fP only in \fBsteps\fP
where we need it.
.SS Log\-mode
.sp
If the \fIscript\-using\-shellia\fP creates a logfile as described in shellia(3)
\fBlogfile\-mode\fP, the created logfile has some features as shown in the
example script \fIhello_world_log\fP\&.
On \fBdebian\fP systems it may be
found at \fI/usr/share/doc/shellia/examples/hello_world_log\fP\&.
The example script will automatically display the logfile at the end.
.sp
First we call it without options:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world_log \(dqshellia user\(dq
hello shellia user
\-\-\- LOGFILE \-\-\-
|hello_world_log
||hello_world_log/say_hello
||s:hello shellia user
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.EE
.UNINDENT
.UNINDENT
.sp
The first line shows how the script is called.
The second line shows the output of the script \fIhello shellia user\fP
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  \fIhello_world_log\fP
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 \fIs:\fP, that
stdout \fIhello shellia user\fP has been created by this function.
.sp
We will now run the same script with all debug output enabled
to see debug information with the word \fIDEBUG\fP added
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ /usr/share/doc/shellia/examples/hello_world_log \-d 99 \(dqshellia user\(dq
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
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.EE
.UNINDENT
.UNINDENT
.sp
Another way is to start in interactive mode, manually select the function with
\fI2\fP, continue all steps in the function with \fIc\fP and then quit with \fIq\fP\&.
Now also the interactive input and output will be logged and the logfile
will be too large, to display it here.
.SS variable in Interactive\-mode
.sp
If you see \fI$<var>\fP in interactive mode, the meaning is like \fI\e${var}\fP,
but you can press \fBv\fP to see the actual value of the variable.
If you press \fBv\fP again, the name of the variable is shown as before.
.SH NOTES
.sp
\fBshellia\fP is tested successful with \fIbash\fP, \fIdash\fP, \fIbusybox sh\fP, \fImksh\fP and
\fIposh\fP\&.
To use \fBshellia\fP with \fIposh\fP the nounset option (\fIset \-o nounset\fP or
\fIset \-u\fP) is not supported because of Bug #913718 (posh can not use \(dq$@\(dq
together with set \-u). Because of Bug #910275 (posh does never execute an
\(dqEXIT trap\(dq, if it is created with the \(dqtrap\(dq command in a sub shell) remaining
files named \(dq/tmp/shellia.??????????\(dq should be deleted manual, after using
\fBshellia\fP with \fIposh\fP\&.
\fBshellia\fP can not be used in \fIksh\fP, because the shell does not support the
\fIlocal\fP command.
.SH ERROR MESSAGES
.sp
\fBERROR: ia premature exit of\fP \fIcommand\fP
\fBunchecked output:\fP \fIunchecked output\fP
.INDENT 0.0
.INDENT 3.5
Before output of a \fIcommand\fP issued with \fBcheck\-mode\fP can be printed, it
will be collected and checked. If the \fIscript.using.shellia\fP exits premature,
the already collected \fIunchecked output\fP is printed with this error message.
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
shellia(3), shellia(7)
.SH AUTHOR
bernd.schumacher@hpe.com

License: GNU General Public License, version 3
.SH COPYRIGHT
Bernd Schumacher <bernd.schumacher@hpe.com> (2007-2020)
.\" Generated by docutils manpage writer.
.