IO-Prompt-0.997004/000755 000765 000024 00000000000 13015661610 014147 5ustar00damianstaff000000 000000 IO-Prompt-0.997004/Build.PL000644 000765 000024 00000000743 13015661246 015454 0ustar00damianstaff000000 000000 use strict; use warnings; use Module::Build; my $builder = Module::Build->new( module_name => 'IO::Prompt', license => 'perl', dist_author => 'Damian Conway ', dist_version_from => 'lib/IO/Prompt.pm', requires => { 'Test::More' => 0, 'IO::Handle' => 0, 'Term::ReadKey' => 0, 'Want' => 0, }, add_to_cleanup => [ 'IO-Prompt-*' ], ); $builder->create_build_script(); IO-Prompt-0.997004/Changes000644 000765 000024 00000004114 13015661607 015450 0ustar00damianstaff000000 000000 Revision history for IO-Prompt 0.0.1 Tue May 24 21:56:09 2005 Initial release. 0.99.1 Wed May 25 02:38:58 2005 - Added -menu option 0.99.2 Mon Aug 1 23:55:45 2005 - Fixed setting of $_ using Want.pm (thanks Robin!) 0.99.3 Mon Aug 1 23:56:57 2005 0.99.4 Fri Feb 17 15:59:21 2006 - Fixed -menu to handle nested arrays as well as nested hashes - Removed spurious -wipe and -wipefirst options, by renaming them -clear and -clearfirst - Fixed cuddling behaviour - Added special handling (principally to allow navigation back up a menu level under -menu) - Added dependencies to Build.pl and Makefile.PL (thanks to the many people who reported this oversight) - Made all underscores in flags optional 0.99.5 Tue Sep 5 14:48:40 2006 - Fixed underscore bug in -failif and -okayif (thanks Uwe) - Added -raw option (thanks Uwe) - Remove spurious context attribute from return value objects - Localized $\ within prompt() to prevent bad input echoing (thanks Smylers) - Disallowed negative exponents in -integer values (thanks Smylers) - Documented incompatibility with systems not having /dev/tty (thanks Mischa) 0.996 Sun Jan 10 20:20:24 2010 - Added dependency check and FAQ entry for /dev/tty (thanks Miller) - Removed spurious warning for undefined inputs - Changed versioning system 0.997 Sat Jan 30 07:17:07 2010 - Removed another spurious warning for undefined inputs 0.997001 Sat Apr 24 12:00:19 2010 - More warning cleanup and also made backspaces work right at the start of a line (thanks Ingmar) 0.997002 Wed Nov 7 07:50:49 2012 - Fixed ->opened bug under 5.14 (thanks GFUGI!) - Documented unmaintained status 0.997003 Wed Aug 19 10:47:34 2015 - Removed dependencies check for /dev/tty because it was messing up smoke testing (thanks, Jarkko!) 0.997004 Fri Nov 25 09:02:47 2016 - Removed dependency on version.pm (thanks Petr) - Removed dependency on deprecated POSIX isprint() (thanks Slaven) IO-Prompt-0.997004/examples/000755 000765 000024 00000000000 13015661610 015765 5ustar00damianstaff000000 000000 IO-Prompt-0.997004/lib/000755 000765 000024 00000000000 13015661610 014715 5ustar00damianstaff000000 000000 IO-Prompt-0.997004/Makefile.PL000644 000765 000024 00000001061 13015661246 016124 0ustar00damianstaff000000 000000 use strict; use warnings; use ExtUtils::MakeMaker; WriteMakefile( NAME => 'IO::Prompt', AUTHOR => 'Damian Conway ', VERSION_FROM => 'lib/IO/Prompt.pm', ABSTRACT_FROM => 'lib/IO/Prompt.pm', PL_FILES => {}, PREREQ_PM => { 'Test::More' => 0, 'IO::Handle' => 0, 'Term::ReadKey' => 0, 'Want' => 0, }, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, clean => { FILES => 'IO-Prompt-*' }, ); IO-Prompt-0.997004/MANIFEST000644 000765 000024 00000001064 13015661610 015301 0ustar00damianstaff000000 000000 Build.PL Changes MANIFEST META.yml # Will be created by "make dist" Makefile.PL README lib/IO/Prompt.pm t/00.load.t t/pod-coverage.t t/pod.t examples/clear.pl examples/cmdline.pl examples/data.pl examples/default.pl examples/hand.pl examples/interactive.pl examples/lingua.pl examples/menu.pl examples/nonl.pl examples/num.pl examples/passwd.pl examples/record.pl examples/require.pl examples/to.pl examples/tty.pl examples/underscore.pl examples/while_until.pl examples/yesno.pl META.json Module JSON meta-data (added by MakeMaker) IO-Prompt-0.997004/META.json000644 000765 000024 00000001722 13015661610 015572 0ustar00damianstaff000000 000000 { "abstract" : "Interactively prompt for user input", "author" : [ "Damian Conway " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.142690", "license" : [ "unknown" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "IO-Prompt", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "IO::Handle" : "0", "Term::ReadKey" : "0", "Test::More" : "0", "Want" : "0" } } }, "release_status" : "stable", "version" : "0.997004" } IO-Prompt-0.997004/META.yml000644 000765 000024 00000001060 13015661610 015415 0ustar00damianstaff000000 000000 --- abstract: 'Interactively prompt for user input' author: - 'Damian Conway ' build_requires: ExtUtils::MakeMaker: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.142690' license: unknown meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: IO-Prompt no_index: directory: - t - inc requires: IO::Handle: '0' Term::ReadKey: '0' Test::More: '0' Want: '0' version: '0.997004' IO-Prompt-0.997004/README000644 000765 000024 00000002075 13015661607 015041 0ustar00damianstaff000000 000000 IO::Prompt version 0.997004 By default, this module exports a single function: prompt(). It prompts the user to enter some input, and returns an object that represents the user input. You may specify various flags to the function to affect its behaviour; most notably, it defaults to automatically chomp the input, unless the -line flag is specified. Note that this is an interim re-release. A full release with better documentation will follow in the near future. Meanwhile, please consult the 'examples/' directory from this module's CPAN distribution to better understand how to make use of this module. INSTALLATION To install this module, run the following commands: perl Makefile.PL make make test make install Alternatively, to install with Module::Build, you can use the following commands: perl Build.PL ./Build ./Build test ./Build install DEPENDENCIES None. COPYRIGHT AND LICENCE Copyright (C) 2005, Damian Conway This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. IO-Prompt-0.997004/t/000755 000765 000024 00000000000 13015661610 014412 5ustar00damianstaff000000 000000 IO-Prompt-0.997004/t/00.load.t000644 000765 000024 00000000162 10244721371 015735 0ustar00damianstaff000000 000000 use Test::More tests => 1; BEGIN { use_ok( 'IO::Prompt' ); } diag( "Testing IO::Prompt $IO::Prompt::VERSION" ); IO-Prompt-0.997004/t/pod-coverage.t000644 000765 000024 00000000254 10244721371 017155 0ustar00damianstaff000000 000000 #!perl -T use Test::More; eval "use Test::Pod::Coverage 1.04"; plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@; all_pod_coverage_ok(); IO-Prompt-0.997004/t/pod.t000644 000765 000024 00000000214 10244721371 015360 0ustar00damianstaff000000 000000 #!perl -T use Test::More; eval "use Test::Pod 1.14"; plan skip_all => "Test::Pod 1.14 required for testing POD" if $@; all_pod_files_ok(); IO-Prompt-0.997004/lib/IO/000755 000765 000024 00000000000 13015661610 015224 5ustar00damianstaff000000 000000 IO-Prompt-0.997004/lib/IO/Prompt.pm000644 000765 000024 00000067321 13015661607 017062 0ustar00damianstaff000000 000000 package IO::Prompt; our $VERSION = '0.997004'; use strict; use Carp; use 5.008; no warnings 'utf8'; our @EXPORT = qw( prompt ); our @EXPORT_OK = qw( hand_print get_input ); use IO::Handle; use Term::ReadKey; sub _isprint { $_[0] =~ qr/ ^ [[:print:]]+ $ /x } my $clearfirst; my %input; sub _clear { return unless $_[0]; open my $OUT, ">/dev/tty" or croak "Cannot write to terminal: $!"; print {$OUT} "\n" x 60; $clearfirst = 0; } our %flags_arg = ( p => 'prompt', s => 'speed', e => 'echo', r => 'require', d => 'default', u => 'until', w => 'while', nl => 'newline', m => 'menu', ); our %flags_alias = ( '-okayif' => '-while', '-okay_if' => '-while', '-failif' => '-until', '-fail_if' => '-until', ); our %flags_noarg = ( y => 'yes', n => 'no', i => 'integer', num => 'number', raw => 'raw_input', 1 => 'onechar', c => 'clear', f => 'clearfirst', a => 'argv', l => 'line', t => 'tty', x => 'escape', ); my $RECORD; # store filehandle for __PROMPT__ file supporting -record flag $flags_arg{$_} = $_ for values %flags_arg; $flags_noarg{$_} = $_ for values %flags_noarg; my $flag_with_arg = join '|', reverse sort keys %flags_arg; my $flag_no_arg = join '|', reverse sort keys %flags_noarg; my %yespat = ( 'y' => qr/^\s*[yY]/, 'Y' => qr/^\s*Y/, ); my %nopat = ( 'n' => qr/^\s*[nN]/, 'N' => qr/^\s*N/, ); my %num_pat = ( integer => qr{[+-]? \d+ (?:[Ee]+?\d+ )?}x, number => qr{[+-]? (?:\d+[.]?\d* | [.]\d+) (?:[Ee][+-]?\d+)? }x, ); sub _get_prompt (\%@) { my ($flags, @data) = @_; my ($OUT); @data = map { $flags_alias{$_} || defined($_) ? $_ : "" } @data; for (my $i = 0 ; $i < @data ; $i++) { local *_ = \$data[$i]; if (ref eq 'HASH') { splice @data, $i + 1, 0, %$_; } elsif (ref eq 'GLOB' or UNIVERSAL::isa($_, 'IO::Handle')) { croak "Can't write prompt to read-only $_" unless -w; $OUT = $_; } elsif (/^-/) { # a flag s/_//g; if (s/^-(f|clearfirst)/-/) { $clearfirst = 1 unless defined $clearfirst; } elsif (s/^-(yes|y)/-/i) { $flags->{-yesno}{yes} = $yespat{ substr $1, 0, 1 }; $flags->{-yesno}{yesprompt} = substr $1, 0, 1; } elsif (s/^-(?:nl|newline)/-/i) { $flags->{-nlstr} = $data[ $i + 1 ]; undef $data[ $i++ ]; } elsif (s/^-escape|-x/-/i) { $flags->{-escape} = 1; } elsif (s/^-raw_?(?:input)?/-/i) { $flags->{-raw_input} = 1; } elsif (s/^-number|-num/-/i) { $flags->{-number} = 'number'; } elsif (s/^-integer|-i/-/i) { $flags->{-number} = 'integer'; } elsif (s/^-(no|n)/-/i) { $flags->{-yesno}{no} = $nopat{ substr $1, 0, 1 }; $flags->{-yesno}{noprompt} = substr $1, 0, 1; } elsif (m/^-($flag_with_arg)/) { croak "Missing argument for $_ option" if @data < $i+2 || !defined $data[$i+1]; s/^-($flag_with_arg)/-/; $flags->{ -$flags_arg{$1} } = $data[$i+1]; undef $data[$i++]; } elsif (s/^-($flag_no_arg)/-/) { $flags->{ -$flags_noarg{$1} } = 1; } else { croak "Unknown flag ($_) in prompt" } redo if defined $_ && /^-./; } else { next } undef $data[$i]; } $_ = !defined() ? undef : ref eq 'Regexp' ? $_ : qr/^\Q$_\E$/ for @{$flags}{qw(-while -until -failif -okayif)}; for (grep { defined } $flags->{ -require }) { croak "Argument to -require must be hash reference" unless ref eq 'HASH'; my %reqs = %$_; $_ = sub { my ($input) = @_; for (keys %reqs) { return $_ unless _smartmatch($input, $reqs{$_}); } return; }; } my @prompt = grep { defined } @data; if (@prompt && exists $flags->{-default}) { my $prompt = join "", @prompt; $prompt =~ s/(:?\s*)$/ [$flags->{-default}]$1/ if $prompt !~ /\[.*\]/; @prompt = $prompt; } return $OUT, @prompt; } my $prompt_req = "(The value entered is not acceptable) "; sub prompt { my $caller = caller; local $\ = q{}; # Make sure no funny business on print statements my %flags; my ($OUT, @prompt) = _get_prompt(%flags, @_); open $OUT, ">/dev/tty" or croak "Cannot write to terminal: $!" if !$OUT; $OUT->autoflush(1); @prompt = $flags{ -prompt } if !@prompt and $flags{ -prompt }; my $IN; if ($flags{-tty} || $flags{-argv}) { open $IN, " $input, success => $success, set_val => $flags{ -set_underscore }, }, 'IO::Prompt::ReturnVal'; } sub _success { my ($val, $no_set, $raw) = @_; print {$RECORD} $val, "\n" if $val && $RECORD; return "$val" if $raw; return bless { value => $val, success => 1, set_val => !$no_set, }, 'IO::Prompt::ReturnVal'; } sub _failure { my ($val, $raw) = @_; return "$val" if $raw; return bless { value => $val, success => 0, set_val => 0, }, 'IO::Prompt::ReturnVal'; } sub import { my $class = shift; { no strict 'refs'; *{ caller() . "::$_" } = \&{$_} for @EXPORT; foreach my $sym (@_) { grep { $_ eq $sym } @EXPORT_OK or next; *{ caller() . "::$sym" } = \&{$sym}; } } @_ = grep /^-/, @_; $input{ caller() } = undef; if ("@_" eq "-clearfirst") { $clearfirst = 1; return; } for my $i (0 .. $#_) { last if $RECORD; if ($_[$i] eq '-record') { splice @_, $i, 1; open $RECORD, '>', '__PROMPT__' or croak "Can't open __PROMPT__ recording file: $!"; print {$RECORD} "__DATA__\n__PROMPT__\n"; } } prompt @_ if @_; } CHECK { for my $pkg (keys %input) { next if defined $input{$pkg}; no strict 'refs'; if (my $datahandle = *{"${pkg}::DATA"}{IO}) { local $/; my $data = <$datahandle>; if ($data =~ s/(\A|\n) __PROMPT__ \s*? \n (.*)/$1/xs) { $input{$pkg} = "$2"; } else { delete $input{$pkg}; } open "${pkg}::DATA", "<", \$data or die "Internal error: $!"; } else { delete $input{$pkg}; } } } my $baseline = ord 'A'; sub _visualize { local ($_) = @_; return _isprint($_) ? $_ : $_ eq "\n" ? $_ : ord($_) == 0 ? '' : ord($_) < $baseline ? '^' . chr($baseline + ord($_) - 1) : '?' } sub hand_print { my $OUT = \*STDOUT; my $echo = undef; my $speed = 0.05; local $| = 1; for (@_) { if (ref eq 'HASH') { $speed = $_->{-speed} if exists $_->{-speed}; $OUT = $_->{-to} if exists $_->{-to}; $echo = $_->{-echo} if exists $_->{-echo}; } elsif (!$speed) { print {$OUT} $_; } else { print {$OUT} $_ and select undef, undef, undef, rand $speed for map { defined $echo ? $echo : _visualize($_) } split ""; } } return scalar @_; } sub _fake_from_DATA { my ($caller, $IN, $OUT, $flags, @prompt) = @_; local $SIG{INT} = sub { ReadMode 'restore', $IN; exit }; ReadMode 'noecho', $IN; ReadMode 'raw', $IN; print {$OUT} @prompt; my $input = getc $IN; if ($input =~ /\cD|\cZ/) { print {$OUT} _visualize($input),"\n"; return; } if ($input eq "\e") { ReadMode 'restore', $IN; return get_input($IN, $OUT, $flags, @prompt); } $input{$caller} =~ m/\G (?!\cD|\cZ) (.*) (\n?)/xgc; my ($line, $nlstr) = ($1, $2); unless (defined $line) { while ($input ne "\n") { $input = getc $IN } print {$OUT} "\n"; return; } delete $input{$caller} if pos $input{$caller} == length $input{$caller}; if ($input eq "\n") { hand_print { -to => $OUT, %$flags }, $line; unless (defined <$IN>) { print {$OUT} "\n"; return; } } else { my $i = 0; while (1) { my $done = $i >= length $line; print {$OUT} substr($line, $i++, 1) unless $done; if (getc $IN eq "\n") { last if $done; hand_print { -to => $OUT, %$flags }, substr($line, $i); $i = length $line; } } } ReadMode 'restore', $IN; print {$OUT} "\n"; return $line . $nlstr; } sub get_input { my ($IN, $OUT, $flags, @prompt) = @_; my ($onechar, $nlstr, $echo, $require) = @{$flags}{ -onechar, -nlstr, -echo, -'require' }; $nlstr = "\n" unless defined $nlstr; if (!-t $IN) { return scalar <$IN> unless $onechar; return getc $IN; } $OUT->autoflush(1); local $SIG{INT} = sub { ReadMode 'restore', $IN; exit }; my ($input, $newlines); my %cntl = GetControlChars $IN; my $cntl = join '|', values %cntl; ReadMode 'raw', $IN; INPUT: while (1) { my $next = getc $IN; if ($next eq $cntl{INTERRUPT}) { ReadMode 'restore', $IN; exit; } elsif ($next eq $cntl{ERASE}) { if (defined $input && length $input) { substr($input, -1) = ""; print {$OUT} "\b \b"; } next; } elsif ($next eq $cntl{EOF}) { ReadMode 'restore', $IN; close $IN; return $input; } elsif ($flags->{-escape} && $next eq "\e") { ReadMode 'restore', $IN; print {$OUT} ""; return "\e"; } elsif ($next !~ /$cntl/ && defined $next) { $input .= $next; if ($next eq "\n") { if ($input eq "\n" && exists $flags->{-default}) { print {$OUT} ( defined $echo && $flags->{-menu} ? $echo : defined $echo ? $echo x length($flags->{-default}) : '['.$flags->{-default}.']' ); print {$OUT} $nlstr; ReadMode 'restore', $IN; return $onechar ? substr($_, 0, 1) : $_ for $flags->{-default}; } $newlines .= $nlstr; } else { print {$OUT}(defined $echo ? $echo : $next); } } else { $input .= $next; } if ($onechar or !defined $next or $input =~ m{\Q$/\E$}) { chomp $input unless $flags->{-line}; if ($require and my $mesg = $require->($input)) { print {$OUT} "\r", " " x 79, "\r", sprintf($mesg, @prompt); undef $input; undef $newlines; } else { ReadMode 'restore', $IN; print {$OUT} $newlines if defined $newlines; return $onechar ? substr($input, 0, 1) : $input; } } } } sub _yesno { my ($IN, $OUT, $flags, @prompt) = @_; my ($yes, $no, $yesprompt, $noprompt) = @{ $flags->{ -yesno } }{qw(yes no yesprompt noprompt)}; $yes = qr/^([^Nn])/ unless defined $yes; $no = qr/^([^Yy])/ unless defined $no; my $prompt2 = $yesprompt && $noprompt ? "'$yesprompt' or '$noprompt'" : $yesprompt ? "'$yesprompt' for yes" : "'$noprompt' for no"; my $raw = $flags->{-raw_input}; print {$OUT} @prompt if -t $IN; while (1) { my $response = get_input($IN, $OUT, { %$flags, -nlstr => "" }, @prompt); chomp $response unless $flags->{-line}; print {$OUT} "\n" and return _success($response, 'no_set', $raw) if defined $response and $response =~ /$yes/; print {$OUT} "\n" and return _failure($response, $raw) if !defined $response or $response =~ /$no/; print {$OUT} "\r", " " x 79, "\r", @prompt, "(Please answer $prompt2) " if -t $IN; } } sub _number { my ($IN, $OUT, $flags, @prompt) = @_; my $numtype = $flags->{ -number }; my $prompt_num = "(Please enter a valid $numtype) "; my $match = $num_pat{$numtype}; my $require = $flags->{ -require }; print {$OUT} @prompt if -t $IN; while (1) { my $response = get_input($IN, $OUT, { %$flags, -nlstr => "", -require => undef }, @prompt); chomp $response if defined $response && !$flags->{-line}; if (-t $IN and defined $response) { if ($response !~ /\A \s* $match \s* \Z/x) { print {$OUT} "\r", " " x 79, "\r", @prompt, $prompt_num; next; } elsif ($require and my $mesg = $require->($response)) { print {$OUT} "\r", " " x 79, "\r", sprintf($mesg, @prompt); next; } } print {$OUT} "\n" and return _tidy($response); } } sub _self { $_[0] } sub _menu { my ($IN, $OUT, $flags, @prompt) = @_; my $datatype = ref $flags->{ -menu }; my @data = $datatype eq 'ARRAY' ? @{ $flags->{ -menu } } : $datatype eq 'HASH' ? sort keys %{ $flags->{ -menu } } : croak "Argument to -menu must be hash or array reference"; my $val_for = $datatype eq 'ARRAY' ? \&_self : sub { $flags->{ -menu }{$_[0]} }; my $count = @data; croak "Too many -menu items" if $count > 26; croak "Too few -menu items" if $count < 1; my $max_char = chr(ord('a') + $count - 1); my $menu = q{}; my $default_key; my $next = 'a'; for (@data) { my $item = $_; if (defined $flags->{ -default } && !defined $default_key && $item eq $flags->{ -default }) { $default_key = $next; } $item =~ s/\A/qq{ }.$next++.q{. }/xmse; $item =~ s/\n?\z/\n/xms; $item =~ s/(?!\Z)\n/\n /gxms; $menu .= $item; } push @prompt, "\n$menu\n> "; my $prompt_range = "(Please enter a-$max_char) > "; my $require = $flags->{ -require }; print {$OUT} @prompt if -t $IN; while (1) { my $response = get_input($IN, $OUT, { %$flags, -escape => 1, -nlstr => "", -require => undef }, @prompt); chomp $response; if (-t $IN and defined $response) { if (length $response == 1 && $response eq "\e") { return $response; } elsif (length $response > 1 || ($response lt 'a' || $response gt $max_char) ) { if ($response ne $flags->{-default}) { print {$OUT} "\r", " " x 79, "\r", $prompt_range; next; } $response = $default_key; } elsif ($require and my $mesg = $require->($data[ord($response)-ord('a')])) { print {$OUT} "\r", " " x 79, "\r", sprintf($mesg, @prompt); next; } } print {$OUT} "\n"; my $selection = $data[ord($response)-ord('a')]; $response = defined $response ? $val_for->($selection) : $response; if (defined $response && ref($response) =~ m/\A(?:HASH|ARRAY)\z/xms ) { $response = _menu($IN, $OUT, {%{$flags}, -menu=>$response}, "$selection: "); if (defined $response && $response eq "\e") { print {$OUT} "\n", @prompt if -t $IN; next; } } return _tidy($response); } } sub _smartmatch { my ($str, $matcher) = @_; my $type = ref $matcher; my $res = $type eq 'CODE' ? do { local $_ = $str; $matcher->() } : $type eq 'Regexp' ? ($str =~ $matcher) : $type eq 'ARRAY' ? scalar grep({ _smartmatch($str, $_) } @$matcher) : $type eq 'HASH' ? $matcher->{$str} : $str eq $matcher; return $res; } package IO::Prompt::ReturnVal; use overload q{bool} => sub { $_ = $_[0]{value} if $_[0]{set_val}; $_[0]{handled} = 1; $_[0]{success}; }, q{""} => sub { $_[0]{handled} = 1; "$_[0]{value}"; }, q{0+} => sub { $_[0]{handled} = 1; 0 + $_[0]{value}; }, fallback => 1, ; sub DESTROY { $_ = $_[0]{value} unless $_[0]{handled}; } 1; # Magic true value required at end of module __END__ =head1 NAME IO::Prompt - Interactively prompt for user input =head1 STATUS This module is no longer being maintained. Use the IO::Prompter module instead. =head1 VERSION This document describes IO::Prompt version 0.997004 =head1 SYNOPSIS use IO::Prompt; while( prompt "next: " ) { print "You said '$_'\n"; } =head1 DESCRIPTION By default, this module exports a single function C. It prompts the user to enter some input, and returns an object that represents the user input. You may specify various flags to the function to affect its behaviour; most notably, it defaults to automatically C the input, unless the C<-line> flag is specified. Two other functions are exported at request: C, which simulates hand-typing to the console; and C, which is the lower-level function that actually prompts the user for a suitable input. Note that this is an interim re-release. A full release with better documentation will follow in the near future. Meanwhile, please consult the F directory from this module's CPAN distribution to better understand how to make use of this module. =head1 INTERFACE =head2 Arguments to C Any argument not of the following forms is treated as part of the text of the prompt itself. Flag Long form Arg Effect ---- --------- --- ------ Use as prompt Prompt to specified filehandle Flatten hash entries into argument list (useful for aggregating the options below) -p -prompt Specify prompt explicitly -s -speed Simulated typing speed (seconds/char) -e -echo What to echo for each char typed -nl -newline When a newline is typed, echo instead -d -default What to return if only pressed -r -require Each value of each entry must 'smartmatch' the input else corresponding key is printed as error message: - Subs must return true when passed input - Regexes must pattern match input - Strings must eq match input - Arrays are flattened & recursively matched - Hashes must return true for input as key -u -until Fail if input matches -fail_if -w -while Fail unless input matches -okay_if -m -menu Show the data specified as a menu and allow one to be selected. Enter an to back up one level. -1 -one_char Return immediately after first char typed -x -escape Pressing returns "\e" immediately -raw -raw_input Return only the string that was input (turns off context-sensitive features) -c -clear Clear screen before prompt -f -clear_first Clear screen before first prompt only -a -argv Load @ARGV from input if @ARGV empty -l -line Don't autochomp -t -tty Prompt to terminal no matter what -y -yes Return true if [yY] entered, false otherwise -yn -yes_no Return true if [yY], false if [nN] -Y -Yes Return true if 'Y' entered, false otherwise -YN -Yes_No Return true if 'Y', false if 'N' -num -number Accept only valid numbers as input -i -integer Accept only valid integers as input Note that the underscores between words in flags like C<-one_char> and C<-yes_no> are optional. Flags can be "cuddled". For example: prompt("next: ", -tyn1s=>0.2) # -tty, -yes, -no, -one_char, -speed=>0.2 =head2 "Hand-written" printing via C The C subroutine takes a string and prints it out in the stop-and-start manner of hand-typed text. =head2 Low-level input retrieval via C The C subroutine is a low-level utility subroutine that takes an input filehandle, an output filehandle, a reference to a hash of options (as listed for C, above) and a single prompt string. It prints the prompt and retreives the input. You almost certainly want to use C instead. =head1 DIAGNOSTICS =over =item C<< Can't write prompt to read-only $_ >> You specified a filehandle to which the prompt should be written, but that filehandle was not writeable. Did you pass the wrong filehandle, or open it in the wrong mode? =item C<< Missing argument for %s option >> The flag you specified takes an argument, but you didn't provide that argument. =item C<< Unknown flag ($s) in prompt >> The flag you specified wasn't one of those that C understands. Did you misspell it, perhaps? =item C<< Argument to -require must be hash reference >> The C<-require> option takes a single argument that is a hash. You tried to pass it something else. Try a hash instead. =item C<< Cannot write to terminal: %s >> =item C<< Cannot read from terminal: %s >> C attempted to access the terminal but couldn't. This may mean your environment has no C available, in which case there isn't much you can do with this module. Sorry. =item C<< Can't open %s: %s >> C tried to read input via C<*ARGV> from a file specified on the command-line, but the file couldn't be opened for the reason shown. This is usually either a permission problem, a non-existent file, or a mistyped filepath. =item C<< Argument to -menu must be hash or array reference >> The C<-menu> option requires an argument that is either an array: prompt -menu=>['yes', 'no', 'maybe']; or a hash: prompt -menu=>{yes=>1, no=>0, maybe=>0.5}; or a hash of hashes (of hashes (of array)) =item C<< Too many -menu items >> =item C<< Too few -menu items >> A menu can't have fewer than 1 or more than 26 items. =back =head1 CONFIGURATION AND ENVIRONMENT IO::Prompt requires no configuration files or environment variables. =head1 DEPENDENCIES IO::Prompt requires the following modules: =over =item * version =item * IO::Handle =item * Term::ReadKey =back =head1 INCOMPATIBILITIES The module requires a /dev/tty device be available. It is therefore incompatible with any system that doesn't provide such a device. =head1 BUGS AND LIMITATIONS No bugs have been reported. Please report any bugs or feature requests to C, or through the web interface at L. =head1 FAQ This is a collection of things that might help. Please send your questions that are not answered here to Damian Conway C<< >> =head2 Can I use this module with ActivePerl on Windows? Up to now, the answer was 'No', but this has changed. You still cannot use ActivePerl, but if you use the Cygwin environment (http://sources.redhat.com), which brings its own perl, and have the latest IO::Tty (v0.05 or later) installed, it should work (feedback appreciated). =head1 THANKS My deepest gratitude to Autrijus Tang and Brian Ingerson, who have taken care of this module for the past twelve months, while I was off trekking in the highlands of Perl 6. Now it's their turn for some mountain air, I'll be looking after this module again. =head1 AUTHOR Damian Conway C<< >> =head1 LICENCE AND COPYRIGHT Copyright (c) 2005, Damian Conway C<< >>. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 DISCLAIMER OF WARRANTY BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IO-Prompt-0.997004/examples/clear.pl000755 000765 000024 00000000430 10350473545 017417 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w use IO::Prompt; use Data::Dumper 'Dumper'; if (prompt -clearfirst, -escape, "first> ", -line) { warn Dumper [ $_ ]; } # Should not wipe screen, since previous call already did... while (prompt -clearfirst, " next> ", -line) { warn Dumper [ $_ ]; } IO-Prompt-0.997004/examples/cmdline.pl000755 000765 000024 00000000351 10244760354 017745 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w use IO::Prompt -argv; use Data::Dumper 'Dumper'; warn Dumper [@ARGV]; # This time it's probably a no-op, since @ARGV will be non-empty... use IO::Prompt -argv; use Data::Dumper 'Dumper'; warn Dumper [@ARGV]; IO-Prompt-0.997004/examples/data.pl000755 000765 000024 00000002437 10244760354 017252 0ustar00damianstaff000000 000000 use IO::Prompt; # The input is taken from the __PROMPT__ section below # # Hitting immediately after the prompt will cause the next # __PROMPT__ line to be typed in for you. # Useful for pretending to type without bothering with the keyboard. # # Hitting any other key immediately after the prompt will put you into # "smart typing" mode: the next __PROMPT__ line will be typed in # for you, one letter for every key you hit (no matter what key you hit) # Useful for pretending to type without looking at the keyboard. # # Hitting immediately after the prompt will escape from the # automated input process and allow you to type whatever you like # # Because the __PROMPT__ section ends with a line containing only -D, # input terminates when that line is reached. If the last line *didn't* # contain the -D (or -Z if you prefer) then input would # continue from the keyboard after all the __PROMPT__ lines were used # while (prompt -line, "\nNext line: ") { print "Input was: $_"; while () { print "Datum was: $_"; last; } } print "\n"; while () { print "Datum was: $_"; } __DATA__ This is data line 1 This is data line 2 This is data line 3 This is data last line __PROMPT__ This is input line 1 This is input line 2  IO-Prompt-0.997004/examples/default.pl000755 000765 000024 00000000653 10244762227 017764 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # Yes/no input only, with defaults set... use IO::Prompt; until (prompt "yes? ", -default => "N", -YN1) { print "That's a 'no'\n"; } while (0 + prompt "next: ", -d => "-1") { print "That's non-zero\n"; } while (prompt "****: ", -d => "secret", -e => '*') { print "That's '$_'\n"; } print "\n"; while (prompt "**** [or default]: ", -d => "secret", -e => '*') { print "That's '$_'\n"; } IO-Prompt-0.997004/examples/hand.pl000755 000765 000024 00000000514 10244760354 017245 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # The internal &hand_print sub can be optionally exported to handle # special output requirements... use IO::Prompt 'hand_print'; hand_print "Now is the winter of\n"; hand_print { -speed => 0.25 }, "our discontent made ", { -speed => 0.5 }, "glorious\n", { -speed => 0.15 }, "summmer by this son of York\n" IO-Prompt-0.997004/examples/interactive.pl000755 000765 000024 00000000163 10244760354 020650 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # Basic example... use IO::Prompt; while (prompt "next: ") { print "You said '$_'\n"; } IO-Prompt-0.997004/examples/lingua.pl000755 000765 000024 00000003476 10350473761 017625 0ustar00damianstaff000000 000000 #!/usr/bin/perl # Typical example of using the module in a presentation... use Lingua::LinkParser; { local $| = 1; print "loading analyser..."; $parser = new Lingua::LinkParser; print "done\n"; } use IO::Prompt; $parser->opts( 'verbosity' => 0, 'max_sentence_length' => 70, 'panic_mode' => 1, 'max_parse_time' => 30, 'linkage_limit' => 1000, 'short_length' => 10, 'disjunct_cost' => 2, 'min_null_count' => 0, 'max_null_count' => 0, ); while (prompt "> ", -clearfirst) { my $sentence = $parser->create_sentence($_); if ($sentence->num_linkages == 0) { $parser->opts( 'min_null_count' => 1, 'max_null_count' => $sentence->length ); $sentence = $parser->create_sentence($_); if ($sentence->num_linkages == 0) { $parser->opts( 'disjunct_cost' => 3, 'min_null_count' => 1, 'max_null_count' => 30, 'max_parse_time' => 60, 'islands_ok' => 1, 'short_length' => 6, 'all_short_connectors' => 1, 'linkage_limit' => 100 ); my $sentence = $parser->create_sentence($_); } } for $i (1 .. $sentence->num_linkages) { $linkage = $sentence->linkage($i); $linkage->compute_union; $sublinkage = $linkage->sublinkage($linkage->num_sublinkages); print $parser->get_diagram($sublinkage), "\n"; } } __DATA__ __PROMPT__ The issue of gene patents is a vexing one Patents on genes are a vexed issue Gene patenting is an issue that vexes The vexacious issue is patented genes Patentable genes vex the issue Time flies like an arrow IO-Prompt-0.997004/examples/menu.pl000644 000765 000024 00000001446 10244760511 017274 0ustar00damianstaff000000 000000 use IO::Prompt; my $answer = prompt 'Please select the most correct answer...', -1, -menu => [ 'Perl is an interpreted language', 'Perl is the Swiss Army Chainsaw', 'Perl rocks, dude!', 'All of the above', ]; print "You chose: [$answer]\n\n"; $answer = prompt 'Please select the most correct answer...', -1, -menu => { interpreted => 'Perl is an interpreted language', Swiss => 'Perl is the Swiss Army Chainsaw', Rocks => 'Perl rocks, dude!', all => 'All of the above', }; print "You chose: [$answer]\n\n"; IO-Prompt-0.997004/examples/nonl.pl000755 000765 000024 00000000312 10244760354 017275 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # Sometimes it's useful to change &prompt's response to a newline... use IO::Prompt; prompt "type something: ", -nl => ''; prompt " and something else -->", -newline => "<--\n"; IO-Prompt-0.997004/examples/num.pl000755 000765 000024 00000000354 10244760354 017134 0ustar00damianstaff000000 000000 use IO::Prompt; # You can constrain input to be numeric, or even integral... my $how_many = prompt -number => 'How many? '; print "You asked for $how_many\n"; $how_many = prompt -i => 'How many? '; print "You asked for $how_many\n"; IO-Prompt-0.997004/examples/passwd.pl000755 000765 000024 00000001004 10244760354 017627 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # Change what prompt echos for each input character # (except -- use the -nl flag for that)... use IO::Prompt; if (prompt "next: ", -echo => '*') { use Data::Dumper 'Dumper'; warn Dumper [$_]; } if (prompt "next: ", -echo => '.') { use Data::Dumper 'Dumper'; warn Dumper [$_]; } if (prompt "next: ", -echo => '') { use Data::Dumper 'Dumper'; warn Dumper [$_]; } if (prompt "next: ", -echo => '(*)') { use Data::Dumper 'Dumper'; warn Dumper [$_]; } IO-Prompt-0.997004/examples/record.pl000755 000765 000024 00000001315 10244760354 017611 0ustar00damianstaff000000 000000 use IO::Prompt -record; # Loading the module with the -record flag causes it to record all inputs # which are written to a file named ./__PROMPT__ # # The contents of ./__PROMPT__ are suitable for appending as your __DATA__ # section to recreate the input process that was recorded (but don't forget to # remove the -record flag first!) # prompt "next: ", -integer, -require => { 'next (must be > 0):' => sub { $_ > 0 } }; print "[$_]\n"; prompt "base: ", -i, -req => { '%s(an even number, please) ' => sub { $_ % 2 == 0 } }; print "[$_]\n"; prompt "base: ", -req => { 'base [ACGT]: ' => qr/^[ACGT]$/ }; print "[$_]\n"; prompt "base: ", -req => { 'base [ACGT]: ' => [qw(A C G T skip)] }; print "[$_]\n"; IO-Prompt-0.997004/examples/require.pl000755 000765 000024 00000001237 10244760354 020012 0ustar00damianstaff000000 000000 use IO::Prompt; # The -require flag allows you to specify conditions that must be met by # the input string... # # Each key of the hash is the error message to be printed if the corresponding # value doesn't match the input. A %s in the error message is replaced with # the current prompt. # prompt "next: ", -integer, -require => { 'next (must be > 0):' => sub { $_ > 0 } }; print "[$_]\n"; prompt "base: ", -i, -req => { '%s(an even number, please) ' => sub { $_ % 2 == 0 } }; print "[$_]\n"; prompt "base: ", -req => { 'base [ACGT]: ' => qr/^[ACGT]$/ }; print "[$_]\n"; prompt "base: ", -req => { 'base [ACGT]: ' => [qw(A C G T skip)] }; print "[$_]\n"; IO-Prompt-0.997004/examples/to.pl000755 000765 000024 00000001040 10244760354 016750 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # A filehandle in the argument list causes the prompt to be sent to # that filehandle, rather than to the terminal... # use IO::Prompt; open my $fh, '>/dev/null' or die $!; print "No prompt should appear here... (type anything)\n"; if (prompt $fh, "> ", -line) { print; } if (prompt \*STDERR, "type some more> ", -line) { print; } use IO::File; $fh = new IO::File, "<$0" or die $!; print "This should fail at line ", __LINE__ + 1, " (read-only filehandle)...\n"; if (prompt $fh, "> ", -line) { print; } IO-Prompt-0.997004/examples/tty.pl000755 000765 000024 00000000731 10244760354 017154 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # The -tty flag ensures that the prompt is sent to the tty, no matter what... use IO::Prompt; if (prompt -tty, "tty> ") { use Data::Dumper 'Dumper'; warn Dumper [$_]; } open $fh, ">/dev/null"; if (prompt -tty, $fh, "tty> ") { use Data::Dumper 'Dumper'; warn Dumper [$_]; } if (prompt "in> ") { use Data::Dumper 'Dumper'; warn Dumper [$_]; } if (prompt $fh, "in> ") { use Data::Dumper 'Dumper'; warn Dumper [$_]; } IO-Prompt-0.997004/examples/underscore.pl000755 000765 000024 00000001237 11175510015 020476 0ustar00damianstaff000000 000000 use IO::Prompt; # This example demostrates how prompt autosets $_ when appropriate # Case 1... undef $_; my $first = prompt "1> "; print defined() ? "(\$_ was '$_')\n" : "(\$_ was undef)\n"; print "Got: $first\n"; # Case 2... undef $_; prompt "2> "; print defined() ? "(\$_ was '$_')\n" : "(\$_ was undef)\n"; print "Got: [$_]\n"; # Case 3... undef $_; while (prompt "3> ") { print defined() ? "(\$_ was '$_')\n" : "(\$_ was undef)\n"; print "Got: [$_]\n"; last if $_ ne "\n"; } # Case 4... undef $_; while (my $next = prompt "4> ") { print defined() ? "(\$_ was '$_')\n" : "(\$_ was undef)\n"; print "Got: $next\n"; last if $next ne "\n"; } IO-Prompt-0.997004/examples/while_until.pl000755 000765 000024 00000000667 10244760354 020667 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # The -while and -until flags control whether &prompt returns true on a given # input... use IO::Prompt; while (prompt "first while digit: ", -while => qr/\d/) { print "You said '$_'\n"; } while (prompt "second until digit: ", -until => qr/\d/) { print "You said '$_'\n"; } while ( prompt "third while digit (not zero): ", -while => qr/\d/, -until => qr/0/ ) { print "You said '$_'\n"; } IO-Prompt-0.997004/examples/yesno.pl000755 000765 000024 00000001122 10244760354 017464 0ustar00damianstaff000000 000000 #! /usr/bin/perl -w # Variations on the yes/no theme... # use IO::Prompt; 1 until prompt(-YN1, "Continue char (Y/N): "); 1 until prompt(-yn1, "Continue char (y/n): "); 1 until prompt(-yesno1, "Continue char (y/n): "); 1 until prompt(-yes1, "Continue char (y/*): "); 1 until prompt(-YES1, "Continue char (Y/*): "); 1 until prompt(-Y1, "Continue char (Y/*): "); 1 until prompt(-yn, "Continue line (y/n): "); 1 until prompt(-yes, "Continue line (y/*): "); 1 until prompt(-YN, "Continue line (Y/N): "); 1 until prompt(-Y, "Continue line (Y/*): "); print "Done\n";