Finding Out What a Tool Command Does

Part II · Module 17 · Chapter 17.6 · Finding Out What a Tool Command Does

Here is how most flow scripts acquire their options. Someone needs a command, finds a colleague's script that uses it, copies the line including its flags, and it works. The flags are never looked up — by them, or by the next person, or by anyone for the following five years.

It works right up until it does not, and then nobody can say what the options were for.

This chapter is about the other habit. It is a short chapter because the techniques are short.

1. The tool's own reference

Tools built on Tcl generally provide help from inside the session — often a help command, often integrated manual pages, usually a searchable HTML reference as well. The exact names and syntax differ by vendor, and I am not going to guess at them: a confidently wrong help command is worse than none, because you would type it rather than check.

Find yours once:

• Type help at the prompt and see what happens. Then try help help.
• info commands *help*, info commands *man* — the discovery technique from Chapter 17.1 §3.
• Look for a documentation command in the GUI's Help menu, and read the command it logs — Chapter 17.3.
• The installation ships a reference directory. Find it once and bookmark it.

Five minutes, once per tool, and you stop guessing permanently.

2. What copying a flag does not tell you

When you lift -foo from somebody's script, four things stay unknown:

• What it does. Obviously.
• Whether it is still needed. It may have worked around a bug fixed three releases ago.
• What it costs. Some options change runtime or memory substantially.
• What the default would have been. Often the flag is setting the default explicitly, and is simply noise.

The last two matter most. An option copied into a hundred scripts because one person needed it once is a real and common form of technical debt.

3. Make a command list its own options

This works on any Tcl ensemble — a command with subcommands — and it is the fastest reference there is, because it cannot be out of date.

Ask for a subcommand that does not exist, and the error enumerates the real ones:

foreach ens {string file array dict info namespace clock} {
    catch {$ens __bogus__} e
    puts "  $ens: [lindex [split $e "\n"] 0]"
}

  string:
    unknown or ambiguous subcommand "__bogus__": must be bytelength, compare, equal, first, index, is, last, length, map, match, range, repeat, replace, re
  file:
    bad option "__bogus__": must be atime, attributes, channels, copy, delete, dirname, executable, exists, extension, isdirectory, isfile, join, link, lst
  dict:
    unknown or ambiguous subcommand "__bogus__": must be append, create, exists, filter, for, get, incr, info, keys, lappend, merge, remove, replace, set, 
  info:
    unknown or ambiguous subcommand "__bogus__": must be args, body, cmdcount, commands, complete, default, exists, frame, functions, globals, hostname, le
  namespace:
    bad option "__bogus__": must be children, code, current, delete, ensemble, eval, exists, export, forget, import, inscope, origin, parent, path, qualifi
  clock:
    unknown or ambiguous subcommand "__bogus__": must be add, clicks, format, microseconds, milliseconds, scan, or seconds

This is Chapter 14.10 §7's trick, and it applies directly to a tool's own ensembles — including the gamma-style design name / design cells shapes from Chapter 17.5 §2.

4. Read the source of a Tcl-level command

Many commands you will meet are not the vendor's at all — they are procedures your site or a previous engineer wrote, usually with no documentation. For those, the source is the reference, and Chapter 14.10 §4 gets it:

puts "  info args find_instances    : [info args find_instances]"
puts "  info body find_instances    :"

  info args find_instances    : args
  info body find_instances    :
      set pat "*"
      for {set i 0} {$i < [llength $args]} {incr i} {
      if {[lindex $args $i] eq "-pattern"} { set pat [lindex $args [expr {$i+1}]] ; incr i }
      }
      set o {} ; foreach c $::b::cells { if {[string match $pat $c]} { lappend o $c } } ; return $o

info args said only args, which tells you nothing — it is variadic. The body tells you what it actually accepts: a -pattern option, and nothing else. That is how you discover an undocumented procedure's interface in thirty seconds.

Three commands, worth committing to memory:

Remember from Chapter 14.10 §4 that these work only on Tcl procedures. A vendor command implemented in C has no body to read — info procs will not find it, and you are back to the tool's reference.

5. Write the help you wish you had found

If your team ships site procedures, give them a help facility. It costs about fifteen lines and it is built from the same introspection:

namespace eval ::help { variable text }

proc describe {name summary} { set ::help::text($name) $summary }

proc help {{pattern *}} {
    foreach n [lsort [array names ::help::text $pattern]] {
        puts "  $n"
        puts "      $::help::text($n)"
        if {[llength [info procs $n]]} {
            set sig {}
            foreach a [info args $n] {
                if {[info default $n $a d]} { lappend sig "?$a?" } else { lappend sig $a }
            }
            puts "      usage: $n [join $sig { }]"
        }
    }
}

proc worst_slack {reports {limit 0.0}} { ... }
proc count_cells  {pattern} { ... }

describe worst_slack "Return the worst slack across the given report files."
describe count_cells  "Count instances whose name matches a glob pattern."

  help:
  count_cells
      Count instances whose name matches a glob pattern.
      usage: count_cells pattern
  worst_slack
      Return the worst slack across the given report files.
      usage: worst_slack reports ?limit?

  help worst*:
  worst_slack
      Return the worst slack across the given report files.
      usage: worst_slack reports ?limit?

Note where the usage lines came from: nobody typed them. info args supplied the parameter names and info default marked ?limit? as optional — the ?x? convention from Chapter 14.7 §4, generated rather than written. A signature produced this way cannot drift out of date, because it is read from the procedure itself.

The only hand-written part is the one-line summary, which is the part a machine cannot infer.

6. The habit

Three rules, and they are the whole chapter:

Look it up the first time. Before a command goes into a script you will keep, spend a minute on its reference. Note what the non-default options do.

Explain the non-obvious ones. A short comment next to a surprising flag saves the next person the same minute, and saves them from deleting something load-bearing:

# -hierarchical: the default searches the current level only, and the
# sub-blocks are where the sequential cells live.
set cells [get_cells -hierarchical *_reg*]

Delete what nobody can explain. If an option has no comment, no one remembers why it is there, and removing it changes nothing in a test run — remove it. Options accumulate otherwise, and every one is a thing the next reader has to wonder about.

7. Exercises

Exercise 1. Name two things that stay unknown when you copy a flag from someone else's script.

Exercise 2. How do you make a Tcl ensemble list its valid subcommands?

Exercise 3. That trick gave wrong # args instead of a list. What happened, and what do you do?

Exercise 4. A site procedure's info args says only args. How do you find out what options it accepts?

Exercise 5. Why does info body not help for a vendor command?

Exercise 6. In the generated help, where did ?limit? come from?

Exercise 7. You find an option in an inherited script that nobody can explain and whose removal changes nothing. What should you do?