Topics: perl beginner tutorial example freeware automatic generate code simple forms template free expert development tool getopt::long regular expression regex

Summary.  Using simple forms, PerlWizard quickly generates front ends for user-friendly Perl scripts for Unix and Windows, with emphasis on the user interface, managing defaults files, and providing help.  The generated user interface supplies defaults for unentered options, validates options, and records options for use as defaults on subsequent runs of the generated scripts.  This makes PerlWizard scripts much more interactive and friendly than typical command line programs.  Once PerlWizard generates the front end, the programmer just needs to go to the bottom of the generated code and start writing.  No need to worry about how to set up Getopt::Long calls, initialization files, built-in help, log files, etc.  PerlWizard is available at www.rtbaileyphd.com/perlwizard.

So basically, you just need to fill out a few simple forms, click a few buttons, and you can quickly jump into coding the guts of your script without bothering with all the boilerplate needed to produce a robust, user-friendly Perl application..

Running PerlWizard.  PerlWizard is distributed as the one-jar file PerlWizard.jar.  Click the preceding link and save it to your computer.  PerlWizard will not create any files or registy entries on your computer.  Its only access to your system is to copy scripts to your clipboard.  To run it, just double click the jar file in Windows explorer or else type

            java -jar PerlWizard.jar

on the command line in a Windows cmd window or on a Unix system. 

If you want to modify the template, you can get a copy of the jar's template from the Download page and follow the instructions there.

If you get an UnsupportedClassVersionError, then your version of Java is too old.  PerlWizard was compiled for Java 7 (jdk 1.7, jre7), which was released 7/28/2011.  It should also work for later versions of Java.

When it starts you will see a tabbed application.  The first tab will be Intro, which will contain a duplicate of this page.  Click the Terms tab and agree to the minimal terms of use.  Then just fill out the forms in the Step1 and Step2 tabs.  There is plenty of help for each of the fields, so no further explanation is needed here.  Your generated script will be found in the next tab.  When you are satisfied, click the Copy to Clipboard button.  This copies the script to your clipboard.  Paste the generated script into a text editor such as notepad.  Repeat the copy and paste operations in the PerlWizardSubs, gnrl_utils, and file_mgr tabs.  Optionally, copy and paste from the *.bat and MkLink tabs.  Save the PerlWizardSubs.pl, gnrl_utils.pl, and file_mgr.pl script to a location on your PERL5LIB path or to the same directory where you put your generated script.  See https://rtbaileyphd.com/mklink for info on MkLink.pl if you are a Windows user.

To uninstall, just delete the jar file. 

Running generated PerlWizard scripts.  PerlWizard scripts are invoked in one of the following ways:

   MyScript.pl -help
   MyScript.pl -Opt1 Val1 -Opt2 Val2 ... other_args
   perl MyScript.pl -Opt1 Val1 -Opt2 Val2 ... other_args
   other_cmd | MyScript.pl -batch -Opt1 Val1 -Opt2 Val2 ... other_args -- -
   other_cmd | perl MyScript.pl -batch -Opt1 Val1 -Opt2 Val2 other_args -- -

On the command line the options are case insensitive and equals signs may or may not be used.  So "-Opt1 Val1", "-Opt1=Val1", and "-opt1=Val1" are equivalent.  Options can also be abbreviated.  So "-batch" and "-bat" are equivalent as long as "-bat" is not ambiguous.  Ordering is irrelevant.  Option processing stops if " -- " is seen.  These are all features of the Perl Getopt::Long module.

PerlWizard always generates code for the boolean options -ask_all, -help, -batch, and -debug, and string options ‑log_file and ‑defaults_file.  It prompts the developer for names and other details of script-specific options.

Details vs getting started.  You do not need to read the following details since PerlWizard has plenty of built-in help and is very easy to use.  Come back here just if something is unclear.  You can get started now by clicking this link: PerlWizard.jar

Getopt::Long  The generated scripts handle command line options using the Perl Getopt::Long module.  The Getopt::Long module processes long (multi-character) options, abbreviations, and option arguments according to POSIX conventions with some extensions.  It puts the option argument value, if any, in a Perl variable whose name is the option name.  For example, "‑DBName=MyDB" on the command line would cause the Perl variable $DBName to be filled with the value "MyDB".  The command line could also contain "-DB=MyDB" or "-db MyDB" and the $DBName variable would still be filled with the value "MyDB".  Each option processed by Getopt::Long is removed from Perl's @ARGV array.  Whatever is left over can be assigned to a PerlWizard variable  using type argv_string in the Step 2 tab (3rd box dropdown in Selected Option Detail).

Execution modes.  PerlWizard scripts can be executed in an interactive mode or batch mode.  In the interactive mode, the scripts generally prompt the user for missing options, while in the batch mode the scripts always run without user intervention.  Interactive mode prompting can be disabled for selected options.  Normally, prompting should be disabled for options that do not need to be changed often, if at all (e.g., the name of the log file).  There is also a total interactive mode initiated by -ask_all on the command line; in this mode the script prompts for values for every possible option.  After the script is generated, the developer can change the prompting behavior with the %prompt_fors hash.

The default mode can be set to be either interactive or batch at the time of generation.  Irrespective of the default mode, a command line option can be used to change the mode at run-time. If the default mode is interactive, then the batch mode is established by the presence of -batch on the command line. If the default mode is batch, then the interactive mode is established by the presence of -nobatch on the command line.

In the -ask-all mode, your PerlWizard script will always ask the user to enter all possible options.

Defaults files.  After the initial interactive execution of a generated script, defaults for options for subsequent executions may be taken from defaults files whose names are generally derived from the script name and the user's name. These defaults files are generally created in the pwiz subdirectory of the user's current working directory.  In the interactive mode, they are updated each time the generated script is executed.  For example, if joe interactively executes the script named wgr.pl in directory /u/foo, then the file named /u/foo/pwiz/wgr.pl.joe.defaults will be created, and it will contain the option values and other_args that joe used.  The next time joe runs wgr.pl in /u/foo, defaults for unentered options and an unentered other_args will be taken from the file /u/foo/pwiz/wgr.pl.joe.defaults.   If used in the -batch mode, wgr.pl will use the defaults in /u/foo/pwiz/wgr.pl.joe.defaults, but will not update /u/foo/pwiz/wgr.pl.joe.defaults.

If you do not want pwiz subdirectories being created everywhere, then from the dropdown, take the $home/pwiz/$pgm.defaults choice.  The same is true for logs subdirectories.

Instead of being stored, selected defaults can be specified to always be recomputed at run-time.  This might include defaults that are time-dependent.  After the script is generated, the developer can change the defaults behavior with the %is_storeds hash.

The set of defaults files can consist of one or more files.  Multiple files can be used when an option value represents a major category.  For example, if Customer is one option and Phone is the next, and the script is run for Joe Brown 360-555-1234, then Sally Smith 423-555-5678, and then Joe Brown again, the default value for Phone should be 360-555-1234.  You accomplish this by telling PerlWizard to switch defaults after processing the Customer option (Step 2 tab checkbox labeled "Switch defaults file after processing").  After the script is generated, the developer can change the file switching with the % switch_defaults_files hash.

The name of the head defaults file can be specified with the -defaults_file option on the command line.  In this case the defaults file may be somewhere other than the pwiz subdirectory.

This system of defaults files and prompting options make it very easy for users to tune PerlWizard scripts to fit their needs without ever having to edit a configuration file or the Windows registry.

Regular expressions.  PerlWizard users can enter Perl regular expressions that each option must match.  These expressions allow the generated script to check for valid option values.  For example, the generated script could ensure that the option -day can only take on the values "Mon", "Tue", ... "Sun".  In the interactive mode, script users are prompted to re-enter values that do not match the expressions.

Writing useful regular expressions can be difficult.  For example, how would you write an expression that tests for a date that passes 2/1/12, Feb-1-12, 2-1-2012, February 1, 2012 but fails 2-1/2012?  Fortunately, there is help in the form of the Perl Regexp::Common modules.  These modules export a hash of regular expressions in %RE.  PerlWizard allows you to use this hash (and any other variables) in the expressions you supply.  A few examples are supplied in the PerlWizard regular expression drop-down.  You need to manually install and 'use' the correct Regexp::Common modules, however.  See also the sub GetRegexMatches() in PerlWizardSubs.pl.

In PerlWizard scripts, regular expressions that appear to be a list of choices cause the automatic creation of a menu.  This menu is presented to the user for an option when prompting is turned on for that option and the user did not enter it on the command line.  The user just has to enter an item number from the menu.

When the end user is asked to enter a value and that value does not match the regular expression, it could be very unfriendly to tell them that their entry did not match some regular expression.  End users should be told something in a human language.  These statements are stored in hints that the script author supplies to PerlWizard.

In the generated script the regular expressions are stored in %regexps and the expression hints are in %regexps_hints. 

Additional Validations.  In case the validation afforded by the %regexps hash is insufficient, PerlWizard adds stubs that you can modify as needed.  These stubs are in the get_XXXX() subs, along with instructions.  There is one get_XXXX() sub for each command line variable.

Placeholders.   Because PerlWizard cannot modify the generated code after you have copied it out of PerlWizard, and because you will almost certainly want to add new command line variables later, PerlWizard will generate PlaceHolder variables.  See the Step 2 tab.  PerlWizard hides from users those variables whose names start with 'Placeholder'.  Therefore these variables are not noticed by users.  To enhance your program, you just need to select one of these with the correct type and globally replace the name with your own name.  E.g.:
     s/PlaceholderB2/MyNewBool/g
Unfortunately, this will mess up the columnar formatting in your script.  To overcome this problem, you can download RenameVar.pl from the Download page.  RenameVar.pl will do the global substitution in such a way that the neat layout is preserved.  See also GeneralPurposeScript.pl on the Download page.

Credits.   PerlWizard code is generated by the FreeMarker template engine (http://www.freemarker.org) which was developed by the Visigoth Software Society (no link).  I used NetBeans ( http://netbeans.org/ ) to develop PerlWizard and found it to be an excellent IDE.  I used OneJar to gather the multiple jar files produced by NetBeans into a single jar file to make PerlWizard very easy to deploy and use.

Click here to download PerlWizard if you not done so already:  PerlWizard.jar

Questions?  Contact me at sprintf("%s@%s.com", 'perlwizard', 'rtbaileyphd') or see Feedback.

This page was last modified Wed Oct 07 16:35:58 2020

Change Log