Be script friendly in your tools output

If your command line tool prints something, make it friendly to shell scripts. This example was sent to me last week:

virsh # pool-list --details --all
Name       State     Autostart  Persistent  Capacity  Allocation  Available
---------------------------------------------------------------------------
default    running   yes        yes          1.79 TB     1.49 TB  304.77 GB
image_dir  running   yes        yes          1.79 TB     1.49 TB  304.77 GB
tmp        inactive  no         yes                -           -          -

And this was my reply:

One good thing, and several bad things about that. The good thing is
that empty columns are presented with ‘-’ which means you can use awk
and sort -k to parse the output columnwise.

The bad things:

  1. Space within fields “1.79 TB” (awk / sort -k in fact won’t work).
  2. Numeric fields aren’t numbers: You can’t sort -n on “1.79 TB”, and you can’t read that number into a script and do math on it. Most tools have a “-h” or “–human” option in order to generate human-readable numbers (without spaces), but default to just printing the raw numbers.
  3. Unnecessary “——-” line.
  4. Title line should be optional. Have a –no-title option or something like that to suppress it.
  5. Does virsh still print an unnecessary blank line after the output? If so, stop doing that.

In tools like virt-df we also provide CSV format output. CSV is a fine format for two-dimensional output, but beware the caveats.

About these ads

3 Comments

Filed under Uncategorized

3 responses to “Be script friendly in your tools output

  1. John Levon

    Totally disagree. Make your output friendly to humans. Add a –parseable option for computers (and insist on also specifying –output-fields or whatever). Don’t try to do both; it will most likely be a disaster.

    • rich

      You’re assuming that (can be parsed) XOR (friendly to humans). I don’t think any of the things I suggested would have made the output less friendly to humans.

      The problem with machine-readable output, and also with CSV output, is that you have a separate and less-used code path, one which is more likely to bit rot. To see what I mean, try the “-m” option in parted some time.

  2. Good points. Note `sort` recently got the -h option to sort 1.79TB etc. (without spaces).

    Note also that one can align output for human consumption external to each tool, with `column`. Consider: mount | column -t

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s