Provided by: shellia_5.9_all bug

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)