Fink::CLI(3) Fink documentation Fink::CLI(3)NAMEFink::CLI - functions for user interaction
DESCRIPTION
These functions handle a variety of output formatting and user
interaction/response tasks.
Functions
No functions are exported by default. You can get whichever ones you
need with things like:
use Fink::CLI '&prompt_boolean';
use Fink::CLI qw(&print_breaking &prompt);
word_wrap
my @lines = word_wrap $string, $length;
my @lines = word_wrap $string, $length, $prefix1;
my @lines = word_wrap $string, $length, $prefix1, $prefix2;
Word wraps a single-line string $string to maximum length $length,
and returns the resulting lines. Breaking is performed only at
space characters.
Optionally, prefixes can be defined to prepend to each line
printed: $prefix1 is prepended to the first line, $prefix2 is
prepended to all other lines. If only $prefix1 is defined, that
will be prepended to all lines.
print_breaking
print_breaking $string;
print_breaking $string, $linebreak;
print_breaking $string, $linebreak, $prefix1;
print_breaking $string, $linebreak, $prefix1, $prefix2;
Wraps $string, breaking at word-breaks, and prints it on STDOUT.
The screen width is determined by get_term_width, or if that fails,
the package global variable $linelength. Breaking is performed only
at space chars. A linefeed will be appended to the last line
printed unless $linebreak is defined and false.
Optionally, prefixes can be defined to prepend to each line
printed: $prefix1 is prepended to the first line, $prefix2 is
prepended to all other lines. If only $prefix1 is defined, that
will be prepended to all lines.
If $string is a multiline string (i.e., it contains embedded
newlines other than an optional one at the end of the whole
string), the prefix rules are applied to each contained line
separately. That means $prefix1 affects the first line printed for
each line in $string and $prefix2 affects all other lines printed
for each line in $string.
print_breaking_stderr
This is a wrapper around print_breaking that causes output to go to
STDERR. See print_breaking for a complete description of parameters
and usage.
die_breaking
die_breaking $message;
Raises an exception like 'die', but formats the error message with
print_breaking.
Note that this does not have all the special features of 'die',
such as adding the line number on which the error occurs or
propagating previous errors if no argument is passed.
rejoin_text
print_breaking rejoin_text <<EOMSG
Here is paragraph
one.
And
two.
EOMSG
This function takes text in which multiple newlines are used to
delimit paragraphs and removes newlines from within paragraphs.
Multiple newlines (and any intervening whitespace) become a double
newline. Each "internal" newline becomes a single space.
prompt
my $answer = prompt $prompt;
my $answer = prompt $prompt, %options;
Ask the user a question and return the answer. The user is prompted
via STDOUT/STDIN using $prompt (which is word-wrapped). The
trailing newline from the user's entry is removed.
The %options are given as option => value pairs. The following
options are known:
default (optional)
If the option 'default' is given, then its value will be
returned if no input is detected.
This can occur if the user enters a null string, or if Fink is
configured to automatically accept defaults (i.e., bin/fink was
invoked with the -y or --yes option).
Default value: null string
timeout (optional)
The 'timeout' option establishes a wait period (in seconds) for
the prompt, after which the default answer will be used. If a
timeout is given, any existing alarm() is destroyed.
Default value: no timeout
category (optional)
A string to categorize this prompt.
prompt_boolean
my $answer = prompt_boolean $prompt;
my $answer = prompt_boolean $prompt, %options;
Ask the user a yes/no question and return the truth-value of the
answer. The user is prompted via STDOUT/STDIN using $prompt (which
is word-wrapped).
The %options are given as option => value pairs. The following
options are known:
default (optional)
If the option 'default' is given, then its truth-value will be
returned if no input is detected.
This can occur if the user enters a null string, or if Fink is
configured to automatically accept defaults (i.e., bin/fink was
invoked with the -y or --yes option).
Default value: true
timeout (optional)
The 'timeout' option establishes a wait period (in seconds) for
the prompt, after which the default answer will be used. If a
timeout is given, any existing alarm() is destroyed.
Default value: no timeout
category (optional)
A string to categorize this prompt.
prompt_selection
my $answer = prompt_selection $prompt, %options;
Ask the user a multiple-choice question and return the value for
the choice. The user is prompted via STDOUT/STDIN using $prompt
(which is word-wrapped) and a list of choices. The choices are
numbered (beginning with 1) and the user selects by number.
The %options are given as option => value pairs. The following
options are known:
choices (required)
The option 'choices' must be a reference to an ordered pairwise
array [ label1 => value1, label2 => value2, ... ]. The labels
will be displayed to the user; the values are the return values
if that option is chosen.
default (optional)
If the option 'default' is given, then it determines which
choice will be returned if no input is detected.
This can occur if the user enters a null string, or if Fink is
configured to automatically accept defaults (i.e., bin/fink was
invoked with the -y or --yes option).
The following formats are recognized for the 'default' option:
@default = []; # choice 1
@default = ["number", $number]; # choice $number
@default = ["label", $label]; # first choice with label $label
@default = ["value", $label]; # first choice with value $value
Default value: choice 1
timeout (optional)
The 'timeout' option establishes a wait period (in seconds) for
the prompt, after which the default answer will be used. If a
timeout is given, any existing alarm() is destroyed.
Default value: no timeout
intro (optional)
A text block that will be displayed before the list of options.
This contrasts with the $prompt, which is goes afterwards.
category (optional)
A string to categorize this prompt.
should_skip_prompt
my $bool = should_skip_prompt $category;
Returns whether or not Fink should skip prompts of the given
category. A false $category represents an uncategorized prompt.
get_input
my $answer = get_input $prompt;
my $answer = get_input $prompt, %options;
Prints the string $prompt, then gets a single line of input from
STDIN.
Returns the entered string (including the trailing newline), or a
null string if the timeout expires or immediately (without waiting
for input) if fink is suppressing the prompt (run with the -y
option or with an appropriate SuppressPrompts). If not suppressing
a prompt, this function destroys any pre-existing alarm(). STDIN
is flushed before accepting input, so stray keystrokes prior to the
prompt are ignored.
The options hash can contain the following keys:
timeout => $timeout (optional)
If $timeout is zero or not given, will block forever waiting
for input. If $timeout is given and is positive, will only wait
that many seconds for input before giving up.
category => $category (optional)
Categorizes this prompt. If $category is listed in the comma-
delimited SuppressPrompts in fink.conf, will use the default
value and not prompt the user.
get_term_width
my $width = get_term_width;
This function returns the width of the terminal window, or zero if
STDOUT is not a terminal. Uses Term::ReadKey if it is available,
greps the TERMCAP env var if ReadKey is not installed, tries tput
if neither are available, and if nothing works just returns 80.
This function always returns a number, not undef.
capture
my $return = capture { BLOCK }, \$out, \$err;
Executes BLOCK, but intercepts STDOUT and STDERR, putting them into
the arguments $out and $err. The return value is simply the BLOCK's
return value.
If $out and $err point to the same scalar, STDOUT and STDERR will
have their outputs merged.
Fink 0.36.3.1 2013-12-30 Fink::CLI(3)
