kiekiam Files

KIEKIAM (wherewhen in esperanto).
A (ba|z)sh script that:

  - calls and external command to execute,
  - logs to a stream or file its stdout && stderr,
  - possibly timestamps and/or tags logged output
    and/or original console streams,
  - displays those outputs to console with no lag.

Released under GPLv3 licence by kAbaÏaKH.

Depends upon bash+date+tee, or only zsh.
Faster using zsh (see notes/fa*stness)
but also more reliable since its read method
does not trim its input (see notes/mi*sread).
Z's seldom available, alas, on production servers.

Launch script without any argument to see its usage.
If installed in a directory from $PATH:

  $ kiekiam

Force to be run with bash or zsh.
Replace ${path_to} with your own installation directory,
(or set path_to with the suitable value):

  $ bash ${path_to}kiekiam

  $ zsh ${path_to}kiekiam

For purposes of example, a dummy external command to execute:

  $ cat eligokajeraro
  date +"out %H:%M:%S" # with a space
  sleep 1
  date +"err	%H%M%S" >&2 # with a tab

  $ sh eligokajeraro
  out 22:33:09
  err	223310
  
Simpliest call. Default values for everything.
No argument on command line, only the command to execute.
Stream &3 must be redirected to file "log".
Notice that the two lines appears as soon as produced
by external command (with a one second delay between).

  $ kiekiam eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

  [==================][][=][][===============]
                     | |  | |                |
   timestamp field --+ |  | |                |
         delimiter ----+  | |                |
        stream tag -------+ |                |
         delimiter ---------+                |
        input line --------------------------+

Change timestamp format.

  $ kiekiam -t "%c" eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  Thu Nov 29 22:33:09 1973: OUT: out 22:33:09
  Thu Nov 29 22:33:10 1973: ERR: err	223310

Use UTC time with a specific format.
For both -t and -u options, some non-strftime(3) date(1)'s
sequences are available, even when using zsh, namely:
'%:z', '%::z' and '%:::z'.

  $ kiekiam -u "%F %T%:z" eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  1973-11-29 21:33:09+00:00: OUT: out 22:33:09
  1973-11-29 21:33:10+00:00: ERR: err     223310

Change output and error stream tags.
Make stdout tag green and stderr red
with ANSI terminal escape sequences.

  $ kiekiam -o "\e[32mout\e[39m" -e "\e[31merr\e[39m" eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

Change default field selection and order.
Here without timestamping, will be way faster with heavily
verbose external command outputs (see notes/fa*stness).

  $ kiekiam -f is eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  out 22:33:09: OUT
  err	223310: ERR

Change delimiter to a tabulation,
using an echo escape sequence.

  $ kiekiam -d "\t" eligokajeraro 3>log
  out 22:33:09
  err	223310

  $ cat log
  19731129T223309+0100	OUT	out 22:33:09
  19731129T223310+0100	ERR	err	223310

Change stream selection.
Tag both console and log destination.

  $ kiekiam -s cl eligokajeraro 3>log
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

  $ cat log
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

Can also tag only console and drop log destination.
Log destination will be built but dumped to /dev/null,
which is a non optimized way.

  $ rm -f log

  $ kiekiam -s c eligokajeraro 3>/dev/null
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

  $ cat log
  cat: log: No such file or directory

Select log destination from options on command line,
not with stream redirection.

  $ cat log
  19700101T010000+0100: OUT: out 01:00:00
  19700101T010001+0100: ERR: err	010001

  $ kiekiam -l log eligokajeraro
  out 22:33:09
  err	223310

  $ cat log
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

Append to the log destination
but only if it is a file.

  $ cat log
  19700101T010000+0100: OUT: out 01:00:00
  19700101T010001+0100: ERR: err	010001

  $ kiekiam -a log eligokajeraro
  out 22:33:09
  err	223310

  $ cat log
  19700101T010000+0100: OUT: out 01:00:00
  19700101T010001+0100: ERR: err	010001
  19731129T223309+0100: OUT: out 22:33:09
  19731129T223310+0100: ERR: err	223310

Return codes with examples causing them:

  0: No error with kiekiam, but no information about executed command.
     $ kiekiam command 3>log

  1: A character is not 't' (time), 's' (stream) or 'i' (input) within field selection.
     $ kiekiam -f ck command 3>log

  2: Missing at least one 'i' (input) within field selection.
     $ kiekiam -f ts command 3>log

  3: A character is not 'c' (console) or 'l' (log) within streams selection.
     $ kiekiam -s h command 3>log

  4: Log destination is ampersand-prefixed but out of range &3 to &8.
     $ kiekiam -l "&2" command 

  5: Trying to append to a stream.
     $ kiekiam -a "&3" command 

  6: Unknow error in kiekiam option parsing from command line.
     $ kiekiam -z command 3>log

  7: Log stream is not opened.
     $ kiekiam command

  8: Unable to write to log destination file.
     $ kiekiam -l /tmp command

  9: No command to execute was given.
     $ kiekiam -l /dev/null