lib/cmd.tcl

#!/usr/bin/wish

# This file provides shell command procedures cmd_fnc and t_cmd_fnc.

my_source [list print.tcl]


proc cmd_fnc { cmd_buf { quiet {} } { test_mode {} } { print_output {} }\
  { show_err {} } { ignore_err {} } { acceptable_shell_rcs {} } } {

  # Run the given command in a shell and return the shell return code and the
  # output as a 2 element list.

  # Example usage:
  # set result [cmd_fnc "date"].

  # Example output:

  # #(CST) 2018/01/17 16:23:28.951643 -    0.001086 - Issuing: date
  # Mon Feb 19 10:12:10 CST 2018
  # result:
  #   result[0]:                                      0x00000000
  #   result[1]:                                      Mon Feb 19 10:12:10 CST
  # 2018

  # Note: Because of the way this procedure processes parms, the user can
  # specify blank values as a way of skipping parms.  In the following
  # example, the caller is indicating that they wish to have quiet and
  # test_mode take their normal defaults but have print_output be 0.:
  # cmd_fnc "date" "" "" 0

  # Description of argument(s):
  # cmd_buf                         The command string to be run in a shell.
  # quiet                           Indicates whether this procedure should
  #                                 run the print_issuing() procedure which
  #                                 prints "Issuing: <cmd string>" to stdout.
  #                                 The default value is 0.
  # test_mode                       If test_mode is set, this procedure will
  #                                 not actually run the command.  If
  #                                 print_output is set, it will print
  #                                 "(test_mode) Issuing: <cmd string>" to
  #                                 stdout.  The default value is 0.
  # print_output                    If this is set, this procedure will print
  #                                 the stdout/stderr generated by the shell
  #                                 command.  The default value is 1.
  # show_err                        If show_err is set, this procedure will
  #                                 print a standardized error report if the
  #                                 shell command returns non-zero.  The
  #                                 default value is 1.
  # ignore_err                      If ignore_err is set, this procedure will
  #                                 not fail if the shell command fails.
  #                                 However, if ignore_err is not set, this
  #                                 procedure will exit 1 if the shell command
  #                                 fails.  The default value is 1.
  # acceptable_shell_rcs            A list of acceptable shell rcs.  If the
  #                                 shell return code is found in this list,
  #                                 the shell command is considered
  #                                 successful.  The default value is {0}.

  # Set defaults.
  set_var_default quiet [get_stack_var quiet 0 2]
  set_var_default test_mode 0
  set_var_default print_output 1
  set_var_default show_err 1
  set_var_default ignore_err 1
  set_var_default acceptable_shell_rcs 0

  qpissuing $cmd_buf $test_mode

  if { $test_mode } { return [list 0 ""] }

  set shell_rc 0

  if { [ catch {set out_buf [eval exec bash -c {$cmd_buf}]} result ] } {
    set out_buf $result
    set shell_rc [lindex $::errorCode 2]
  }

  if { $print_output } { puts "${out_buf}" }

  # Check whether return code is acceptable.
  if { [lsearch -exact $acceptable_shell_rcs ${shell_rc}] == -1 } {
    # The command failed.
    append error_message "The prior shell command failed.\n"
    append error_message [sprint_var shell_rc "" "" 1]
    if { $acceptable_shell_rcs != 0 } {
      # acceptable_shell_rcs contains more than just a single element equal
      # to 0.
      append error_message "\n"
      append error_message [sprint_list acceptable_shell_rcs "" "" 1]
    }
    if { ! $print_output } {
      append error_message "out_buf:\n${out_buf}"
    }
    if { $show_err } {
      print_error_report $error_message
    }

    if { ! $ignore_err } {
      exit 1
    }

  }

  return [list $shell_rc $out_buf]

}


proc t_cmd_fnc { args } {

  # Call cmd_fnc with test_mode equal to the test_mode setting found by
  # searching up the call stack.  See cmd_fnc (above) for details for all
  # other arguments.

  # We wish to obtain a value for test_mode by searching up the call stack.
  # This value will govern whether the command specified actually gets
  # executed.
  set_var_default test_mode [get_stack_var test_mode 0 2]

  # Since we wish to manipulate the value of test_mode, which is the third
  # positional parm, we must make sure we have at least 3 parms.  We will now
  # append blank values to the args list as needed to ensure that we have the
  # minimum 3 parms.
  set min_args 3
  for {set ix [llength $args]} {$ix < $min_args} {incr ix} {
    lappend args {}
  }

  # Now replace the caller's test_mode value with the value obtained from the
  # call stack search.  It does not matter what value is specified by the
  # caller for test_mode.  It will be replaced.  The whole point of calling
  # t_cmd_fnc is to allow it to set the test_mode.
  set args [lreplace $args 2 2 $test_mode]

  return [cmd_fnc {*}$args]

}