Provided by: shellia_5.9_all bug

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)