| Subject: | [wish] on-demand alternative to (automatic) help |
Term::Completion came in very handy for me at a site where users would frequently select a
short code or corresponding name from a list of 100+ values.
Most of these users would be doing data entry, with the remainder doing production support
and administration, and would very quickly find ways to minimize their keystrokes.
So while the automatic display of the "helptext" value at completion attempts would be
helpful at first, I expected it would quickly become annoying screen 'chatter' (I had also added
one or two key-combos in the client logic, e.g. to toggle between selection by code and by
name, so together with the other key combos listed in "helptext", I was looking at 6-8 lines).
My solution was to add an alternative 'on-demand' help style to Term::Completion (0.91): a
new "help" (argument) hash key to represent key-combos that bring up "helptext". The
automatic display of "helptext" still occurs if "help" is undef (which it is by default). The
production platforms were perl 5.8.8 atop Redhat Enterprise Linux 5 & HP-UX 11i v2 and v3
fwiw.
Please see the listing below for a demo, to be used with a patched Term::Completion per the
attached "term-completion-0.91.on_demand_help.diff".
There's a minor documentation typo fix in the patch too, "diable" -> "disable".
Thanks,
Val
Listing 1: Demonstration of on-demand alternative to (automatic) help
-------------------------------------------------------
#!/usr/bin/perl
#
# eg2 - Demonstration of on-demand alternative to (automatic) help
#
# Description:
# With the addition of a new parameter "help", supports switching the
# display style for "helptext" from automatic (from the complete()
# method) to keyable on-demand.
#
# Procedure:
# 1. Run this script
# 2. At the first prompt, use completion (TAB-TAB) to see "helptext".
# 3. At the second prompt, key "?" as indicated to see "helptext" instead.
#
use strict ;
use warnings 'all' ;
# Patched Term::Completion should sit in ./Term
use lib '.' ;
use Term::Completion ;
my $tc ;
my $choice ;
my @country ;
chomp( @country = <DATA> ) ;
print 'Prompting with automatic help...', "\n" ;
$tc = Term::Completion->new(
prompt => 'Enter/select a country: ',
choices => \@country,
helptext => <<'EOF',
TAB complete the selection
TAB-TAB show matching choices
Ctrl-H delete a character (backspace)
Ctrl-P, cursor-up scroll up by one
Ctrl-N, cursor-down scroll down by one
Ctrl-U clear the input buffer
EOF
) ;
$choice = $tc->complete() ;
print 'Country selected: ', $choice, "\n" ;
print 'Prompting with on-demand help...', "\n" ;
$tc = Term::Completion->new(
prompt => 'Enter/select a country (?=help): ',
choices => \@country,
help => qr/\?/,
helptext => <<'EOF',
TAB complete the selection
TAB-TAB show matching choices
Ctrl-H delete a character (backspace)
Ctrl-P, cursor-up scroll up by one
Ctrl-N, cursor-down scroll down by one
Ctrl-U clear the input buffer
? help
EOF
) ;
$choice = $tc->complete() ;
print 'Country selected: ', $choice, "\n" ;
exit ;
__DATA__
AFGHANISTAN
ÅLAND ISLANDS
ALBANIA
ALGERIA
AMERICAN SAMOA
ANDORRA
ANGOLA
ANGUILLA
ANTARCTICA
ANTIGUA AND BARBUDA
ARGENTINA
ARMENIA
ARUBA
AUSTRALIA
AUSTRIA
AZERBAIJAN
BAHAMAS
BAHRAIN
BANGLADESH
BARBADOS
BELARUS
BELGIUM
BELIZE
BENIN
BERMUDA
BHUTAN
BOLIVIA, PLURINATIONAL STATE OF
BONAIRE, SINT EUSTATIUS AND SABA
BOSNIA AND HERZEGOVINA
BOTSWANA
BOUVET ISLAND
BRAZIL
BRITISH INDIAN OCEAN TERRITORY
BRUNEI DARUSSALAM
BULGARIA
BURKINA FASO
BURUNDI
CAMBODIA
CAMEROON
CANADA
| Subject: | term-completion-0.91.on_demand_help.diff |
*** /Library/Perl/5.8.6/Term/Completion.pm Fri Feb 27 09:21:00 2009
--- Completion.pm Mon Jun 11 23:19:03 2012
***************
*** 35,40 ****
--- 35,41 ----
eol => "\r\n",
del_one => "\b \b",
# help
+ help => undef,
helptext => undef,
# default: empty list of choices
choices => [],
***************
*** 128,134 ****
my $return = $this->{default};
my $r = length($return);
! if(defined $this->{helptext}) {
$this->{out}->print($this->{helptext});
}
--- 129,135 ----
my $return = $this->{default};
my $r = length($return);
! if(defined $this->{helptext} && !defined $this->{help}) {
$this->{out}->print($this->{helptext});
}
***************
*** 212,217 ****
--- 213,228 ----
redo LOOP;
};
+ # on-demand help
+ if(defined $this->{help}) {
+ $_ =~ $this->{help} && do {
+ if(defined $this->{helptext}) {
+ $this->{out}->print($this->{helptext});
+ }
+ redo LOOP;
+ };
+ }
+
# (^U) kill
$_ =~ $this->{'kill'} && do {
if ($r) {
***************
*** 743,749 ****
of configurable options, their default value and their purpose.
The key definitions are regular expressions (C<qr/.../>) - this allows
! to match multiple keys for the same action, as well as diable the
action completely by specifying an expression that will never match a
single character, e.g. C<qr/-disable-/>.
--- 754,760 ----
of configurable options, their default value and their purpose.
The key definitions are regular expressions (C<qr/.../>) - this allows
! to match multiple keys for the same action, as well as disable the
action completely by specifying an expression that will never match a
single character, e.g. C<qr/-disable-/>.
***************
*** 853,864 ****
The characters to print for deleting one character (to the left).
Default is C<"\b \b">.
=item C<helptext>
This is an optional text which is printed by the C<complete()> method
! before the actual completion process starts. It may be a multi-line
! string and should end with a newline character. Default is I<undef>. The
! text could for example look like this:
helptext => <<'EOT',
You may use the following control keys here:
TAB complete the word
--- 864,883 ----
The characters to print for deleting one character (to the left).
Default is C<"\b \b">.
+ =item C<help>
+
+ Regular expression matching those keys that print C<helptext> on-demand.
+ Furthermore, with C<help> defined (I<undef>), automatic printing of
+ C<helptext> by the C<complete()> method is disabled (enabled).
+ Default is I<undef>, for backwards compatibility; C<qr/\?/> is suggested.
+
=item C<helptext>
This is an optional text which is printed by the C<complete()> method
! before the actual completion process starts, unless C<help> is defined.
! It may be a multi-line string and should end with a newline character.
! Default is I<undef>. The text could for example look like this:
!
helptext => <<'EOT',
You may use the following control keys here:
TAB complete the word