Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Term::Prompt(3)	      User Contributed Perl Documentation      Term::Prompt(3)

       Term::Prompt - Perl extension for prompting a user for information

	   use Term::Prompt;
	   $value = prompt(...);

	   use Term::Prompt qw(termwrap);
	   print termwrap(...);

	   $Term::Prompt::MULTILINE_INDENT = '';

       You must	have Text::Wrap	and Term::ReadKey available on your system.

       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...

       This is the main	function of the	module.	Its first argument determines
       its usage and is	one of the following single characters:

	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 'c' was taken)
	p: password (keystrokes	not echoed)
	m: menu

       x: do not care
	    $result = prompt('x', 'text	prompt', 'help prompt',	'default' );

	   $result is whatever the user	types.

       a: alpha-only
	    $result = prompt('a', 'text	prompt', 'help prompt',	'default' );

	   $result is a	single 'word' consisting of [A-Za-z] only. The
	   response is rejected	until it conforms.

       n: numeric-only
	    $result = prompt('n', 'text	prompt', 'help prompt',	'default' );

	   The result will be a	positive integer or 0.

	    $result = prompt('-n', 'text prompt', 'help	prompt', 'default' );

	   The result will be a	negative integer or 0.

	    $result = prompt('+-n', 'text prompt', 'help prompt', 'default' );

	   The result will be a	any integer or 0.

       i: ignore case
	    $result = prompt('i', 'text	prompt', 'help prompt',	'default',

       c: case sensitive
	    $result = prompt('c', 'text	prompt', 'help prompt',	'default',

       r: ranged by the	low and	high values
	    $result = prompt('r', 'text	prompt', 'help prompt',	'default',
			     'low', 'high');

       f: floating-point
	    $result = prompt('f', 'text	prompt', 'help prompt',	'default');

	   The result will be a	floating-point number.

       y: yes/no
	    $result = prompt('y', 'text	prompt', 'help prompt',	'default')

	   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.

       e: regular expression
	    $result = prompt('e', 'text	prompt', 'help prompt',	'default',
			     'regular expression');

	   The regular expression has and implicit ^ and $ surrounding it;
	   just	put in .* before or after if you need to free it up before or

       s: sub
	    $result = prompt('s', 'text	prompt', 'help prompt',	'default',
			     sub { warn	'Your input was	' . shift; 1 });
	    $result = prompt('s', 'text	prompt', 'help prompt',	'default',

	   User	reply is passed	to given code reference	as first and only
	   argument.  If code returns true, input is accepted.

       p: password
	    $result = prompt('p', 'text	prompt', 'help prompt',	'default' );

	   $result is whatever the user	types, but the characters are not
	   echoed to the screen.

       m: menu
	    @results = prompt(
				   prompt	    => 'text prompt',
				   title	    => 'My Silly Menu',
		       items		=> [ qw	(foo bar baz biff spork	boof akak) ],
				   order	    => 'across',
				   rows		    => 1,
				   cols		    => 1,
				   display_base	    => 1,
				   return_base	    => 0,
				   accept_multiple_selections => 0,
				   accept_empty_selection     => 0,
		       ignore_whitespace => 0,
		       separator	 => '[^0-9]+'
			       'help prompt',

	   This	will create a menu with	numbered items to select. You replace
	   the normal prompt argument with a hash reference containing this

	       The prompt string.

	       Text printed above the menu.

	       An array	reference to the list of text items to display.	They
	       will be numbered	ascending in the order presented.

	       If set to 'across', the item numbers run	across the menu:

		1) foo	  2) bar    3) baz
		4) biff	  5) spork  6) boof
		7) akak

	       If set to 'down', the item numbers run down the menu:

		1) foo	  4) biff   7) akak
		2) bar	  5) spork
		3) baz	  6) boof

	       'down' is the default.

	       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.

	       Usually,	you would set rows = 1 or cols = 1 to force a non-
	       wrapped layout. Setting both in tandem is untested. Cavet

	       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.

	       The defaults are	1 and 0, respectively.

	       When set	to logical true	(1 will	suffice), more than one	menu
	       item may	be selected. The return	from prompt() will be an array
	       or array	ref, depending on how it is called.

	       The default is 0. The return value is a single scalar
	       containing the 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
	       accept_multiple_selections is in	effect,	or undef if not.

	       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:

		[,]    ## Commas
		[,/]   ## Commas or slashes
		[,/\s] ## Commas or slashes or whitespace

	       When set, allows	spaces between menu responses to be ignored,
	       so that

		1, 5, 6

	       is collapsed to


	       before parsing. NOTE: Do	not set	this option if you are
	       including whitespace as a legal separator.

	       When set, consecutive separators	will not result	in an empty
	       entry. For example, without setting this	option:


	       will result in a	return of


	       When set, the return will be:


	       which is	probably what you want.

   Other Functions and Variables
	   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 STDOUT or STDERR if the width of the current
	   filehandle cannot be	determined).  It uses the GetTerminalSize
	   function from Term::ReadKey then Text::Wrap.

	   This	package	variable holds the string to be	used to	indent lines
	   of a	multiline prompt, after	the first line.	The default is "\t",
	   which is how	the module worked before the variable was exposed. If
	   you do not want ANY indentation:

	    $Term::Prompt::MULTILINE_INDENT = '';

   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.

       It will work off	of unique parts	of 'legal_options'.

       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 ONLY 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.

       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.

       Original	Author:	Mark Henderson ( or Derived from, from anlpasswd	(see, with permission.


       E. Allen	Smith ( 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.

       Matthew O. Persico ( Addition	of menu	functionality
       and $Term::Prompt::MULTILINE_INDENT.

       Tuomas Jormola ( Addition of	code refs.

       Current maintainer: Matthew O. Persico (

       perl, Term::ReadKey, and	Text::Wrap.

       Copyright (C) 2004 by Matthew O.	Persico

       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.

perl v5.32.0			  2007-07-04		       Term::Prompt(3)


Want to link to this manual page? Use this URL:

home | help