Long(3) User Contributed Perl Documentation Long(3)NAMEGetopt::GUI::LongSYNOPSIS
use Getopt::GUI::Long;
# pass useful config options to Configure
Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
GetOptions(\%opts,
["GUI:separator", "Important Flags:"],
["f|some-flag=s", "A flag based on a string"],
["o|other-flag", "A boloean"],
);
# or use references instead of a hash (less tested, however):
GetOptions(["some-flag=s", "perform some flag based on a value"] => \$flag,
["other-flag=s", "perform some flag based on a value"] => \$other);
# displays auto-help given the input above:
% opttest -h
Usage: opttest [OPTIONS] Other Arguments
OPTIONS:
Important Flags:
-f STRING A flag based on a string
-o A boloean
Help Options:
-h Display help options -- short flags preferred
--help Display help options -- long flags preferred
--help-full Display all help options -- short and long
# or long help:
% opttest --help
Usage: opttest [OPTIONS] Other Arguments
OPTIONS:
Important Flags:
--some-flag=STRING A flag based on a string
--other-flag A boloean
Help Options:
-h Display help options -- short flags preferred
--help Display help options -- long flags preferred
--help-full Display all help options -- short and long
# or a GUI screen:
(see http://net-policy.sourceforge.net/images/getopt_example.png )
DESCRIPTION
This module is a wrapper around Getopt::Long that extends the value of
the original Getopt::Long module to:
1) add a simple graphical user interface option screen if no
arguments are passed to the program. Thus, the arguments to
actually use are built based on the results of the user
interface. If arguments were passed to the program, the user
interface is not shown and the program executes as it normally
would and acts just as if Getopt::Long::GetOptions had been
called instead.
2) provide an auto-help mechanism such that -h and --help are
handled automatically. In fact, calling your program with -h
will default to showing the user a list of short-style arguments
when one exists for the option. Similarly --help will show the
user a list of long-style when possible. --help-full will list
all potential arguments for an option (short and long both).
It's designed to make the creation of graphical shells trivial
without the programmer having to think about it much as well as
providing automatic good-looking usage output without the
programmer needing to write usage() functions.
This also can turn normal command line programs into web CGI scripts
as well (automatically). If the Getopt::GUI::Long program is
installed as a CGI script then it will automatically prompt the user
for the same variables.
USAGE
The Getopt::GUI::Long module can work identically to the Getopt::Long
module but really benefits from some slightly different usage
conventions described below.
Option format:
Option strings passed should be formatted in one of the following ways:
Empty String
Empty strings are ignored by the non-GUI version of the command,
but are treated as vertical separators between questions when
displaying the GUI screen.
Standard flag specification string
EG: "some-flag|optional-flag=s"
This is the standard method by which Getopt::Long does things and
is merely treated the same way here. In this case, the text
presented to the user screen will be the first name in the list
("some-flag") in the above option. The type of wdget displayed
with the text will depend on the optional =s/i/whatever flag and
will be either a checkbox, entry box, ...
Array Reference
EG: ["some-flag|optional-flag=s", 'Prompt text', OTHER],
The values passed in this array are as follows:
0: Standard flag specification string
Same as always, and as above.
1: Prompt text about flag
The help text that should be shown to the user in the graphical
interface. In the example above rather than "some-flag" being
shown, "Prompt text" will be shown next to the widget instead.
If the prompt text is equal to "!GUI" then this option will not
be displayed (automatically at least) within the GUI.
2...: OTHER options
Beyond the name and description, key value pairs can indicate
more about how the option should be handled.
required => 1
Forces a screen option to be filled out by the user.
question => { QUESTION FORM }
question => [{ QUESTION1}, {QUESTION2}, ...]
These allows you to build custom QWizard widgets to meet a
particular question need. It's highly useful for doing
menus and single choice fields that normally command line
options don't handle well. For example consider a numeric
priority level between 0 and 10. The following question
definition will give them a menu rather than a fill in the
blank field:
['priority=i','Priority Level',
question => { type => 'menu', values => [1..10] }]
Note you can specify multiple question widgets if needed as
well, though this will probably be rare in usage.
QWizard question tokens
Any of the following items can be passed as well, which
will be added to the QWizard question structure. See the
QWizard documantion on "QUESTION DEFINITIONS" for details
on the usage of these.
type
helpdesc
helptext
default
check_value
doif
submit
refresh_on_change
handle_results
text
(Warning: Replaces the text already extracted from the
prompt text described above).
name
(Warning: Replaces the option name extracted from the
position 0 standard flag specification string above.
Do not use this unless you really know what you're
doing.)
[others TBD]
Special Flag Names
Flags that start with GUI: are not passed to the normal Getopt::Long
routines and are instead for internal GUI digestion only. If the GUI
screen is going to be displayed (remember: only if the user didn't
specify any options), these extra options control how the GUI behaves.
Some of these options requires some knowledge of the QWizard
programming system. Knowledge of QWizard should only be required if
you want to make use of those particular extra features.
GUI:guionly
EG: ['GUI:guionly', { type => 'checkbox', name => 'myguiflag'}]
Specifies a valid QWizard question(s) to only be shown when the gui
is displayed, and the specification is ignored during normal
command line usage.
GUI:separator
EG: ['GUI:separator', 'Task specific options:']
Inserts a label above a set of options to identify them as a group.
GUI:screen
EG: ['GUI:screen', 'Next Screen Title', ...]
Specifies that a break in the option requests should occur and the
remaining options should appear on another screen(s). This allows
applications with a lot of options to reduce the complexity it
offers users and offers a more "wizard" like approach to helping
them decide what they're trying to do.
You can also make this next screen definition conditional by
defining an earlier option that may be, say, a boolean flag called
"feature_flag". Using this you can then only go into the next
screen if the "feature_flag" was set by doing the following:
['feature-flag',
'turn on a special feature needing more options'],
['GUI:screen', 'Next Screen Title', doif => 'feature-flag']
['feature-arg1', 'extra argument #1 for special feature'],
...
Also, if you need to do more complex calculations use the qwparam()
function of the passed in QWizard object in a subroutine reference
instead:
['feature1','Turn on feature #1"],
['feature2','Turn on feature #2"],
['GUI:screen', 'Next Screen Title',
doif => sub {
return ($_[1]->qwparam('feature1') && $_[1]->qwparam('feature2'));
}]
GUI:otherargs_text
EG: ['GUI:otherargs', 'Files to process:']
Normally the GUI screen shows a "Other Arguments:" option at the
bottom of the main GUI screen to allow users to entry additional
flags (needed for file names, etc, and other non-option arguments
to be passed). However, since it doesn't know what these arguments
should be it can only provide a generic "Other Arguments:"
description. This setting lets you change that text to something
specific to what your application experts, such as "Files:" or
"HTML Files:" or something that helps the user understand what is
expected of them.
If you want to self-handle the argument prompting using other
QWizard constructs, then use the nootherargs token described below
instead.
GUI:nootherargs
EG: ['GUI:nootherargs', 1]
Normally the GUI screen shows a "Other Arguments:", or programmer
described text as described above, option at the bottom of the main
GUI screen. If you're going to handle the additional arguments
yourself in some way (using either some GUI:guionly or
(GUI:otherprimaries and GUI:submodules) flags), then you should
specify this so the other arguments field is not shown. You're
expected, in your self-handling code, to set the __otherargs
QWizard parameter to the final arguments that should be passed on.
GUI:nosavebutton
EG: ['GUI:nosavebutton', 1]
Normally the GUI screen offers a "save" menu that lets users save
their current screen settings for future calls. Using this setting
turns off this behavior so the button isn't shown.
GUI:otherprimaries
EG: ['GUI:otherprimaries', primaryname =>
{ title => '...', questions => [...] }]
Defines other primaries to be added to the QWizard primary set.
GUI:submodules
EG: ['GUI:submodules', 'primaryname']
Defines a list of other primaries that should be called after the
initial one.
GUI:post_answers
EG: ['GUI:post_answers', sub { do_something(); }]
Defines an option for QWizard post_answers subroutines to run.
GUI:actions
EG: ['GUI:actions', sub { do_something(); }]
Defines an option for QWizard actions subroutines to run.
GUI:hook_finished
EG: ['GUI:hook_finished', sub { do_something(); }]
Defines subroutine(s) to be called after the GUI has completely
finished.
GUI:run_button
EG: ['GUI:run_button', 'My Run Button']
Defines the text to use for the final "Run" button (which normally
just says "Run").
GUI:VERSION
If display_help is defined, and the above token is specified
Getopt::GUI::Long takes over the output for --version output as
well.
EG: ['GUI:VERSION','0.9']
Produces the --version help option:
Help Options:
-h Display help options -- short flags preferred
--help Display help options -- long flags preferred
--help-full Display all help options -- short and long
--version Display the version number
And also auto-handles the --version switch:
% PROGRAM --version
Version: 0.9
CONFIGURATION
If you call Getopt::GUI::Long's Configure routine, it will accept a
number of configure tokens and will pass the remaining ones to the
Getopt::Long Configure routine. The tokens that it recognizes itself
are described below:
display_help
The Getopt::GUI::Long package will auto-display help messages based
on the text included in the GetOptions call. No more writing those
silly usage() functions!
Note that this differs from the Getopt::Long's implementation of
the auto_help token in that the information is pulled from the
extended GetOptions called instead of the pod documentation.
The display_help token will automatically add the following options
to the options the application will accept, and will catch and
process them as well.
-h Command line help preferring short options if present in the
help specification.
--help
Command line help preferring long options if present in the
help specification.
--help-full
Shows all available option names for a given option
--gui
If the default GUI is not showing up because no_gui has been
specified, a sure can still call the application with only the
--gui flag to make it appear.
--no-gui
If the no_gui option hasn't been set and the user doesn't want
to see the GUI then they can use the --no-gui flag as the only
argument to ensure it doesn't appear.
capture_output
This tells the Getopt::GUI::Long module that it should caputure the
resulting STDOUT and STDERR results from the script and display the
results in a window once the script has finished.
no_gui
This option defaults to not presenting a GUI form for the user to
fill out unless they specify --gui as the first and only argument
on the command line.
allow_zero
By default the GUI will always pop up if zero-arguments have been
specified (or the help info will be displayed if no_gui is set).
This options specifies that zero arguments is a normal usage case.
Thus the only way to force the GUI or help to appear will be the
command line --gui flag.
Using the QWizard object for other purposes
The Getopt::GUI::Long qwizard object is stored at
$Getopt::GUI::Long::GUI_qw, which is usable for other GUI screens you
may need to create after the options screens have been processed. You
can also use it during the script to optionally display a progress
meter by making use of the QWizard::set_progress function. However,
you should test to see if the GUI screen mode was actually used before
operating with the object though. As an example:
$Getopt::GUI::Long::GUI_qw->set_progress(3/5)
if ($Getopt::GUI::Long::GUI_qw);
PORTABILITY
If programs desire to not require this module, the following code
snippit can be used instead which will not fail even if this module is
not available. To be used this way, the LocalGetOptions and
LocalOptionsMap functions should be copied to your perl script.
LocalGetOptions(\%opts,
["h|help", "Show help for command line options"],
["some-flag=s", "perform some flag based on a value"]);
sub LocalGetOptions {
if (eval {require Getopt::GUI::Long;}) {
import Getopt::GUI::Long;
# optional configure call
Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
return GetOptions(@_);
}
require Getopt::Long;
import Getopt::Long;
# optional configure call
Getopt::Long::Configure(qw(auto_help no_ignore_case));
GetOptions(LocalOptionsMap(@_));
}
sub LocalOptionsMap {
my ($st, $cb, @opts) = ((ref($_[0]) eq 'HASH')
? (1, 1, $_[0]) : (0, 2));
for (my $i = $st; $i <= $#_; $i += $cb) {
if ($_[$i]) {
next if (ref($_[$i]) eq 'ARRAY' && $_[$i][0] =~ /^GUI:/);
push @opts, ((ref($_[$i]) eq 'ARRAY') ? $_[$i][0] : $_[$i]);
push @opts, $_[$i+1] if ($cb == 2);
}
}
return @opts;
}
Usage as a CGI Script
If a Getopt::GUI::Long script is installed as a CGI script, then the
Getopt::GUI::Long system will automatically create a web front end for
the perl script. It will present the user with all the normal
arguments that it would normally to a Gtk2 or other windowing system.
It will not present the box for generic additional arguments since this
is not safe to do. If you trust your users (ie, you have an
authentication system in place) then you can set the allowcgiargs GUI
variable to make this box appear. Example invocation (not generally
recommended):
['GUI:allowcgiargs',1]
It also allows you to not present certain options to web users that you
will to command line users (some options may not be safe for CGI use).
You can do this by setting the nocgi variable in option definitions you
wish to disallow via CGI. E.G., if you had an option to specify a
location where to load configuration a file from, this would likely be
unsafe to publish in a CGI script. So remove it:
["c|config-file","Load a specific configuration file", nocgi => 1]
EXAMPLES
See the getopttest program in the examples directory for an exmaple
script that uses a lot of these features.
AUTHOR
Wes Hardaker, hardaker@users.sourceforge.net
COPYRIGHT and LICENSE
Copyright (c) 2006-2009, SPARTA, Inc. All rights reserved
Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
Getopt::GUI::Long is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
SEE ALSOperl(1)
modules: QWizard
HISTORY
This module was originally named Getopt::Long::GUI but the Getopt::Long
author wanted to reserve the Getopt::Long namespace entirely for
himself and thus it's been recently renamed to Getopt::GUI::Long
instead. The class tree isn't as clean this way, as this module still
inherits from Getopt::Long but it everything still works of course.
perl v5.14.0 2009-02-23 Long(3)
