PERL Modules | Getopt-XML

CodePin.org

ABOUT

Provide the user input arguments to Getopt::Long as an XML document


AVAILABILITY

View the Getopt-XML README, CHANGES, online.
View the Getopt-XML Subversion repository online.

Download the source code from Subversion.

Download from CPAN: http://cpan.perl.org/modules/by-module/Getopt/


POD DOCUMENTATION

NAME

Getopt::XML - Provide the user input arguments to Getopt::Long as an XML document

SYNOPSIS

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);

DESCRIPTION

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.

REQUIREMENTS

The following perl modules are depended on by this module: ( Note: Dependency on Params::Validate was removed in version 0.52 )

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.

IMPORTABLE METHODS

When the calling application invokes this module in a use clause, the following methods can be imported into its space.

Example:

    use Getopt::XML qw( GetXMLOptions GetXMLOptionsFromFile );

METHODS

new

Create a new object instances of this module.

  • returns

    An object instance of this module.

    my $glx = new Getopt::XML();

XMLToGetoptArgsArray

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()

  • returns

    A reference to an array which an acceptable array input to the Getopt::Long::GetOptionsFromArray() method.

    my $ha_list = XMLToGetoptArgsArray ( $XMLTree )

GetXMLOptions

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

    The hash reference of a parsed XML file, which has been parsed by XML::TreePP::parse()

  • 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 )

GetXMLOptionsFromFile

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.

  • 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::Log::GetOptions() input options.

    GetXMLOptionsFromFile ( xmlfile => $XMLFile, xmlpath => $XMLPath, Getopt_Long => \@options )

EXAMPLES

Method: new

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.

  1. By importing the functions you wish to use, as in: 
        use Getopt::XML qw( function1 function2 );
    function1( args )

    See IMPORTABLE METHODS section for methods available for import

  2. Or by calling the functions in an object oriented mannor, as in: 
        my $glx = new Getopt::XML;
    $glx->function1( args )

Using either method works the same and returns the same output.

Method: XMLToGetoptArgsArray

    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...

Method: GetXMLOptions

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>

Method: GetXMLOptionsFromFile

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@'
            ]
    );

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>

General

The sample XML 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>

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@'
            ]
    );

AUTHOR

Russell E Glaue, http://russ.glaue.org

SEE ALSO

Getopt::Long

XML::TreePP

XML::TreePP::XMLPath

Getopt::XML on Codepin: http://www.codepin.org/project/perlmod/Getopt-XML

COPYRIGHT AND LICENSE

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.



CodePin.org, © 2008 - 2009 Center for the Application of Information Technologies, Western Illinois University