##################################################
# Pick.pm -- Picking user input
##################################################

package Pick;

our $VERSION = "1.01";
our $CVSVERSION = '$Revision: 1.4 $';
our @ISA     = qw(Exporter);

##################################################
sub single {
##################################################
    my ($prompt, $default) = @_;    

    if(@_ != 2) {
        die "Pick::single called with wrong # of args";
    }

    print STDERR "$prompt [$default]> ";
    my $value = <STDIN>;
    chomp $value;

    $value = $default if $value eq "";

    return $value;
}

##################################################
sub list {
##################################################
    my ($prompt, $options, $default) = @_;    

    my $default_int;
    my $count = 0;

    if(@_ != 3 or ref($options) ne "ARRAY") {
        die "Pick::list called with wrong #/type of args";
    }
    
    foreach (@$options) {
        print STDERR "[", ++$count, "] $_\n";
        $default_int = $count if $_ eq $default;
        $files{$count} = $_;
    }

    print STDERR "$prompt [$default_int]> ";
    $input = <STDIN>;
    chomp($input);

    $input = $default_int unless length($input);
    
    return "$files{$input}";
}

1;

__END__

=head1 NAME

    Pick -- A module to ask for user input

=head1 DOWNLOAD

_SRC_HERE_

=head1 SYNOPSIS

    use Pick;

        # "File name [index.html]>"
    Pick::single("File name", "index.html");

        # "[1] apple
        #  [2] pear
        #  [3] pineapple
        #  Pick a fruit [3]> "
    Pick::list("Pick a fruit", ["apple", "pear", "pineapple"], 3);

=head1 DESCRIPTION

C<Pick> asks for user input on the command line. 
It either collects a single answer or lets the user pick from a list.

Both functions C<single()> and C<list()> take default values, which they will
return if the user just hits the I<Return> key without providing input.

=head1 EXAMPLES
 
Collect a single value from the user:

    use Pick;
    Pick::single("File name", "index.html");

will display the following:

    File name [index.html]> 

and wait for input. If the user hits I<Return>, it will return C<"index.html">
if the user types in a text string and hits return, the text string will be returned,
not including the trailing newline.

    use Pick;
    Pick::list("Pick a fruit", ["apple", "pear", "pineapple"], 3);

will display the following:

    [1] apple
    [2] pear
    [3] pineapple
    Pick a fruit [3]>

If the user just hits I<Enter>, "pineapple" (the default value) will be returned. 
Note that 3 marks the 3rd element of the list, and is I<not> an index value 
into the array.

If the user enters C<1>, C<2> or C<3>, the corresponding text string
(C<"apple">, C<"pear">, C<"pineapple"> will be returned by C<Pick::list()>.

=head1 LEGALESE

Copyright 2002 by Mike Schilli, all rights reserved.
This program is free software, you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

2002, Mike Schilli <m@perlmeister.com>