.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Term::Prompt 3pm" .TH Term::Prompt 3pm "2015-05-01" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Term::Prompt \- Perl extension for prompting a user for information .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Term::Prompt; \& $value = prompt(...); \& \& use Term::Prompt qw(termwrap); \& print termwrap(...); \& \& $Term::Prompt::MULTILINE_INDENT = \*(Aq\*(Aq; .Ve .SH "PREREQUISITES" .IX Header "PREREQUISITES" You must have Text::Wrap and Term::ReadKey available on your system. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This main function of this module is to accept interactive input. You specify the type of inputs allowed, a prompt, help text and defaults and it will deal with the user interface, (and the user!), by displaying the prompt, showing the default, and checking to be sure that the response is one of the legal choices. Additional 'types' that could be added would be a phone type, a social security type, a generic numeric pattern type... .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "prompt" .IX Subsection "prompt" This is the main function of the module. Its first argument determines its usage and is one of the following single characters: .PP .Vb 12 \& x: do not care \& a: alpha\-only \& n: numeric\-only \& i: ignore case \& c: case sensitive \& r: ranged by the low and high values \& f: floating\-point \& y: yes/no \& e: regular expression \& s: sub (actually, a code ref, but \*(Aqc\*(Aq was taken) \& p: password (keystrokes not echoed) \& m: menu .Ve .IP "x: do not care" 4 .IX Item "x: do not care" .Vb 1 \& $result = prompt(\*(Aqx\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp \&\f(CW$result\fR is whatever the user types. .IP "a: alpha-only" 4 .IX Item "a: alpha-only" .Vb 1 \& $result = prompt(\*(Aqa\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp \&\f(CW$result\fR is a single 'word' consisting of [A\-Za\-z] only. The response is rejected until it conforms. .IP "n: numeric-only" 4 .IX Item "n: numeric-only" .Vb 1 \& $result = prompt(\*(Aqn\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp The result will be a positive integer or 0. .Sp .Vb 1 \& $result = prompt(\*(Aq\-n\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp The result will be a negative integer or 0. .Sp .Vb 1 \& $result = prompt(\*(Aq+\-n\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp The result will be a any integer or 0. .IP "i: ignore case" 4 .IX Item "i: ignore case" .Vb 2 \& $result = prompt(\*(Aqi\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& \*(Aqlegal_options\-ignore\-case\-list\*(Aq); .Ve .IP "c: case sensitive" 4 .IX Item "c: case sensitive" .Vb 2 \& $result = prompt(\*(Aqc\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& \*(Aqlegal_options\-case\-sensitive\-list\*(Aq); .Ve .IP "r: ranged by the low and high values" 4 .IX Item "r: ranged by the low and high values" .Vb 2 \& $result = prompt(\*(Aqr\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& \*(Aqlow\*(Aq, \*(Aqhigh\*(Aq); .Ve .IP "f: floating-point" 4 .IX Item "f: floating-point" .Vb 1 \& $result = prompt(\*(Aqf\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq); .Ve .Sp The result will be a floating-point number. .IP "y: yes/no" 4 .IX Item "y: yes/no" .Vb 1 \& $result = prompt(\*(Aqy\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq) .Ve .Sp The result will be 1 for y, 0 for n. A default not starting with y, Y, n or N will be treated as y for positive, n for negative. .IP "e: regular expression" 4 .IX Item "e: regular expression" .Vb 2 \& $result = prompt(\*(Aqe\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& \*(Aqregular expression\*(Aq); .Ve .Sp The regular expression has and implicit ^ and $ surrounding it; just put in .* before or after if you need to free it up before or after. .IP "s: sub" 4 .IX Item "s: sub" .Vb 4 \& $result = prompt(\*(Aqs\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& sub { warn \*(AqYour input was \*(Aq . shift; 1 }); \& $result = prompt(\*(Aqs\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq, \& \e&my_custom_validation_handler); .Ve .Sp User reply is passed to given code reference as first and only argument. If code returns true, input is accepted. .IP "p: password" 4 .IX Item "p: password" .Vb 1 \& $result = prompt(\*(Aqp\*(Aq, \*(Aqtext prompt\*(Aq, \*(Aqhelp prompt\*(Aq, \*(Aqdefault\*(Aq ); .Ve .Sp \&\f(CW$result\fR is whatever the user types, but the characters are not echoed to the screen. .IP "m: menu" 4 .IX Item "m: menu" .Vb 10 \& @results = prompt( \& \*(Aqm\*(Aq, \& { \& prompt => \*(Aqtext prompt\*(Aq, \& title => \*(AqMy Silly Menu\*(Aq, \& items => [ qw (foo bar baz biff spork boof akak) ], \& order => \*(Aqacross\*(Aq, \& rows => 1, \& cols => 1, \& display_base => 1, \& return_base => 0, \& accept_multiple_selections => 0, \& accept_empty_selection => 0, \& ignore_whitespace => 0, \& separator => \*(Aq[^0\-9]+\*(Aq \& }, \& \*(Aqhelp prompt\*(Aq, \& \*(Aqdefault\*(Aq); .Ve .Sp This will create a menu with numbered items to select. You replace the normal \fIprompt\fR argument with a hash reference containing this information: .RS 4 .IP "prompt" 4 .IX Item "prompt" The prompt string. .IP "title" 4 .IX Item "title" Text printed above the menu. .IP "items" 4 .IX Item "items" An array reference to the list of text items to display. They will be numbered ascending in the order presented. .IP "order" 4 .IX Item "order" If set to 'across', the item numbers run across the menu: .Sp .Vb 3 \& 1) foo 2) bar 3) baz \& 4) biff 5) spork 6) boof \& 7) akak .Ve .Sp If set to 'down', the item numbers run down the menu: .Sp .Vb 3 \& 1) foo 4) biff 7) akak \& 2) bar 5) spork \& 3) baz 6) boof .Ve .Sp \&'down' is the default. .IP "rows,cols" 4 .IX Item "rows,cols" Forces the number of rows and columns. Otherwise, the number of rows and columns is determined from the number of items and the maximum length of an item with its number. .Sp Usually, you would set rows = 1 or cols = 1 to force a non-wrapped layout. Setting both in tandem is untested. Cavet programmer. .IP "display_base,return_base" 4 .IX Item "display_base,return_base" Internally, the items are indexed the 'Perl' way, from 0 to scalar \&\-1. The display_base is the number added to the index on the menu display. The return_base is the number added to the index before the reply is returned to the programmer. .Sp The defaults are 1 and 0, respectively. .IP "accept_multiple_selections" 4 .IX Item "accept_multiple_selections" When set to logical true (1 will suffice), more than one menu item may be selected. The return from \fI\fIprompt()\fI\fR will be an array or array ref, depending on how it is called. .Sp The default is 0. The return value is a single scalar containing the selection. .IP "accept_empty_selection" 4 .IX Item "accept_empty_selection" When set to logical true (1 will suffice), if no items are selected, the menu will not be repeated and the 'empty' selection will be returned. The value of an 'empty' selection is an empty array or a reference to same, if \fIaccept_multiple_selections\fR is in effect, or \&\fIundef\fR if not. .IP "separator" 4 .IX Item "separator" A regular expression that defines what characters are allowed between multiple responses. The default is to allow all non-numeric characters to be separators. That can cause problems when a user mistakenly enters the lead letter of the menu item instead of the item number. You are better off replacing the default with something more reasonable, such as: .Sp .Vb 3 \& [,] ## Commas \& [,/] ## Commas or slashes \& [,/\es] ## Commas or slashes or whitespace .Ve .IP "ignore_whitespace" 4 .IX Item "ignore_whitespace" When set, allows spaces between menu responses to be ignored, so that .Sp .Vb 1 \& 1, 5, 6 .Ve .Sp is collapsed to .Sp .Vb 1 \& 1,5,6 .Ve .Sp before parsing. \fB\s-1NOTE:\s0\fR Do not set this option if you are including whitespace as a legal separator. .IP "ignore_empties" 4 .IX Item "ignore_empties" When set, consecutive separators will not result in an empty entry. For example, without setting this option: .Sp .Vb 1 \& 1,,8,9 .Ve .Sp will result in a return of .Sp .Vb 1 \& (1,\*(Aq\*(Aq,8,9) .Ve .Sp When set, the return will be: .Sp .Vb 1 \& (1,8,9) .Ve .Sp which is probably what you want. .RE .RS 4 .RE .SS "Other Functions and Variables" .IX Subsection "Other Functions and Variables" .IP "termwrap" 4 .IX Item "termwrap" Part of Term::Prompt is the optionally exported function termwrap, which is used to wrap lines to the width of the currently selected filehandle (or to \s-1STDOUT\s0 or \s-1STDERR\s0 if the width of the current filehandle cannot be determined). It uses the GetTerminalSize function from Term::ReadKey then Text::Wrap. .IP "\s-1MULTILINE_INDENT\s0" 4 .IX Item "MULTILINE_INDENT" This package variable holds the string to be used to indent lines of a multiline prompt, after the first line. The default is \*(L"\et\*(R", which is how the module worked before the variable was exposed. If you do not want \s-1ANY\s0 indentation: .Sp .Vb 1 \& $Term::Prompt::MULTILINE_INDENT = \*(Aq\*(Aq; .Ve .SS "Text and Help Prompts" .IX Subsection "Text and Help Prompts" What, you might ask, is the difference between a 'text prompt' and a \&'help prompt'? Think about the case where the 'legal_options' look something like: '1\-1000'. Now consider what happens when you tell someone that '0' is not between 1\-1000 and that the possible choices are: :) 1 2 3 4 5 ..... This is what the 'help prompt' is for. .PP It will work off of unique parts of 'legal_options'. .PP Changed by Allen \- if you capitalize the type of prompt, it will be treated as a true 'help prompt'; that is, it will be printed \s-1ONLY\s0 if the menu has to be redisplayed due to and entry error. Otherwise, it will be treated as a list of options and displayed only the first time the menu is displayed. .PP Capitalizing the type of prompt will also mean that a return may be accepted as a response, even if there is no default; whether it actually is will depend on the type of prompt. Menus, for example, do not do this. .SH "AUTHOR" .IX Header "AUTHOR" Original Author: Mark Henderson (henderson@mcs.anl.gov or systems@mcs.anl.gov). Derived from im_prompt2.pl, from anlpasswd (see ftp://info.mcs.anl.gov/pub/systems/), with permission. .PP Contributors: .PP E. Allen Smith (easmith@beatrice.rutgers.edu): Revisions for Perl 5, additions of alternative help text presentation, floating point type, regular expression type, yes/no type, line wrapping and regular expression functionality added by E. Allen Smith. .PP Matthew O. Persico (persicom@cpan.org): Addition of menu functionality and \f(CW$Term::Prompt::MULTILINE_INDENT\fR. .PP Tuomas Jormola (tjormola@cc.hut.fi): Addition of code refs. .PP Current maintainer: Matthew O. Persico (persicom@cpan.org) .SH "SEE ALSO" .IX Header "SEE ALSO" perl, Term::ReadKey, and Text::Wrap. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2004 by Matthew O. Persico .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available.