1============================================================================== 2 Getopt::Declare 3 Declaratively Expressed Command-Line Arguments via Regular Expressions 4============================================================================== 5 6 7Getopt::Declare is *yet another* command-line argument parser, one which 8is specifically designed to be powerful but exceptionally easy to use. 9 10To parse the command-line in `@ARGV', one simply creates a 11Getopt::Declare object, by passing `Getopt::Declare::new()' a 12specification of the various parameters that may be encountered: 13 14 $args = new Getopt::Declare($specification); 15 16The specification is a single string such as this: 17 18 $specification = q( 19 20 -a Process all data 21 22 -b <N:n> Set mean byte length threshold to <N> 23 { bytelen = $N; } 24 25 +c <FILE> Create new file <FILE> 26 27 --del Delete old file 28 { delold() } 29 30 delete [ditto] 31 32 e <H:i>x<W:i> Expand image to height <H> and width <W> 33 { expand($H,$W); } 34 35 -F <file>... Process named file(s) 36 { defer {for (@file) {process()}} } 37 38 =getrand [<N>] Get a random number 39 (or, optionally, <N> of them) 40 { $N = 1 unless defined $N; } 41 42 -- Traditionally indicates end of arguments 43 { finish } 44 ); 45 46in which the syntax of each parameter is declared, along with a 47description and (optionally) one or more actions to be performed when 48the parameter is encountered. The specification string may also include 49other usage formatting information (such as group headings or 50separators) as well as standard Perl comments (which are ignored). 51 52Calling Getopt::Delare::new() parses the contents of the array 53@ARGV, extracting any arguments which match the parameters defined in 54the specification string, and storing the parsed values as hash elements 55within the new Getopt::Declare object being created. 56 57Other features of the Getopt::Declare package include: 58 59 * The use of full Perl regular expressions to constrain 60 matching of parameter components. 61 62 * Automatic generation of error, usage and version information. 63 64 * Optional conditional execution of embedded actions (i.e. only 65 on successful parsing of the entire command-line) 66 67 * Strict or non-strict parsing (unrecognized command-line 68 elements may either trigger an error or may simply be left in 69 @ARGV) 70 71 * Declarative specification of various inter-parameter 72 relationships (for example, two parameters may be declared 73 mutually exclusive and this relationship will then be 74 automatically enforced). 75 76 * Intelligent clustering of adjacent flags (for example: the 77 command-line sequence "-a -b -c" may be abbreviated to 78 "-abc", unless there is also a `-abc' flag declared). 79 80 * Selective or global case-insensitivity of parameters. 81 82 * The ability to parse files (especially configuration files) 83 instead of the command-line. 84 85 86============================================================================== 87 88CHANGES 89 90See the file 'Changes' for a list of changes and release dates. 91 92 93============================================================================== 94 95INSTALLATION 96 97Note: requires the Text::Balanced module 98 99Getopt::Declare has been uploaded to the CPAN: 100 http://search.cpan.org/search?query=getopt+declare 101 102So, the easiest way is to use the 'cpan' command if it is installed on your 103computer: 104 cpan Getopt::Declare 105 106Otherwise: 107 perl Makefile.PL 108 make 109 make test 110 make install 111 112Consult the POD for exhaustive documentation: 113 perldoc Getopt::Declare 114 115Also, some demos are available in the demos folder. 116 117 118============================================================================== 119 120AUTHOR 121 122Damian Conway <damian@conway.org> 123 124 125============================================================================== 126 127COPYRIGHT 128 129 Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. 130 This module is free software. It may be used, redistributed 131 and/or modified under the terms of the Perl Artistic License 132 (see http://www.perl.com/perl/misc/Artistic.html) 133 134 135============================================================================== 136 137BUGS AND ANNOYANCES 138 139There are undoubtedly serious bugs lurking somewhere in this code. 140 141If nothing else, it shouldn't take 1500 lines to explain a 142package that was designed for intuitive ease of use! 143 144Bug reports and other feedback are most welcome at: 145 https://rt.cpan.org/Public/Bug/Report.html?Queue=Getopt-Declare 146 147