#! /usr/bin/perl
#
#########################################################################
#        This Perl script is Copyright (c) 2009, Peter J Billam         #
#                          www.pjb.com.au                               #
#                                                                       #
#     This script is free software; you can redistribute it and/or      #
#            modify it under the same terms as Perl itself.             #
#########################################################################
my $Version       = '1.0';
my $VersionDate   = '27sep2009';
use Term::Clui;
# require '/home/pjb/dist/Term-Clui-1.42/Clui.pm'; import Term::Clui;

my $multiple_choice = 0;
my $filter_stdin    = 0;
while ($ARGV[$[] =~ /^-([a-z])/) {
	if ($1 eq 'v')      { shift;
		my $n = $0; $n =~ s{^.*/([^/]+)$}{$1};
		print "$n version $Version $VersionDate\n";
		exit 0;
	} elsif ($1 eq 'm') { $multiple_choice = 1; shift;
	} elsif ($1 eq 'f') { $filter_stdin    = 1; shift;
	} else {
		print "usage:\n";  my $synopsis = 0;
		while (<DATA>) {
			if (/^=head1 SYNOPSIS/)     { $synopsis = 1; next; }
			if ($synopsis && /^=head1/) { last; }
			if ($synopsis && /\S/)      { s/^\s*/   /; print $_; next; }
		}
		exit 0;
	}
}

my $question = shift;
my @list;
if ($filter_stdin) { @list = <>; chomp(@list); } else { @list = @ARGV; }

if ($multiple_choice) {
	print join("\n", choose($question, @list)),"\n";
} else {
	print choose($question, @list)."\n";
}

__END__

=pod

=head1 NAME

choose - Lets the user choose between arguments, or lines of STDIN

=head1 SYNOPSIS

 FILE=`choose 'Which header file ?' *.h`
 MY_GROUPS=`groups`
 chgrp `choose "Change $FILE to which group ?" $MY_GROUPS` $FILE

 lsusb | choose -f 'Which USB device ?'
 lsusb | choose -f -m 'Which USB devices ?'

 case `choose "Which SQL command ?" DELETE INSERT UPDATE` in
     '') exit ;;
     DELETE) ...;;
     INSERT) ...;;
     UPDATE) ...;;
 esac

=head1 DESCRIPTION

This script offers a shell-level interface to the Term::Clui CPAN-module.
The first argument is the question;
by default, subsequent arguments are offered as choices;
with the B<-f> (Filter) option, the lines of STDIN are offered as the choices.

For the user, it uses the Arrow-keys and Return, or B<q> to quit.
If a B<-m> multiple-choice is being offered,
then SpaceBar highlights choices additional to the one under the final Return.

This program comes packaged with the Term::Clui module,
in the C<examples/> directory.

=head1 OPTIONS

=over 3

=item B<-f>

Causes I<choose> to work as a B<f>ilter (like I<grep>),
so that the user chooses between lines from the standard input.
(The default is that the user chooses between
the 2nd and all subsequent arguments.)

=item B<-m>

This offers multiple-choice; the equivalent of
calling I<Term::Clui::choose> in a list context.

=item B<-v>

Prints version number.

=back

=head1 CHANGES

 20090928  1.1  pod tidied up, and -f options documented
 20090927  1.0  first working version

=head1 AUTHOR

Peter J Billam   http://www.pjb.com.au/comp/contact.html

=head1 CREDITS

Based on the CPAN module Term::Clui

=head1 SEE ALSO

 http://search.cpan.org/perldoc?Term::Clui
 http://search.cpan.org/~pjb
 http://www.pjb.com.au/
 perl(1)

=cut