#!/usr/bin/wish

# This file provides many valuable stack inquiry procedures like get_file_proc_names, get_stack_var, etc..

my_source [list print.tcl]


proc get_file_proc_names { file_path { name_regex "" } } {

  # Get all proc names from the file indicated by file_path and return them as a list.

  # Description of argument(s):
  # file_path                       The path to the file whose proc names are to be retrieved.
  # name_regex                      A regular expression to be used to narrow the result to just the desired
  #                                 procs.

  # The first sed command serves to eliminate curly braces from the target file.  They are a distraction to
  # what we are trying to do.
  # TCL proc lines begin with...
  # - Zero or more spaces...
  # - The "proc" keyword...
  # - One or more spaces...
  set proc_regex "^\[ \]*proc\[ \]+"
  set cmd_buf "sed -re 's/\[\\\{\\\}]//g' $file_path | egrep"
  append cmd_buf " '${proc_regex}${name_regex}[ ]' | sed -re"
  append cmd_buf " 's/${proc_regex}(\[^ \]+).*/\\1/g'"
  return [split [eval exec bash -c {$cmd_buf}] "\n"]

}


proc get_stack_var { var_name { default {} } { init_stack_ix 1 } } {

  # Starting with the caller's stack level, search upward in the call stack, for a variable named
  # "${var_name}" and return its value.  If the variable cannot be found, return ${default}.

  # Description of argument(s):
  # var_name                        The name of the variable be searched for.
  # default                         The value to return if the the variable cannot be found.

  for {set stack_ix $init_stack_ix} {$stack_ix <= [info level]} \
      {incr stack_ix} {
    upvar $stack_ix $var_name var_ref
    if { [info exists var_ref] } { return $var_ref }
  }

  return $default

}


proc get_stack_var_level { var_name { init_stack_ix 1 } { fail_on_err 1 } } {

  # Starting with the caller's stack level, search upward in the call stack, for a variable named
  # "${var_name}" and return its associated stack level.  If the variable cannot be found, return -1.

  # Description of argument(s):
  # var_name                        The name of the variable be searched for.
  # init_stack_ix                   The level of the stack where the search should start.  The default is 1
  #                                 which is the caller's stack level.
  # fail_on_err                     Indicates that if the variable cannot be found on the stack, this proc
  #                                 should write to stderr and exit with a non-zero return code.

  for {set stack_ix $init_stack_ix} {$stack_ix <= [info level]} \
      {incr stack_ix} {
    upvar $stack_ix $var_name var_ref
    set stack_level [expr $stack_ix - $init_stack_ix]
    if { [info exists var_ref] } { return $stack_level }
  }

  if { $fail_on_err } {
    append message "Programmer error - Couldn't find variable \"${var_name}\""
    append message " on the stack."
    print_error_report $message
    exit 1
  }

  return -1

}


proc get_stack_proc_name { { level -1 } { include_args 0 } } {

  # Get the name of the procedure at the indicated call stack level and return it.

  # Description of argument(s):
  # level                           The call stack level: 0 would mean this procedure's level (i.e.
  #                                 get_stack_proc_name's level), -1 would indicate the caller's level, etc.
  # include_args                    Indicates whether proc arg values should be included in the result.

  # Set default.
  set_var_default level -1

  if { $include_args } {
    set cmd_buf "set proc_name \[info level $level\]"
  } else {
    set cmd_buf "set proc_name \[lindex \[info level $level\] 0\]"
  }

  if { [ catch $cmd_buf result ] } {
    # The command failed most likely due to being called from "main".
    set proc_name "main"
  }

  return $proc_name

}


proc get_call_stack { { stack_top_ix -1 } { include_args 0 } } {

  # Return the call stack as a list of procedure names.

  # Example:
  # set call_stack [get_call_stack 0]
  # call_stack: get_call_stack calc_wrap_stack_ix_adjust sprint_var sprint_vars print_vars

  # Description of argument(s):
  # stack_top_ix                    The index to the bottom of the stack to be returned.  0 means include the
  #                                 entire stack.  1 means include the entire stack with the exception of
  #                                 this procedure itself, etc.
  # include_args                    Indicates whether proc args should be included in the result.

  set_var_default stack_top_ix -1

  # Get the current stack size.
  set stack_size [info level]
  # Calculate stack_bottom_ix.  Example:  if stack_size is 5, stack_bottom_ix is -4.
  set stack_bottom_ix [expr 1 - $stack_size]
  for {set stack_ix $stack_top_ix} {$stack_ix >= $stack_bottom_ix} \
      {incr stack_ix -1} {
    if { $include_args } {
      set proc_name [info level $stack_ix]
    } else {
      set proc_name [lindex [info level $stack_ix] 0]
    }
    lappend call_stack $proc_name
  }

  return $call_stack

}