1Long(3) User Contributed Perl Documentation Long(3)
2
6 Getopt::GUI::Long
7
9 use Getopt::GUI::Long;
10 # pass useful config options to Configure
12 Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
13 GetOptions(\%opts,
14 ["GUI:separator", "Important Flags:"],
15 ["f|some-flag=s", "A flag based on a string"],
16 ["o|other-flag", "A boloean"],
17 );
18 # or use references instead of a hash (less tested, however):
20 GetOptions(["some-flag=s", "perform some flag based on a value"] => \$flag,
22 ["other-flag=s", "perform some flag based on a value"] => \$other);
23 # displays auto-help given the input above:
25 % opttest -h
27 Usage: opttest [OPTIONS] Other Arguments
28 OPTIONS:
30 Important Flags:
32 -f STRING A flag based on a string
33 -o A boloean
34 Help Options:
36 -h Display help options -- short flags preferred
37 --help Display help options -- long flags preferred
38 --help-full Display all help options -- short and long
39 # or long help:
43 % opttest --help
45 Usage: opttest [OPTIONS] Other Arguments
46 OPTIONS:
48 Important Flags:
50 --some-flag=STRING A flag based on a string
51 --other-flag A boloean
52 Help Options:
54 -h Display help options -- short flags preferred
55 --help Display help options -- long flags preferred
56 --help-full Display all help options -- short and long
57 # or a GUI screen:
59 (see http://www.dnssec-tools.org/images/getopt_example.png )
61
63 This module is a wrapper around Getopt::Long that extends the value of
64 the original Getopt::Long module to:
65 1) add a simple graphical user interface option screen if no
67 arguments are passed to the program. Thus, the arguments to
68 actually use are built based on the results of the user
69 interface. If arguments were passed to the program, the user
70 interface is not shown and the program executes as it normally
71 would and acts just as if Getopt::Long::GetOptions had been
72 called instead.
73 2) provide an auto-help mechanism such that -h and --help are
75 handled automatically. In fact, calling your program with -h
76 will default to showing the user a list of short-style arguments
77 when one exists for the option. Similarly --help will show the
78 user a list of long-style when possible. --help-full will list
79 all potential arguments for an option (short and long both).
80 It's designed to make the creation of graphical shells trivial
82 without the programmer having to think about it much as well as
83 providing automatic good-looking usage output without the
84 programmer needing to write usage() functions.
85 This also can turn normal command line programs into web CGI scripts
87 as well (automatically). If the Getopt::GUI::Long program is
88 installed as a CGI script then it will automatically prompt the user
89 for the same variables.
90
92 The Getopt::GUI::Long module can work identically to the Getopt::Long
93 module but really benefits from some slightly different usage
94 conventions described below.
95 Option format:
97 Option strings passed should be formatted in one of the following ways:
98 Empty String
100 Empty strings are ignored by the non-GUI version of the command,
101 but are treated as vertical separators between questions when
102 displaying the GUI screen.
103 Standard flag specification string
105 EG: "some-flag|optional-flag=s"
106 This is the standard method by which Getopt::Long does things and
108 is merely treated the same way here. In this case, the text
109 presented to the user screen will be the first name in the list
110 ("some-flag") in the above option. The type of wdget displayed
111 with the text will depend on the optional =s/i/whatever flag and
112 will be either a checkbox, entry box, ...
113 Array Reference
115 EG: ["some-flag|optional-flag=s", 'Prompt text', OTHER],
116 The values passed in this array are as follows:
118 0: Standard flag specification string
120 Same as always, and as above.
121 1: Prompt text about flag
123 The help text that should be shown to the user in the graphical
124 interface. In the example above rather than "some-flag" being
125 shown, "Prompt text" will be shown next to the widget instead.
126 If the prompt text is equal to "!GUI" then this option will not
128 be displayed (automatically at least) within the GUI.
129 2...: OTHER options
131 Beyond the name and description, key value pairs can indicate
132 more about how the option should be handled.
133 required => 1
135 Forces a screen option to be filled out by the user.
136 question => { QUESTION FORM }
138 question => [{ QUESTION1}, {QUESTION2}, ...]
139 These allows you to build custom QWizard widgets to meet a
140 particular question need. It's highly useful for doing
141 menus and single choice fields that normally command line
142 options don't handle well. For example consider a numeric
143 priority level between 0 and 10. The following question
144 definition will give them a menu rather than a fill in the
145 blank field:
146 ['priority=i','Priority Level',
148 question => { type => 'menu', values => [1..10] }]
149 Note you can specify multiple question widgets if needed as
151 well, though this will probably be rare in usage.
152 QWizard question tokens
154 Any of the following items can be passed as well, which
155 will be added to the QWizard question structure. See the
156 QWizard documantion on "QUESTION DEFINITIONS" for details
157 on the usage of these.
158 type
160 helpdesc
161 helptext
162 default
163 check_value
164 doif
165 submit
166 refresh_on_change
167 handle_results
168 text
169 (Warning: Replaces the text already extracted from the
170 prompt text described above).
171 name
173 (Warning: Replaces the option name extracted from the
174 position 0 standard flag specification string above.
175 Do not use this unless you really know what you're
176 doing.)
177 [others TBD]
179
181 Flags that start with GUI: are not passed to the normal Getopt::Long
182 routines and are instead for internal GUI digestion only. If the GUI
183 screen is going to be displayed (remember: only if the user didn't
184 specify any options), these extra options control how the GUI behaves.
185 Some of these options requires some knowledge of the QWizard
187 programming system. Knowledge of QWizard should only be required if
188 you want to make use of those particular extra features.
189 GUI:guionly
191 EG: ['GUI:guionly', { type => 'checkbox', name => 'myguiflag'}]
192 Specifies a valid QWizard question(s) to only be shown when the gui
194 is displayed, and the specification is ignored during normal
195 command line usage.
196 GUI:separator
198 EG: ['GUI:separator', 'Task specific options:']
199 Inserts a label above a set of options to identify them as a group.
201 GUI:screen
203 EG: ['GUI:screen', 'Next Screen Title', ...]
204 Specifies that a break in the option requests should occur and the
206 remaining options should appear on another screen(s). This allows
207 applications with a lot of options to reduce the complexity it
208 offers users and offers a more "wizard" like approach to helping
209 them decide what they're trying to do.
210 You can also make this next screen definition conditional by
212 defining an earlier option that may be, say, a boolean flag called
213 "feature_flag". Using this you can then only go into the next
214 screen if the "feature_flag" was set by doing the following:
215 ['feature-flag',
217 'turn on a special feature needing more options'],
218 ['GUI:screen', 'Next Screen Title', doif => 'feature-flag']
220 ['feature-arg1', 'extra argument #1 for special feature'],
221 ...
222 Also, if you need to do more complex calculations use the qwparam()
224 function of the passed in QWizard object in a subroutine reference
225 instead:
226 ['feature1','Turn on feature #1"],
228 ['feature2','Turn on feature #2"],
229 ['GUI:screen', 'Next Screen Title',
231 doif => sub {
232 return ($_[1]->qwparam('feature1') && $_[1]->qwparam('feature2'));
233 }]
234 GUI:otherargs_text
236 EG: ['GUI:otherargs', 'Files to process:']
237 Normally the GUI screen shows a "Other Arguments:" option at the
239 bottom of the main GUI screen to allow users to entry additional
240 flags (needed for file names, etc, and other non-option arguments
241 to be passed). However, since it doesn't know what these arguments
242 should be it can only provide a generic "Other Arguments:"
243 description. This setting lets you change that text to something
244 specific to what your application experts, such as "Files:" or
245 "HTML Files:" or something that helps the user understand what is
246 expected of them.
247 If you want to self-handle the argument prompting using other
249 QWizard constructs, then use the nootherargs token described below
250 instead.
251 GUI:nootherargs
253 EG: ['GUI:nootherargs', 1]
254 Normally the GUI screen shows a "Other Arguments:", or programmer
256 described text as described above, option at the bottom of the main
257 GUI screen. If you're going to handle the additional arguments
258 yourself in some way (using either some GUI:guionly or
259 (GUI:otherprimaries and GUI:submodules) flags), then you should
260 specify this so the other arguments field is not shown. You're
261 expected, in your self-handling code, to set the __otherargs
262 QWizard parameter to the final arguments that should be passed on.
263 GUI:nosavebutton
265 EG: ['GUI:nosavebutton', 1]
266 Normally the GUI screen offers a "save" menu that lets users save
268 their current screen settings for future calls. Using this setting
269 turns off this behavior so the button isn't shown.
270 GUI:otherprimaries
272 EG: ['GUI:otherprimaries', primaryname =>
273 { title => '...', questions => [...] }]
274 Defines other primaries to be added to the QWizard primary set.
276 GUI:submodules
278 EG: ['GUI:submodules', 'primaryname']
279 Defines a list of other primaries that should be called after the
281 initial one.
282 GUI:post_answers
284 EG: ['GUI:post_answers', sub { do_something(); }]
285 Defines an option for QWizard post_answers subroutines to run.
287 GUI:actions
289 EG: ['GUI:actions', sub { do_something(); }]
290 Defines an option for QWizard actions subroutines to run.
292 GUI:hook_finished
294 EG: ['GUI:hook_finished', sub { do_something(); }]
295 Defines subroutine(s) to be called after the GUI has completely
297 finished.
298 GUI:run_button
300 EG: ['GUI:run_button', 'My Run Button']
301 Defines the text to use for the final "Run" button (which normally
303 just says "Run").
304 GUI:VERSION
306 If display_help is defined, and the above token is specified
307 Getopt::GUI::Long takes over the output for --version output as
308 well.
309 EG: ['GUI:VERSION','0.9']
311 Produces the --version help option:
313 Help Options:
315 -h Display help options -- short flags preferred
316 --help Display help options -- long flags preferred
317 --help-full Display all help options -- short and long
318 --version Display the version number
319 And also auto-handles the --version switch:
321 % PROGRAM --version
323 Version: 0.9
324
326 If you call Getopt::GUI::Long's Configure routine, it will accept a
327 number of configure tokens and will pass the remaining ones to the
328 Getopt::Long Configure routine. The tokens that it recognizes itself
329 are described below:
330 display_help
332 The Getopt::GUI::Long package will auto-display help messages based
333 on the text included in the GetOptions call. No more writing those
334 silly usage() functions!
335 Note that this differs from the Getopt::Long's implementation of
337 the auto_help token in that the information is pulled from the
338 extended GetOptions called instead of the pod documentation.
339 The display_help token will automatically add the following options
341 to the options the application will accept, and will catch and
342 process them as well.
343 -h Command line help preferring short options if present in the
345 help specification.
346 --help
348 Command line help preferring long options if present in the
349 help specification.
350 --help-full
352 Shows all available option names for a given option
353 --gui
355 If the default GUI is not showing up because no_gui has been
356 specified, a sure can still call the application with only the
357 --gui flag to make it appear.
358 --no-gui
360 If the no_gui option hasn't been set and the user doesn't want
361 to see the GUI then they can use the --no-gui flag as the only
362 argument to ensure it doesn't appear.
363 capture_output
365 This tells the Getopt::GUI::Long module that it should caputure the
366 resulting STDOUT and STDERR results from the script and display the
367 results in a window once the script has finished.
368 no_gui
370 This option defaults to not presenting a GUI form for the user to
371 fill out unless they specify --gui as the first and only argument
372 on the command line.
373 allow_zero
375 By default the GUI will always pop up if zero-arguments have been
376 specified (or the help info will be displayed if no_gui is set).
377 This options specifies that zero arguments is a normal usage case.
378 Thus the only way to force the GUI or help to appear will be the
379 command line --gui flag.
380
382 The Getopt::GUI::Long qwizard object is stored at
383 $Getopt::GUI::Long::GUI_qw, which is usable for other GUI screens you
384 may need to create after the options screens have been processed. You
385 can also use it during the script to optionally display a progress
386 meter by making use of the QWizard::set_progress function. However,
387 you should test to see if the GUI screen mode was actually used before
388 operating with the object though. As an example:
389 $Getopt::GUI::Long::GUI_qw->set_progress(3/5)
391 if ($Getopt::GUI::Long::GUI_qw);
392
394 If programs desire to not require this module, the following code
395 snippit can be used instead which will not fail even if this module is
396 not available. To be used this way, the LocalGetOptions and
397 LocalOptionsMap functions should be copied to your perl script.
398 LocalGetOptions(\%opts,
400 ["h|help", "Show help for command line options"],
401 ["some-flag=s", "perform some flag based on a value"]);
402 sub LocalGetOptions {
404 if (eval {require Getopt::GUI::Long;}) {
405 import Getopt::GUI::Long;
406 # optional configure call
407 Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
408 return GetOptions(@_);
409 }
410 require Getopt::Long;
411 import Getopt::Long;
412 # optional configure call
413 Getopt::Long::Configure(qw(auto_help no_ignore_case));
414 GetOptions(LocalOptionsMap(@_));
415 }
416 sub LocalOptionsMap {
418 my ($st, $cb, @opts) = ((ref($_[0]) eq 'HASH')
419 ? (1, 1, $_[0]) : (0, 2));
420 for (my $i = $st; $i <= $#_; $i += $cb) {
421 if ($_[$i]) {
422 next if (ref($_[$i]) eq 'ARRAY' && $_[$i][0] =~ /^GUI:/);
423 push @opts, ((ref($_[$i]) eq 'ARRAY') ? $_[$i][0] : $_[$i]);
424 push @opts, $_[$i+1] if ($cb == 2);
425 }
426 }
427 return @opts;
428 }
429 Forcing a Particular Generator
431 There a times where you may want to force a particular generator to be
432 used. This can be accomplished by setting the QWIZARD_GENERATOR
433 environmental variable. this can actually be done in code within
434 something like LocalGetOptions function as well:
435 sub LocalGetOptions {
437 # force the library by using $ENV{'QWIZARD_GENERATOR'}
438 # if Gtk2, Tk, HTML or Readline generators are required, set the
439 # QWIZARD_GENERATOR ENV variable either externally or in this
440 # script Example: Force QWizard to use Tk instead of the
441 # preferred default of Gtk2 like this:
442 $ENV{'QWIZARD_GENERATOR'} = 'Tk' if (not exists($ENV{'QWIZARD_GENERATOR'}));
443 # ... conitune with the rest of the LocalGetOptions shown above
445
447 If a Getopt::GUI::Long script is installed as a CGI script, then the
448 Getopt::GUI::Long system will automatically create a web front end for
449 the perl script. It will present the user with all the normal
450 arguments that it would normally to a Gtk2 or other windowing system.
451 It will not present the box for generic additional arguments since this
453 is not safe to do. If you trust your users (ie, you have an
454 authentication system in place) then you can set the allowcgiargs GUI
455 variable to make this box appear. Example invocation (not generally
456 recommended):
457 ['GUI:allowcgiargs',1]
459 It also allows you to not present certain options to web users that you
461 will to command line users (some options may not be safe for CGI use).
462 You can do this by setting the nocgi variable in option definitions you
463 wish to disallow via CGI. E.G., if you had an option to specify a
464 location where to load configuration a file from, this would likely be
465 unsafe to publish in a CGI script. So remove it:
466 ["c|config-file","Load a specific configuration file", nocgi => 1]
468
470 See the getopttest program in the examples directory for an exmaple
471 script that uses a lot of these features.
472
474 Wes Hardaker, hardaker@users.sourceforge.net
475
477 Copyright (c) 2006-2009, SPARTA, Inc. All rights reserved
478 Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
480 Getopt::GUI::Long is free software; you can redistribute it and/or
482 modify it under the same terms as Perl itself.
483
485 perl(1)
486 modules: QWizard
488
490 This module was originally named Getopt::Long::GUI but the Getopt::Long
491 author wanted to reserve the Getopt::Long namespace entirely for
492 himself and thus it's been recently renamed to Getopt::GUI::Long
493 instead. The class tree isn't as clean this way, as this module still
494 inherits from Getopt::Long but it everything still works of course.
495perl v5.28.1 2013-02-25 Long(3)
