Ask - ask your users about stuff
Object-oriented style:
use Ask; my $ask = Ask->detect; if ($ask->question(text => "Are you happy?") and $ask->question(text => "Do you know it?") and $ask->question(text => "Really want to show it?")) { $ask->info(text => "Then clap your hands!"); }
Functional style:
use Ask ':all'; if (question("Are you happy?") and question("Do you know it?") and question("Really want to show it?")) { info("Then clap your hands!"); }
The Ask suite is a set of modules for interacting with users; prompting them for information, displaying messages, warnings and errors, etc.
Ask
There are already countless CPAN modules for doing this sort of thing, but what sets Ask apart from them is that Ask will detect how your script is being run (in a terminal, headless, etc) and choose an appropriate way to interact with the user.
Ask->instance
Singleton pattern. Can also be passed an argument to use it as a setter.
Ask->detect(%arguments)
A constructor, sort of. It inspects the program's environment and returns an object that implements the Ask API (see below).
Backend-specific arguments can be provided:
my $ask = Ask->detect( %common_args, 'Ask::STDIO' => \%stdio_args, 'Ask::Zenity' => \%zenity_args, );
Note that these objects don't usually inherit from Ask, so the following will typically be false:
my $ask = Ask->detect(%arguments); $ask->isa("Ask");
Instead, check:
my $ask = Ask->detect(%arguments); $ask->DOES("Ask::API");
Ask->backends
Returns a list of available backends. Each backend is a Perl class name. Some of the backends may be available (i.e. installed and able to be compiled) without being usable under current circumstances (e.g. the Gtk2 backend is available but cannot be used because no X server is running). To check usability, instantiate the class and call is_usable on the instance.
is_usable
The list is sorted in "quality" order, best to worst, though quality is subjective.
Ask->plugins
The same as Ask->backends, but doesn't check that each result is a loadable Perl class, and doesn't sort them in any particular order.
Objects returned by the detect method implement the Ask API. This section documents that API.
detect
The following methods are provided by objects implementing the Ask API. They are largely modeled on the interface for GNOME Zenity.
info(text => $text, %arguments)
Display a message to the user.
Setting the argument no_wrap to true can be used to hint that line wrapping should be avoided.
no_wrap
The lang argument can be used to indicate the language of the text as an ISO 639-1 code (e.g. "en" for English). Not all objects implementing the Ask API will pay attention to this hint, so don't be too surprised to see text in French with an English "OK" button underneath!
lang
text
warning(text => $text, %arguments)
Display a warning to the user.
Supports the same arguments as info.
info
error(text => $text, %arguments)
Display an error message (not necessarily fatal) to the user.
entry(%arguments)
Ask the user to enter some text. Returns that text.
The text argument is supported as a way of communicating what you'd like them to enter. The hide_text argument can be set to true to hint that the text entered should not be displayed on screen (e.g. password input).
hide_text
The default argument can be used to supply a default return value if the user cannot be asked for some reason (e.g. running on an unattended terminal).
default
The lang argument can be used to indicate the language of the text as an ISO 639-1 code (e.g. "en" for English).
question(text => $text, %arguments)
Ask the user to answer an affirmative/negative question (i.e. OK/cancel, yes/no) defaulting to affirmative. Returns boolean.
The text argument is the text of the question; the ok_label argument can be used to set the label for the affirmative button; the cancel_label argument for the negative button.
ok_label
cancel_label
file_selection(%arguments)
Ask the user for a file name. Returns the file name. No checks are made to ensure the file exists.
The multiple argument can be used to indicate that multiple files may be selected (they are returned as a list); the directory argument can be used to hint that you want a directory.
multiple
directory
The default argument can be used to supply a default return value if the user cannot be asked for some reason (e.g. running on an unattended terminal). If multiple is true, then this must be an arrayref.
Until version 0.011, returned values are strings. Thereafter, returned values are Path::Tiny objects.
single_choice(text => $text, choices => \@choices)
Asks the user to select a single option from many choices.
For example:
my $answer = $ask->single_choice( text => "If a=1, b=2. What is a+b?", choices => [ [ A => 12 ], [ B => 3 ], [ C => 2 ], [ D => 42 ], [ E => "Fish" ], ], );
The choices are identifier => label pairs. The identifiers are not necessarily displayed to the user making the choice; the labels are. The function returns the identifier for the chosen option.
identifier => label
The lang argument can be used to indicate the language of the text and labels as an ISO 639-1 code (e.g. "en" for English).
multiple_choice(text => $text, choices => \@choices)
Asks the user to select zero or more options from many choices.
my @ingredients = $ask->multiple_choice( text => "What do you want on your pizza?", choices => [ [ cheese => 'Cheese' ], [ tomato => 'Tomato' ], [ ham => 'Ham' ], [ pineapple => 'Pineapple' ], [ chocolate => 'Chocolate' ], ], );
Returns list of identifiers.
The default argument can be used to supply a default return value if the user cannot be asked for some reason (e.g. running on an unattended terminal). It must be an arrayref.
If you wish to create your own implementation of the Ask API, please read Ask::API for more information.
Implementing Ask::API allows you to extend Ask to other environments.
To add extra methods to the Ask API you may use Moo roles:
{ package AskX::Method::Password; use Moo::Role; sub password { my ($self, %o) = @_; $o{hide_text} //= 1; $o{text} //= "please enter your password"; $self->entry(%o); } } my $ask = Ask->detect(traits => ['AskX::Method::Password']); say "GOT: ", $ask->password;
You can optionally export the Ask methods as functions. The functions behave differently from the object-oriented interface in one regard; if called with one parameter, it's taken to be the "text" named argument.
use Ask qw( question info ); if (question("Are you happy?") and question("Do you know it?") and question("Really want to show it?")) { info("Then clap your hands!"); }
Ask uses Sub::Exporter::Progressive, so exported functions may be renamed:
use Ask question => { -as => 'interrogate' }, info => { -as => 'notify' }, ;
It is strongly recommended that you pass a lang argument with each method call. Not all backends yet pay attention to it.
See also AskX::AutoLang as a way to avoid passing lang => "fu" to every single method call!
lang => "fu"
The PERL_ASK_BACKEND environment variable can be used to influence the outcome of Ask->detect. Indeed, it trumps all other factors. If set, it should be a full class name.
PERL_ASK_BACKEND
Ask->detect
If either of the AUTOMATED_TESTING or PERL_MM_USE_DEFAULT environment variables are set to true, the Ask::Fallback backend will automatically be used.
AUTOMATED_TESTING
PERL_MM_USE_DEFAULT
Ask::Fallback
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Ask.
Terminal backends:
Ask::STDIO - very basic usage of STDIN/STDOUT/STDERR
Ask::Caroline - uses Caroline and Term::ANSIColor for better interaction
Ask::Clui - uses Term::Clui for better interaction
GUI backends:
Ask::Gtk - GUI using Gtk2.
Ask::Prima - GUI using Prima.
Ask::Tk - GUI using Tk.
Ask::Wx - GUI using Wx.
Ask::Zenity - GUI using the /usr/bin/zenity binary (part of GNOME)
/usr/bin/zenity
Backends which perform no real user interaction:
Ask::Callback - implementation for testing; redirects input and output to callback functions.
Ask::Fallback - returns default answers; for scripts running unattended.
See Ask::API for documentation of API internals.
See Ask::Question for an alternative way of using Ask.
Similar modules: IO::Prompt, IO::Prompt::Tiny and many others.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2012-2013, 2020 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
To install Ask, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ask
CPAN shell
perl -MCPAN -e shell install Ask
For more information on module installation, please visit the detailed CPAN module installation guide.