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)