README
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