1Long(3)               User Contributed Perl Documentation              Long(3)
2
3
4

NAME

6       Getopt::GUI::Long
7

SYNOPSIS

9         use Getopt::GUI::Long;
10
11         # 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
19         # or use references instead of a hash (less tested, however):
20
21         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
24         # displays auto-help given the input above:
25
26         % opttest -h
27         Usage: opttest [OPTIONS] Other Arguments
28
29         OPTIONS:
30
31         Important Flags:
32            -f STRING             A flag based on a string
33            -o                    A boloean
34
35         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
40
41
42         # or long help:
43
44         % opttest --help
45         Usage: opttest [OPTIONS] Other Arguments
46
47         OPTIONS:
48
49         Important Flags:
50           --some-flag=STRING     A flag based on a string
51           --other-flag           A boloean
52
53         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
58         # or a GUI screen:
59
60         (see http://www.dnssec-tools.org/images/getopt_example.png )
61

DESCRIPTION

63         This module is a wrapper around Getopt::Long that extends the value of
64         the original Getopt::Long module to:
65
66         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
74         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
81         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
86         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

USAGE

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
96   Option format:
97       Option strings passed should be formatted in one of the following ways:
98
99       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
104       Standard flag specification string
105              EG: "some-flag|optional-flag=s"
106
107           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
114       Array Reference
115              EG: ["some-flag|optional-flag=s", 'Prompt text', OTHER],
116
117           The values passed in this array are as follows:
118
119           0: Standard flag specification string
120               Same as always, and as above.
121
122           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
127               If the prompt text is equal to "!GUI" then this option will not
128               be displayed (automatically at least) within the GUI.
129
130           2...: OTHER options
131               Beyond the name and description, key value pairs can indicate
132               more about how the option should be handled.
133
134               required => 1
135                   Forces a screen option to be filled out by the user.
136
137               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
147                     ['priority=i','Priority Level',
148                      question => { type => 'menu', values => [1..10] }]
149
150                   Note you can specify multiple question widgets if needed as
151                   well, though this will probably be rare in usage.
152
153               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
159                   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
172                   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
178               [others TBD]
179

Special Flag Names

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
186       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
190       GUI:guionly
191             EG:  ['GUI:guionly', { type => 'checkbox', name => 'myguiflag'}]
192
193           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
197       GUI:separator
198             EG:  ['GUI:separator', 'Task specific options:']
199
200           Inserts a label above a set of options to identify them as a group.
201
202       GUI:screen
203             EG:  ['GUI:screen', 'Next Screen Title', ...]
204
205           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
211           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
216                   ['feature-flag',
217                    'turn on a special feature needing more options'],
218
219                   ['GUI:screen', 'Next Screen Title', doif => 'feature-flag']
220                   ['feature-arg1', 'extra argument #1 for special feature'],
221                   ...
222
223           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
227                   ['feature1','Turn on feature #1"],
228                   ['feature2','Turn on feature #2"],
229
230                   ['GUI:screen', 'Next Screen Title',
231                    doif => sub {
232                      return ($_[1]->qwparam('feature1') && $_[1]->qwparam('feature2'));
233                   }]
234
235       GUI:otherargs_text
236             EG:  ['GUI:otherargs', 'Files to process:']
237
238           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
248           If you want to self-handle the argument prompting using other
249           QWizard constructs, then use the nootherargs token described below
250           instead.
251
252       GUI:nootherargs
253             EG:  ['GUI:nootherargs', 1]
254
255           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
264       GUI:nosavebutton
265             EG:  ['GUI:nosavebutton', 1]
266
267           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
271       GUI:otherprimaries
272             EG:  ['GUI:otherprimaries', primaryname =>
273                                         { title => '...', questions => [...] }]
274
275           Defines other primaries to be added to the QWizard primary set.
276
277       GUI:submodules
278             EG:  ['GUI:submodules', 'primaryname']
279
280           Defines a list of other primaries that should be called after the
281           initial one.
282
283       GUI:post_answers
284             EG:  ['GUI:post_answers', sub { do_something(); }]
285
286           Defines an option for QWizard post_answers subroutines to run.
287
288       GUI:actions
289             EG:  ['GUI:actions', sub { do_something(); }]
290
291           Defines an option for QWizard actions subroutines to run.
292
293       GUI:hook_finished
294             EG:  ['GUI:hook_finished', sub { do_something(); }]
295
296           Defines subroutine(s) to be called after the GUI has completely
297           finished.
298
299       GUI:run_button
300             EG: ['GUI:run_button', 'My Run Button']
301
302           Defines the text to use for the final "Run" button (which normally
303           just says "Run").
304
305       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
310             EG:  ['GUI:VERSION','0.9']
311
312           Produces the --version help option:
313
314             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
320           And also auto-handles the --version switch:
321
322             % PROGRAM --version
323             Version: 0.9
324

CONFIGURATION

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
331       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
336           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
340           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
344           -h  Command line help preferring short options if present in the
345               help specification.
346
347           --help
348               Command line help preferring long options if present in the
349               help specification.
350
351           --help-full
352               Shows all available option names for a given option
353
354           --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
359           --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
364       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
369       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
374       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

Using the QWizard object for other purposes

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
390         $Getopt::GUI::Long::GUI_qw->set_progress(3/5)
391           if ($Getopt::GUI::Long::GUI_qw);
392

PORTABILITY

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
399         LocalGetOptions(\%opts,
400                         ["h|help", "Show help for command line options"],
401                         ["some-flag=s", "perform some flag based on a value"]);
402
403         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
417         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
430   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
436        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
444            # ... conitune with the rest of the LocalGetOptions shown above
445

Usage as a CGI Script

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
452       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
458         ['GUI:allowcgiargs',1]
459
460       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
467         ["c|config-file","Load a specific configuration file", nocgi => 1]
468

EXAMPLES

470       See the getopttest program in the examples directory for an exmaple
471       script that uses a lot of these features.
472

AUTHOR

474       Wes Hardaker, hardaker@users.sourceforge.net
475
477       Copyright (c) 2006-2009, SPARTA, Inc.  All rights reserved
478
479       Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
480
481       Getopt::GUI::Long is free software; you can redistribute it and/or
482       modify it under the same terms as Perl itself.
483

SEE ALSO

485       perl(1)
486
487       modules: QWizard
488

HISTORY

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.
495
496
497
498perl v5.36.0                      2023-01-20                           Long(3)
Impressum