db2c 0.0.4 → 1.0.0

data/man/db2c.1.ronn

@@ -3,7 +3,7 @@ db2c(1) - A DB2 console with with history and autocomplete support, and few othe
 
 ## SYNOPSIS
 
-`db2c` <[options]>
+`db2c` [<options>] [dbname]
 
 ## DESCRIPTION && EXAMPLES
 
@@ -27,32 +27,61 @@ DB2 console mode does not support readline and autocomplete, this is a wrapper f
     db2(testdb) => select * from xyz.tab[double-tab]
     </pre>
 
-  * **You can pipe**:
-    <pre>
-    db2(testdb) => select * from large.table | grep -v something
-    db2(testdb) => select * from large.table | less
-    </pre>
-
   * For example, if a command outputs long lines, **less -S** is your friend:
     <pre>
     db2(testdb) => select * from table.with.many.columns | less -S
     (you can scorll horizontally with left/right arrows)
     </pre>
 
-  * You can use _some psql-like_ commands
+  * **You can edit last statement or use the editor to write a new multiline statement**:
+    <pre>
+    db2(testdb) => edit
+    db2(testdb) => emacs
+    </pre>
+
+  * **Any !command will be sent to the shell as is**:
+    <pre>
+    db2(testdb) => !clear
+    </pre>
+
+  * You can use _some_ common shell commands directly:
+    <pre>
+    db2(testdb) => ls ~
+    db2(testdb) => less ~/somefile
+    db2(testdb) => top
+    db2(testdb) => irb
+    </pre>
+
+  * You can use _some psql-like_ meta commands
     <pre>
-    db2(testdb) => **\d schema.table**
-      == describe table schema.table
     db2(testdb) => **\h**
       == To see this help from within the console
+    db2(testdb) => **\l**
+      == list database directory
+    db2(testdb) => **\lt [all|schema]**
+      == list tables for all or one schema using db2 list command
+    db2(testdb) => **\l[t|v|a|s] [schema]**
+      == list tables|views|aliases|summary-tables for all or one schema using syscat.tables
+    db2(testdb) => **\d schema.table**
+      == describe table schema.table
     db2(testdb) => **\q**
     </pre>
 
+  * **You can pipe**:
+    <pre>
+    db2(testdb) => \dv | grep -v SYS
+    db2(testdb) => select * from large.table | less
+    </pre>
+
+
 ## OPTIONS
 
   * `-h`, `--help`, `--man`:
     Displays this help page.
 
+  * `-t`:
+   Commands will be executed when you enter a terminating semicolon (;)
+
   * `--debug`:
     Displays annoying messages.
 

data/rlwrap/filters/RlwrapFilter.pm

@@ -0,0 +1,816 @@
+package RlwrapFilter;
+
+use strict;
+use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
+
+sub when_defined($@);
+my $previous_tag = -1;
+my $last_cumulative_output = "";
+
+require Exporter;
+require AutoLoader;
+@ISA = qw(Exporter AutoLoader);
+
+@EXPORT = qw(TAG_INPUT TAG_OUTPUT TAG_HISTORY TAG_COMPLETION TAG_PROMPT);
+$VERSION = '0.01';
+
+use Carp;
+
+# constants for every tag we know about
+use constant TAG_INPUT                         => 0;
+use constant TAG_OUTPUT                        => 1;
+use constant TAG_HISTORY                       => 2;
+use constant TAG_COMPLETION                    => 3;
+use constant TAG_PROMPT                        => 4;
+use constant TAG_IGNORE                        => 251;
+use constant TAG_ADD_TO_COMPLETION_LIST        => 252;
+use constant TAG_REMOVE_FROM_COMPLETION_LIST   => 253;
+use constant TAG_OUTPUT_OUT_OF_BAND            => 254;
+use constant TAG_ERROR                         => 255;
+
+use constant REJECT_PROMPT                    => "_THIS_CANNOT_BE_A_PROMPT_";
+
+# we want to behave differently when running outside rlwrap
+my $we_are_running_under_rlwrap = defined $ENV{RLWRAP_COMMAND_PID};
+
+
+# die() and warn() must communicate via rlwrap, not via STDERR
+$SIG{__DIE__}  = \&die_with_error_message;
+$SIG{__WARN__} = \&warn_with_info_message;
+
+# automagically have a setter/getter for every key of %$self
+sub AUTOLOAD {
+  my $self = shift;
+  my $type = ref($self)
+    or croak "$self is not an object";
+
+  my $name = $AUTOLOAD;
+  $name =~ s/.*://;             # strip fully-qualified portion
+
+  unless (exists $self->{$name} ) {
+    croak "There is no `$name' setter/getter in class $type";
+  }
+
+  if (@_) {
+    return $self->{$name} = shift;
+  } else {
+    return $self->{$name};
+  }
+}
+
+# open communication lines with rlwrap (or with the terminal when not running under rlwrap)
+if ($we_are_running_under_rlwrap) {
+
+  open CMD_IN,     ">&" . $ENV{RLWRAP_MASTER_PTY_FD};
+  open CMD_OUT,    "<&" . $ENV{RLWRAP_MASTER_PTY_FD};
+
+  open FILTER_IN,  "<&" . $ENV{RLWRAP_INPUT_PIPE_FD};
+  open FILTER_OUT, ">&" . $ENV{RLWRAP_OUTPUT_PIPE_FD};
+} else {
+  open CMD_IN,     ">&STDOUT";
+  open CMD_OUT,    "<&STDIN";
+
+  open FILTER_IN,  "<&STDIN";
+  open FILTER_OUT,  ">&STDOUT";
+}
+
+
+# create filter object
+sub new {
+  my ($this, %init) = @_;
+  my $class = ref($this) || $this;
+  my $self = {};
+  my @accessors = qw(initialiser help_text input_handler
+		   output_handler prompt_handler echo_handler
+		   message_handler history_handler completion_handler
+		   echo_handler message_handler cloak_and_dagger_verbose
+		   cumulative_output prompts_are_never_empty
+		   minimal_rlwrap_version);
+  foreach my $acc (@accessors) {
+    $self->{$acc} = "";
+  }
+  bless $self, $class;
+  foreach my $key (keys %init) {
+    croak "There is no `$key' attribute in class $class" unless defined $self->{$key};
+    $self -> {$key} = $init{$key};
+    $self -> minimal_rlwrap_version($self->{$key}) if $key eq "minimal_rlwrap_version";
+  }
+  return $self;
+}
+
+
+
+# event loop
+sub run {
+    my ($self) = @_;
+
+    if($ENV{RLWRAP_COMMAND_PID} == 0) { # when called as rlwrap -z <filter> (with no command) ..
+      write_message(TAG_OUTPUT_OUT_OF_BAND, $self -> help_text . "\n"); # ... send help text
+    }
+
+    while(1) {
+	my ($tag, $message) = read_message();
+
+        $message = when_defined $self -> message_handler, "$message", $tag; # ignore return value
+	my $response;
+
+	if ($tag == TAG_INPUT) {
+	  $response = when_defined $self -> input_handler, "$message";
+	} elsif ($tag == TAG_OUTPUT) {
+	  $response = $self -> handle_output($message);
+	} elsif ($tag == TAG_HISTORY) {
+	  $response = when_defined $self -> history_handler, "$message";
+	} elsif ($tag == TAG_COMPLETION) {
+	  my ($line, $prefix, $completions, @completions);
+	  if ($self -> completion_handler) {
+	    $message =~ s/[ ]+$//; # eat final space
+	    ($line, $prefix, $completions) = split /\t/, $message;
+	    @completions = split / /, $completions;
+	    @completions = &{$self -> completion_handler}($line, $prefix, @completions);
+	    $response = "$line\t$prefix\t". (join ' ', @completions) . " ";
+	  } else {
+	    $response = $message;
+	  }
+	} elsif ($tag == TAG_PROMPT) {
+	  if ($message eq REJECT_PROMPT or
+	      ($self -> {prompts_are_never_empty} and $message eq "")) {
+			write_message($tag,REJECT_PROMPT);
+			# don't update <previous_tag> and don't reset <cumulative_input>
+			next;
+		}
+	  $self->{cumulative_output} =~ s/(?<![^\n])[^\n]*$// #  s/[^\n]*$// takes way too long on big strings, what is the optimal regex to do this?
+            if $ENV{RLWRAP_IMPATIENT}; # chop off prompt from cumulative_output
+
+	  $response = when_defined $self -> prompt_handler, "$message";
+	  croak "prompts may not contain newlines!" if $response =~ /\n/;
+	} else {
+	  $response = $message; # No error message, compatible with future rlwrap
+	                        # versions that may define new tag types
+	}
+
+	unless (out_of_band($tag) and ($tag == TAG_PROMPT and $response eq REJECT_PROMPT)) {
+          $self -> {previous_tag} = $tag;
+          $self -> {previous_message} = $message;
+        }
+	write_message($tag, $response);
+
+    }
+}
+
+
+# when_defined \&f, x, y, ... returns f(x, y, ...) if f is defined, x otherwise
+sub when_defined($@) {
+  my $maybe_ref_to_sub = shift;
+  local $_ =  $_[0] ; # convenient when using anonymous subs as handlers: $filter -> blah_handler(sub{$_ if /blah/});
+  if ($maybe_ref_to_sub) {
+    if ((my $type  = ref($maybe_ref_to_sub))  ne 'CODE') {
+      croak "improper handler <$maybe_ref_to_sub> of type $type (expected a ref to a sub)";
+    }
+    return &{$maybe_ref_to_sub}(@_);
+  } else {
+    return $_;
+  }
+}
+
+sub out_of_band {
+  my($tag) = @_;
+  return $tag > 128;
+}
+
+# split output in echo and the rest and call the appropriate handlers on them
+sub handle_output {
+  my ($self, $message) = @_;
+  my ($echo, $handled_echo, $sep);
+  if (defined $self -> {previous_tag} and $self -> {previous_tag} == TAG_INPUT) {
+      $self->{cumulative_output} = "";
+    ($echo, $sep, $message) = ($message =~ /^([^\n\r]*)(\r?\n)?(.*)?/s); #@@@ This doesn't work for multi-line input!
+    $handled_echo = when_defined $self -> echo_handler, "$echo";
+  }
+  $self->{cumulative_output} .= $message;
+  return $handled_echo . $sep .(when_defined $self -> output_handler, "$message");
+}
+
+sub read_until { # read chunks from pty pointed to by $fh until either inactive for $timeout or
+                 # $stoptext is seen at end-of-chunk
+  my ($fh, $stoptext, $timeout) = @_;
+  my ($res);
+  while (1){
+    my $chunk = read_chunk($fh, $timeout);
+    return $res unless $chunk; # got "" back: timeout
+    $res .= $chunk;
+    return $res if $res =~ /$stoptext$/;
+  }
+}
+
+
+# read chunk from pty pointed to by $fh with timeout $timeout
+sub read_chunk {
+  my ($fh, $timeout) = @_;
+  my ($rin, $rout, $chunk);
+  vec($rin, fileno($fh), 1) = 1;
+  my ($nfound, undef) = select($rout=$rin, undef, undef, $timeout);
+  if ($nfound > 0) {
+    my $nread = sysread($fh, $chunk, 256);
+    if ($nread > 0) {
+      return $chunk;
+    }
+  }
+  return "";
+}
+
+
+# keep reading until $count total bytes were read from filehandle $fh
+sub read_patiently {
+  my($fh, $count) = @_;
+  my $already_read = 0;
+  my $result;
+  while($already_read < $count) {
+    my $nread = sysread($fh, $result, $count-$already_read, $already_read);
+    if ($nread == 0) {
+      exit 0;
+    } elsif ($nread < 0) {
+      die_with_errormessage("error reading: $!");
+    }
+    $already_read += $nread;
+  }
+  return $result;
+}
+
+# keep writing until all bytes from $buffer were written to $fh
+sub write_patiently {
+  my($fh, $buffer) = @_;
+  my $already_written = 0;
+  my $count = length($buffer);
+  while($already_written < $count) {
+    my $nwritten = syswrite($fh, $buffer, $count-$already_written, $already_written);
+    if ($nwritten <= 0) {
+      die_with_errormessage("error writing: $!");
+    }
+    $already_written += $nwritten;
+  }
+}
+
+
+# read message (tag, length word and contents) from FILTER_IN
+sub read_message {
+  return read_from_stdin() unless $we_are_running_under_rlwrap;
+
+  my $tag = unpack("C", read_patiently(*FILTER_IN,1));
+  my $length = unpack("L",read_patiently(*FILTER_IN,4));
+  my $message = read_patiently(*FILTER_IN, $length);
+  $message =~ s/\n$//;
+  return ($tag, $message);
+}
+
+
+sub write_message {
+  my($tag, $message) = @_;
+  return write_to_stdout($tag, $message) unless $we_are_running_under_rlwrap;
+
+  $message ||= ""; # allow undefined messages
+
+  write_patiently(*FILTER_OUT, pack("C", $tag));
+  write_patiently(*FILTER_OUT, pack("L", (length $message) + 1));
+  write_patiently(*FILTER_OUT, "$message\n");
+}
+
+sub read_from_stdin {
+  my ($tag, $prompt, $tagname, $message);
+  while (not defined $tag) {
+    print $prompt;
+    ($tagname, $message) = (<STDIN> =~ /(\S+) (.*?)\r?\n/);
+    exit unless $tagname;
+    $tag = name2tag(undef, $tagname); # call as function, not method
+    $prompt = "again > ";
+  }
+  return ($tag, $message)
+}
+
+sub write_to_stdout {
+  my($tag, $message) = @_;
+  print tag2name(undef, $tag) . " $message\n";
+}
+
+
+sub add_to_completion_list {
+  my ($self, @words) = @_;
+  write_message(TAG_ADD_TO_COMPLETION_LIST, join(' ', @words));
+}
+
+sub remove_from_completion_list {
+  my ($self, @words) = @_;
+  write_message(TAG_REMOVE_FROM_COMPLETION_LIST, join(' ', @words));
+}
+
+
+sub cwd {
+  my ($self) = @_;
+  my $command_pid = $ENV{RLWRAP_COMMAND_PID};
+  my $pwd = "/proc/$command_pid/cwd";
+  croak  "cannot read commands working directory as $pwd doesn't exist" unless -e $pwd;
+  return (-l $pwd ? readlink ($pwd) : $pwd);
+}
+
+
+
+# have a private chat with the rlwrapped command. This relies very much om the assumption that command stops
+# talking, and only listens, when it has displayed the $prompt
+sub cloak_and_dagger {
+  my ($self, $question, $prompt, $timeout) = @_;
+  $prompt ||= $self -> last('prompt');
+  write_patiently(*CMD_IN, "$question\n");
+  $self -> send_output_oob("cloak_and_dagger question: $question\n") if $self -> {cloak_and_dagger_verbose};
+  my $response = read_until(*CMD_OUT, $prompt, $timeout);
+  $response =~ s/.*?\n//; # chop off echoed question;
+  $response =~ s/$prompt$//; # chop off prompt;
+  $self -> send_output_oob("cloak_and_dagger response: $response\n") if $self -> {cloak_and_dagger_verbose};
+  return $response;
+}
+
+
+
+sub tag2name {
+  my ($self, $tag) = @_;
+  for my $name (qw(TAG_REMOVE_FROM_COMPLETION_LIST TAG_ADD_TO_COMPLETION_LIST TAG_INPUT TAG_PROMPT TAG_COMPLETION
+		   TAG_HISTORY TAG_OUTPUT_OUT_OF_BAND TAG_ERROR  TAG_IGNORE TAG_OUTPUT)) {
+    return $name if (eval "$tag == $name");
+  }
+  croak "unknown tag $tag";
+}
+
+sub name2tag {
+  my ($self, $name ) = @_;
+  my $tag = eval uc $name;
+  #croak "unknown tagname $name " if $@;
+  return $tag;
+}
+
+sub send_output_oob {
+  my ($self, $text) = @_;
+  write_message(TAG_OUTPUT_OUT_OF_BAND, $text);
+}
+
+
+
+sub  send_ignore_oob {
+  my ($self, $text) = @_;
+  write_message(TAG_IGNORE, $text);
+}
+
+sub die_with_error_message {
+  die $@ if $^S; # make die() within eval do the right thing
+  my ($error_message) = @_;
+  my $myself = $0;
+  $myself =~ s#^.*/([^.]+)$#$1#;
+  write_message(TAG_ERROR, "$myself: $error_message");
+  sleep 2;
+  exit 1;
+}
+
+
+sub warn_with_info_message {
+  my ($warning) = @_;
+  my $myself = $0;
+  $myself =~ s#^.*/([^.]+)$#$1#;
+  write_message(TAG_OUTPUT_OUT_OF_BAND, "$myself: $warning");
+
+}
+
+sub minimal_rlwrap_version {
+  my ($self, $wanted) = @_;
+  my $found = $ENV{RLWRAP_VERSION} || "0.34";
+  die "This filter requires rlwrap version $wanted or newer!\n"
+    unless !$we_are_running_under_rlwrap or $wanted le $found;
+}
+
+
+sub command_line {
+  my $commandline = $ENV{RLWRAP_COMMAND_LINE};
+  return (wantarray ? split /\s+/, $commandline : $commandline);
+}
+
+sub running_under_rlwrap {
+  return $we_are_running_under_rlwrap;
+}
+
+sub prompt_rejected {
+  my ($self) = @_;
+  $self->minimal_rlwrap_version("0.35");
+  return REJECT_PROMPT;
+}
+
+sub name {
+  my ($name) = ($0 =~ m#([^/]+)$#);
+  $name ||= $0;
+  return $name;
+}
+
+
+1
+
+__END__
+
+
+=head1 NAME
+
+RlwrapFilter - Perl class for B<rlwrap> filters
+
+=head1 SYNOPSIS
+
+  use lib $ENV{RLWRAP_FILTERDIR};
+  use RlwrapFilter;
+
+  $filter = new RlwrapFilter;
+
+  $filter -> output_handler(sub {s/apple/orange/; $_}); # re-write output
+  $filter -> prompt_handler(\&pimp_the_prompt); # change prompt
+  $filter -> history_handler(sub {s/with password \w+/with password ****/; $_}); # keep passwords out of history
+
+  $filter -> run;
+
+=head1 DESCRIPTION
+
+B<rlwrap> (1) (L<http://utopia.knoware.nl/~hlub/uck/rlwrap>) is a tiny
+utility that sits between the user and any console command, in order
+to bestow readline capabilities (line editing, history recall) to
+commands that don't have them.
+
+Since version 0.32, rlwrap can use filters to script almost every
+aspect of rlwrap's interaction with the user: changing the history,
+re-writing output and input, calling a pager or computing completion
+word lists from the current input.
+
+B<RlwrapFilter> makes it very simple to write rlwrap
+filters in perl. A filter only needs to instantiate a RlwrapFilter
+object, change a few of its default handlers and then call its 'run'
+method.
+
+=head1 PUBLIC METHODS
+
+=head2 CONSTRUCTOR
+
+=over 4
+
+=item $f = new RlwrapFilter
+
+=item $f = RlwrapFilter -> new(prompt_handler => sub {"Hi! > "}, minimal_rlwrap_version => "0.35", ...)
+
+Return a new RlwrapFilter object.
+
+=back
+
+=head2 SETTING/GETTING HANDLERS
+
+Handlers are user-defined callbacks that get called from the
+'run' method with a message  (i.e. the un-filtered input,
+output, prompt) as their first argument. For convenience, $_ is set to the same
+value. They should return the re-written message text. They get called
+in a fixed cyclic order: prompt, completion, history, input, echo,
+output, prompt, ... etc ad infinitum. Rlwrap may always skip a handler when in direct mode,
+on the other hand, completion and output handlers may get called more
+than once in succession. If a handler is left undefined, the result is
+as if the message text were returned unaltered.
+
+It is important to note that the filter, and hence all its handlers,
+are bypassed when I<command> is in direct mode, i.e. when it asks for
+single keystrokes (and also, for security reasons, when it doesn't
+echo, e.g. when asking for a password). If you don't want this to happen, use
+B<rlwrap -a> to force B<rlwrap> to remain in readline mode and to
+apply the filter to I<all> of I<command>'s in- and output. This will
+make editors and pagers (which respond to single keystrokes) unusable,
+unless you use rlwrap's B<-N> option (linux only)
+
+
+The getters/setters for the respective handlers are listed below:
+
+=over 4
+
+
+
+=item $handler = $f -> prompt_handler, $f -> prompt_handler(\&handler)
+
+The prompt handler re-writes prompts and gets called when rlwrap
+decides it is time to "cook" the prompt, by default some 40 ms after
+the last output has arrived. Of course, B<rlwrap> cannot read the mind
+of I<command>, so what looks like a prompt to B<rlwrap> may actually
+be the beginning of an output line that took I<command> a little
+longer to formulate. If this is a problem, specify a longer "cooking"
+time with rlwrap's B<-w> option, use the B<prompts_are_never_empty>
+method or "reject" the prompt (cf. the B<prompt_rejected> method)
+
+
+=item $handler = $f -> completion_handler, $f -> completion_handler(\&handler)
+
+The completion handler gets called with the the entire input line, the
+prefix (partial word to complete), and rlwrap's own completion list as
+arguments. It should return a (possibly revised) list of completions.  As
+an example, suppose the user has typed "She played for
+AE<lt>TABE<gt>". The handler will be called like this:
+
+     myhandler("She played for A", "A", "Arsenal", "Arendal", "Anderlecht")
+
+it could then return a list of stronger clubs: ("Ajax", "AZ67",  "Arnhem")
+
+=item $handler = $f -> history_handler, $f -> history_handler(\&handler)
+
+Every input line is submitted to this handler, the return value is put
+in rlwrap's history. Returning an empty or undefined value will keep
+the input line out of the history.
+
+=item $handler = $f -> input_handler, $f -> input_handler(\&handler)
+
+Every input line is submitted to this handler, The handler's return
+value is written to I<command>'s pty (pseudo-terminal).
+
+=item $handler = $f -> echo_handler, $f -> echo_handler(\&handler)
+
+The first line of output that is read back from I<command>'s pty is
+the echo'ed input line. If your input handler alters the input line,
+it is the altered input that will be echo'ed back. If you don't want
+to confuse the user, use an echo handler that returns your original
+input.
+
+If you use rlwrap in --multi-line mode, additional echo lines will
+have to be handled by the output handler
+
+
+=item $handler = $f -> output_handler, $f -> output_handler(\&handler)
+
+All I<command> output after the echo line is submitted to the output
+handler (including newlines). This handler may get called many times in succession,
+dependent on the size of I<command>'s write() calls, and the whims of
+your system's scheduler. Therefore your handler should be prepared to
+rewrite your output in "chunks", where you even don't have the
+guarantee that the chunks contain entire unbroken lines.
+
+If you want to handle I<command>'s entire output in one go, you can
+specify an output handler that returns an empty string, and then use
+$filter -> cumulative_output in your prompt handler to send the
+re-written output "out-of-band" just before the prompt:
+
+    $filter -> output_handler(sub {""});
+
+    $filter -> prompt_handler(
+                  sub{ $filter -> send_output_oob(mysub($filter -> cumulative_output));
+                       "Hi there > "
+                     });
+
+
+Note that when rlwrap is run in --multi-line mode the echo handler will still
+only handle the first echo line.  The remainder will generally
+be echoed back preceded by a continuation prompt; it is up to the
+output handler what to do with it.
+
+
+=item $handler = $f -> message_handler, $f -> message_handler(\&handler)
+
+This handler gets called (as handler($message, $tag)) for every
+incoming message, and every tag (including out-of-band tags), before
+all other handlers. Its return value is ignored, but it may be useful
+for logging and debugging purposes. The $tag is an integer that can be
+converted to a tag name by the 'tag2name' method
+
+=back
+
+=head2 OTHER METHODS
+
+=over 4
+
+=item $f -> help_text("Usage...")
+
+Set the help text for this filter. It will be displayed by rlwrap -z
+<filter>. The second line of the help text is used by C<rlwrap -z listing>;
+it should be a short description of what the filter does.
+
+=item $f -> minimal_rlwrap_version("x.yy")
+
+Die unless rlwrap is version x.yy or newer
+
+=item $dir = $f -> cwd
+
+return the name of I<command>'s current working directory. This uses
+the /proc filesystem, and may only work on newer linux systems (on
+older linux and on Solaris, it will return something like
+"/proc/12345/cwd", useful to find the contents of I<command>'s working
+directory, but not its name)
+
+
+=item $text = $f -> cumulative_output
+
+return the current cumulative output. All (untreated) output gets
+appended to the cumulative output after the output_handler has been
+called. The cumulative output starts with a fresh slate with every
+OUTPUT message that directly follows an INPUT message (ignoring out-of-band
+messages and rejected prompts)
+
+When necessary (i.e. when B<rlwrap> is in "impatient mode") the prompt
+is removed from $filter->cumulative_output by the time the prompt
+handler is called.
+
+=item $tag = $f -> previous_tag
+
+The tag of the last preceding in-band message. A tag is an integer between 0 and
+255, its name can be found with the following method:
+
+=item  $name = $f -> tag2name($tag)
+
+Convert the tag (an integer) to its name (e.g. "TAG_PROMPT")
+
+=item  $name = $f -> name2tag($tag)
+
+Convert a valid tag name like "TAG_PROMPT" to a tag (an integer)
+
+=item $f -> send_output_oob($text)
+
+Make rlwrap display C<$text>. C<$text> is sent "out-of-band":
+B<rlwrap> will not see it until just  after it has sent the next
+message to the filter
+
+=item $f -> send_ignore_oob($text)
+
+Send an out-of-band TAG_IGNORE message to rlwrap. B<rlwrap> will silently
+discard it, but it can be useful when debugging filters
+
+=item $f -> add_to_completion_list(@words)
+
+=item $f -> remove_from_completion_list(@words)
+
+Permanently add or remove the words in C<@words> to/from rlwrap's completion list.
+
+=item $f -> cloak_and_dagger($question, $prompt, $timeout);
+
+Send C<$question> to I<command>'s input and read back everything that
+comes back until C<$prompt> is seen at "end-of-chunk", or no new
+chunks arrive for $timeout seconds, whichever comes first.  Return the
+response (without the final C<$prompt>).  B<rlwrap> remains completely
+unaware of this conversation.
+
+=item $f -> cloak_and_dagger_verbose($verbosity)
+
+If $verbosity evaluates to a true value, make rlwrap print all
+questions sent to I<command> by the C<cloak_and_dagger> method, and
+I<command>'s responses. By default, $verbosity = 0; setting it to
+1 will mess up the screen but greatly facilitate the (otherwise rather tricky) use of
+C<cloak_and_dagger>
+
+=item $self -> prompt_rejected
+
+A special text ("_THIS_CANNOT_BE_A_PROMPT_") to be returned by a
+prompt handler to "reject" the prompt. This will make rlwrap skip
+cooking the prompt.  $self->previous_tag and $self->cumulative_output
+will not be touched.
+
+=item $text = $f -> prompts_are_never_empty($val)
+
+If $val evaluates to a true value, automatically reject empty prompts.
+
+=item $f -> command_line
+
+In scalar context: the rlwrapped command and its arguments as a string ("command -v blah")
+in list context: the same as a list ("command", "-v", "blah")
+
+=item $f -> running_under_rlwrap
+
+Whether the filter is run by B<rlwrap>, or directly from the command line
+
+=item $f -> run
+
+Start an event loop that reads rlwrap's messages from the input pipe,
+calls the appropriate handlers and writes the result to the output
+pipe.  This method never returns.
+
+=back
+
+
+
+=head1 LOW LEVEL PROTOCOL
+
+B<rlwrap> communicates with a filter through messages consisting of a tag
+byte (TAG_OUTPUT, TAG_PROMPT etc. - to inform the filter of what is
+being sent), an unsigned 32-bit integer containing the length of the
+message, the message text and an extra newline. For every message
+sent, rlwrap expects, and waits for an answer message with the same
+tag. Sending back a different (in-band) tag is an error and instantly
+kills rlwrap, though filters may precede their answer message with
+"out-of-band" messages to output text (TAG_OUTPUT_OUT_OF_BAND), report
+errors (TAG_ERROR), and to manipulate the completion word list
+(TAG_ADD_TO_COMPLETION_LIST and TAG_REMOVE_FROM_COMPLETION_LIST)
+Out-of-band messages are not serviced by B<rlwrap> until right after
+it has sent the next in-band message - the communication with the
+filter is synchronous and driven by rlwrap.
+
+Messages are received and sent via two pipes. STDIN, STDOUT and STDERR
+are still connected to the user's terminal, and you can read and write
+them directly, though this may mess up the screen and confuse the user
+unless you are careful. A filter can even communicate with the
+rlwrapped command behind rlwrap's back (cf the cloak_and_dagger()
+method)
+
+The protocol uses the following tags (tags E<gt> 128 are out-of-band)
+
+ TAG_INPUT       0
+ TAG_OUTPUT      1
+ TAG_HISTORY     2
+ TAG_COMPLETION  3
+ TAG_PROMPT      4
+
+ TAG_IGNORE                      251
+ TAG_ADD_TO_COMPLETION_LIST      252
+ TAG_REMOVE_FROM_COMPLETION_LIST 253
+ TAG_OUTPUT_OUT_OF_BAND          254
+ TAG_ERROR                       255
+
+
+To see how this works, you can eavesdrop on the protocol
+using the 'logger' filter.
+
+The constants TAG_INPUT, ... are exported by the RlwrapFilter.pm module.
+
+=head1 SIGNALS
+
+As STDIN is still connected to the users teminal, one might expect the filter
+to receive SIGINT, SIGTERM, SIGTSTP directly from the terminal driver if
+the user presses CTRL-C, CTRL-Z etc Normally, we don't want this - it
+would confuse rlwrap, and the user (who thinks she is talking straight
+to the rlwapped command) probably meant those signals to be sent to
+the command itself. For this reason the filter starts with all signals blocked.
+
+Filters that interact with the users terminal (e.g. to run a pager)
+should unblock signals like SIGTERM, SIGWINCH.
+
+=head1 FILTER LIFETIME
+
+The filter is started by B<rlwrap> after I<command>, and stays alive
+as long as B<rlwrap> runs. Filter methods are immediately usable. When
+I<command> exits, the filter stays around for a little longer in order
+to process I<command>'s last words. As calling the cwd and
+cloak_and_dagger methods at that time will make the filter die with an
+error, it may be advisable to wrap those calls in eval{}
+
+If a filter calls die() it will send an (out-of-band) TAG_ERROR
+message to rlwrap before exiting. rlwrap will then report the message
+and exit (just after its next in-band message - out-of-band messages
+are not always processed immediately)
+
+die() within an eval() sets $@ as usual.
+
+=head1 ENVIRONMENT
+
+Before calling a filter, B<rlwrap> sets the following environment variables:
+
+    RLWRAP_FILTERDIR      directory where RlwrapFilter.pm and most filters live (set by B<rlwrap>, can be
+                          overridden by the user before calling rlwrap)
+
+    PATH	          rlwrap automatically adds $RLWRAP_FILTERDIR to the front of filter's PATH
+
+    RLWRAP_VERSION        rlwrap version (e.g. "0.35")
+
+    RLWRAP_COMMAND_PID    process ID of the rlwrapped command
+
+    RLWRAP_COMMAND_LINE   command line of the rlwrapped command
+
+    RLWRAP_IMPATIENT      whether rlwrap is in "impatient mode" (cf B<rlwrap (1)>). In impatient mode,
+                          the candidate prompt is filtered through the output handler (and displayed before
+                          being overwritten by the cooked prompt).
+
+    RLWRAP_INPUT_PIPE_FD  File descriptor of input pipe. For internal use only
+
+    RLWRAP_OUTPUT_PIPE_FD File descriptor of output pipe. For internal use only
+
+    RLWRAP_MASTER_PTY_FD File descriptor of I<command>'s pty.
+
+
+=head1 DEBUGGING FILTERS
+
+While RlwrapFilter.pm makes it easy to write simple filters, debugging
+them can be a problem. A couple of useful tricks:
+
+=head2 LOGGING
+
+When running a filter, the in- and outgoing messages can be logged by
+the B<logger> filter, using a pipeline:
+
+  rlwrap -z 'pipeline logger incoming : my_filter : logger outgoing' command
+
+
+=head2 RUNNING WITHOUT B<rlwrap>
+
+When called by rlwrap, filters get their input from
+$RLWRAP_INPUT_PIPE_FD and write their output to
+$RLWRAP_OUTPUT_PIPE_FD, and expect and write messages consisting of a
+tag byte, a 32-bit length and the message proper. This is not terribly
+useful when running a filter directly from the command line (outside
+rlwrap), even if we set the RLWRAP_*_FD ourselves.
+
+Therfore, when run directly from the command line, a filter expects
+input messages on its standard input of the form
+
+TAG_PROMPT >
+
+(i.a. a tag name, one space and a message) and it will respond in the
+same way on its standard output
+
+
+=head1 SEE ALSO
+
+B<rlwrap> (1), B<readline> (3)