Subject: [RFC PATCH 0/1] bdl-lib.sh: add bash debug logger

From: Wink Saville <[email-masked]>
Date: Tue, 27 Mar 2018 17:15:34 -0700

Add bdl-lib.sh which provides functions to assit in debugging git
shell scripts and tests. The primary public interace are two routines,
bdl and bdl_nsl which print strings. The difference between the two
is that bdl outputs location of the statement optionally followed by
a string to print. For example:

  $ cat -n bdl-exmpl1.sh
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  bdl "hi"
       4  
       5  # If no parameters just the location is printed
       6  bdl
  $ ./bdl-exmpl1.sh 
  bdl-exmpl1.sh:3: hi
  bdl-exmpl1.sh:6:

bdl_nsl means bdl with no source location being printed and at least
one parameter is required. For example:

  $ cat -n bdl-exmpl2.sh 
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  bdl_nsl "hi"
       4	
       5  # If no parameters nothing is printed
       6  bdl_nsl
  $ ./bdl-exmpl1.sh 
  hi

These routines can also take two parameters where the first parameter is
the destination for the string. There are two types of destinations,
either a single digit file descriptor 1..9 or a file name. For example:

  $ cat -n bdl-exmpl3.sh
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  
       4  # Output to STDOUT
       5  bdl_nsl 1 "hi there"
       6  
       7  # Map 5 to STDOUT
       8  exec 5>&1
       9  bdl 5 "yo dude"
      10  
      11  # Output to a file
      12  bdl bdl_out.txt "good bye!"
      13  cat bdl_out.txt
      14  rm bdl_out.txt
  $ ./bdl-exmpl3.sh 
  hi there
  bdl-exmpl3.sh:9: yo dude
  bdl-exmpl3.sh:12: good bye!

If a destination is not provided as a parameter than there are two
variables, bdl_dst and bdl_stdout, that can be used to provide a
defaults. With bdl_dst taking presedence over bdl_stdout and a
destination parameter taking presedence over the variables. For example:

  $ cat -n bdl-exmpl4.sh 
       1  #!/usr/bin/env bash
       2  . bdl-lib.sh
       3  
       4  # Set defaults with bdl_dst taking presedence
       5  bdl_dst=bdl_dst_out.txt
       6  bdl_stdout=5
       7  
       8  bdl_nsl "printed by bdl_nsl to bdl_dst_out.txt"
       9  bdl "printed by bdl to bdl_dst_out.txt"
      10  
      11  # But the parameter the ultimate presedence
      12  bdl bdl_out.txt "good bye to bdl_out.txt"
      13  
      14  cat bdl_dst_out.txt
      15  cat bdl_out.txt
      16  
      17  rm bdl_dst_out.txt
      18  rm bdl_out.txt
      19  
      20  # Now clear bdl_dst and bdl_stdout takes presedence
      21  # but parameters take presedence
      22  bdl_dst=
      23  exec 5>&1
      24  
      25  bdl_nsl "monkeys via 5"
      26  bdl 1 "horses via 1"
      27  bdl bdl_out.txt "orcas to bdl_out.txt"
      28  
      29  cat bdl_out.txt
      30  rm bdl_out.txt
  $ ./bdl-exmpl4.sh 
  printed by bdl_nsl to bdl_dst_out.txt
  bdl-exmpl4.sh:9: printed by bdl to bdl_dst_out.txt
  bdl-exmpl4.sh:26: orcas to bdl_out.txt
  bdl-exmpl4.sh:12: good bye to bdl_out.txt
  monkeys via 5
  bdl-exmpl4.sh:26: horses via 1
  bdl-exmpl4.sh:27: orcas to bdl_out.txt

TODO: More tests and documentation needed.

Wink Saville (1):
  bdl-lib.sh: add bash debug logger

 bdl-exmpl.sh       |  46 ++++++++++++
 bdl-lib.sh         | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 t/t0014-bdl-lib.sh | 115 ++++++++++++++++++++++++++++
 t/test-lib.sh      |   4 +
 4 files changed, 380 insertions(+)
 create mode 100755 bdl-exmpl.sh
 create mode 100644 bdl-lib.sh
 create mode 100755 t/t0014-bdl-lib.sh

-- 
2.16.3