Getopt::XML - Provide the user input arguments to Getopt::Long as an XML document
Read in a list of XML elements and process them as the input arguments to the Getopt::Long module
use XML::TreePP; use Getopt::Long; use Getopt::XML qw(GetXMLOptions); use Data::Dump qw(dump); # # Set the XML Data my $xmldata=<<"EOF_XMLDATA"; <apple> <color>red</color> <type>red delicious</type> <isAvailable/> <cityGrown>Macomb</cityGrown> <cityGrown>Peoria</cityGrown> <cityGrown>Galesburg</cityGrown> </apple> EOF_XMLDATA # # Parse the XML data using XML::TreePP module my $tpp = XML::TreePP->new(); my $tree = $tpp->parse( $xmldata ); # # Read the XML data in as arguments to Getopt::Long my %options; GetXMLOptions ( xmldoc => $tree, xmlpath => '/apple', Getopt_Long => [ \%options, 'isAvailable', 'color=s', 'type=s', 'cityGrown=s@' ] ); dump(\%options);
This is the output:
{ cityGrown => ["Macomb", "Peoria", "Galesburg"], color => "red", isAvailable => 1, type => "red delicious", }
Alternately, the XML data can be in a file. The above code would be rewritten as this:
use Getopt::Long; use Getopt::XML qw(GetXMLOptions); use Data::Dump qw(dump); # my %options; GetXMLOptions ( xmlfile => '/path/to/xml_file.xml', xmlpath => '/apple', Getopt_Long => [ \%options, 'isAvailable', 'color=s', 'type=s', 'cityGrown=s@' ] ); dump(\%options);
This is simply another way to pass in user defined arguments to an application using Getop::Long. The module provides a way to pass in user arguments from an XML file into Getopt::Long.
In this way, the user can provide input to an application via an XML file. And this can be useful if the application is ran at a regular interval. Or it may be useful if the input to the application can change between multiple executions, but the provided content is consistant over time based on the context of the execution.
This input method may be desired for an application which has default values for options the author wishes to exist, but the author wants those default values to be changed by the user without having to edit the application code.
Or perhaps the application will reside in a multi-user environment, and this module would be used to store the input options as part of the user preferences.
And finally, perhaps the options to be passed into the application resides somewhere else in XML or another storage format that can be transformed into XML as input to an application.
The following perl modules are depended on by this module: ( Note: Dependency on Params::Validate was removed in version 0.52 )
XML::TreePP
XML::TreePP::XMLPath
Getopt::Long # Getopt::Long 2.37 or greater is required
Both XML::TreePP and XML::TreePP::XMLPath required modules are Pure PERL implementations.
Getopt::Long version 2.37 introduces the GetOptionsFromArray() method. Versions of Getopt::Long previous to 2.37 do not contain the GetOptionsFromArray() method.
The process of transforming XML data into options that can be passed into Getopt::Long is performed with the GetOptionsFromArray() method.
When the calling application invokes this module in a use clause, the following methods can be imported into its space.
GetXMLOptions
GetXMLOptionsFromFile
Example:
use Getopt::XML qw( GetXMLOptions GetXMLOptionsFromFile );
Create a new object instances of this module.
returns
An object instance of this module.
my $glx = new Getopt::XML();
This method formats a subtree of an XML document into an array that is acceptable to be passed in to the Getopt::Long::GetOptionsFromArray() method.
XMLTree
The hash reference of a parsed XML file, which has been parsed by XML::TreePP::parse()
A reference to an array which an acceptable array input to the Getopt::Long::GetOptionsFromArray() method.
my $ha_list = XMLToGetoptArgsArray ( $XMLTree )
Read a XML::TreePP parsed XML document, retrieve the XML data located at the specified XML subtree, and transform it into an acceptable argument array that can be passed into to the Getopt::Long::GetOptionsFromArray() method.
xmldoc
xmlpath - optional
The XML Path as recognized by the XML::TreePP::XMLPath module. Note that XMLPath is NOT an XPath, although it has similarities.
Getopt_Long
The hash array of a Getopt::Long configuration which is a definition of the expected Getopt::Long::GetOptions() input options.
GetXMLOptions ( xmldoc => $XMLTree, xmlpath => $XMLPath, Getopt_Long => \@options )
This method is a wrapper around the Getopt::XML::GetXMLOptions() method. Parse a XML file with the XML::TreePP::parsefile() method, then call the GetXMLOptions() method with the resulting XML::TreePP parsed XML document and other parameters passed in from the caller.
xmlfile
The XML file which will be parsed by XML::TreePP::parse() into a hash reference.
The hash array of a Getopt::Long configuration which is a definition of the expected Getopt::Log::GetOptions() input options.
GetXMLOptionsFromFile ( xmlfile => $XMLFile, xmlpath => $XMLPath, Getopt_Long => \@options )
It is not necessary to create an object of this module. However, if you choose to do so any way, here is how you do it.
my $obj = new Getopt::XML;
This module supports being called by two methods.
use Getopt::XML qw( function1 function2 ); function1( args )
See IMPORTABLE METHODS section for methods available for import
my $glx = new Getopt::XML; $glx->function1( args )
Using either method works the same and returns the same output.
use Getopt::Long qw(GetOptionsFromArray); # requires Getopt::Long 2.37 or greater use Getopt::XML qw(XMLToGetoptArgsArray); use XML::TreePP; my $tpp = XML::TreePP->new(); my $tree = $tpp->parsefile( '/path/to/xml_file.xml' ); my $xmlargs = XMLToGetoptArgsArray($tree); my %options; my @Getopt_Long = ( \%options, 'opt1', 'opt2=s', 'opt3=s@' ); GetOptionsFromArray($xmlargs,@Getopt_Long); # data from XML is now in %options
Where the XML file looks like this:
<opt1/> <!-- true or false --> <opt2>argA</opt2> <!-- single value option --> <opt3>argB</opt3> <!-- multi-value option --> <opt3>argC</opt3> <opt3>argD</opt3> etc...
Parse an XML file with XML::TreePP::parsefile() and pass in the resulting parsed XML::TreePP document which will be used to create the arguments that would be passed in to the Getopt::Long::GetOptionsFromArray() method.
use Getopt::Long; use Getopt::XML qw(GetXMLOptions); use XML::TreePP; # Parse the XML file into an XML::TreePP document my $tpp = XML::TreePP->new(); my $tree = $tpp->parsefile( '/path/to/xml_file.xml' ); # Define %options, and populate it with options found in the XML document my %options; GetXMLOptions ( xmldoc => $tree, xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] );
Where the file '/path/to/xml_file.xml' contains the following content:
<xmlconfig> <options> <verbose/> <single_option>argument1A</single_option> <multiple_options>argument2A</multiple_options> <multiple_options>argument2B</multiple_options> <multiple_options>argument2C</multiple_options> </options> </xmlconfig>
Parse an XML file to create the arguments that would be passed in to the Getopt::Long::GetOptionsFromArray() method. With the Getopt::XML module, you can now put the would be user input into an XML file like the example below.
use Getopt::Long; use Getopt::XML qw(GetXMLOptionsFromFile); # Define %options, and populate it with options found in the XML file my %options; GetXMLOptionsFromFile ( xmlfile => '/path/to/xml_file.xml', xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] );
The sample XML file '/path/to/xml_file.xml' contains the following content:
What you are used to doing with the Getopt::Long module
With the Getopt::Long module alone, you performed this to retrieve user input. This prints out what the user passed in for the --single_option option on the command line.
use Getopt::Long; my %options; GetOptions ( %options, 'verbose', 'single_option=s', 'multiple_options=s@' ); print $options{'single_option'},"\n";
What you can do using XML
With the Getopt::XML module, you can now put the would be user input into an XML file like the sample XML file above. This prints out the value of the <single_option></single_option> element as found in the XML file.
use Getopt::Long; use Getopt::XML qw(GetXMLOptionsFromFile); my %options; GetXMLOptionsFromFile ( xmlfile => '/path/to/xml_file.xml', xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] ); print $options{'single_option'},"\n";
What you can do using both methods
Now try doing both. You can provide the XML file to give all the defaults for the input to your application, then you can overwrite the defaults with user provided input. This prints out what the user passed in for the --single_option option on the command line. However, if the user did not provide such input, then the value for this option as found in the XML file is what is printed out.
use Getopt::Long; use Getopt::XML qw(GetXMLOptionsFromFile); # Read in the default arguments for your options from the XML file: my %options; GetXMLOptionsFromFile ( xmlfile => '/path/to/xml_file.xml', xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] ); # Then overwrite those defaults with user provided input GetOptions ( %options, 'verbose', 'single_option=s', 'multiple_options=s@' ); print $options{'single_option'},"\n";
Passing in XML:TreePP parsed XML, instead of a file
Optionally, if you are using the XML::TreePP module for your XML files, you can pass in the parsed XML::TreePP XML document instead of the actual file.
use Getopt::Long; use Getopt::XML qw(GetXMLOptions); use XML::TreePP; # Parse the XML file using XML::TreePP module my $tpp = XML::TreePP->new(); my $tree = $tpp->parsefile( '/path/to/xml_file.xml' ); my %options; # Read the XML data in as arguments to Getopt::Long GetXMLOptions ( xmldoc => $tree, xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] );
Leveraging the capabilites of XML::TreePP, you can also fetch the XML file from the internet via a HTTP GET request
use Getopt::Long; use Getopt::XML qw(GetXMLOptions); use XML::TreePP; # Parse the XML file using XML::TreePP module my $tpp = XML::TreePP->new(); my $tree = $tpp->parsehttp( GET => "http://config.mydomain.com/myapp/default_settings.xml" ); my %options; # Read the XML data in as arguments to Getopt::Long GetXMLOptions ( xmldoc => $tree, xmlpath => '/xmlconfig/options', Getopt_Long => [ \%options, 'verbose', 'single_option=s', 'multiple_options=s@' ] );
Russell E Glaue, http://russ.glaue.org
Getopt::Long
Getopt::XML on Codepin: http://www.codepin.org/project/perlmod/Getopt-XML
Copyright (c) 2008-2009 Center for the Application of Information Technologies. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Getopt::XML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::XML
CPAN shell
perl -MCPAN -e shell install Getopt::XML
For more information on module installation, please visit the detailed CPAN module installation guide.