cvsuser 04/02/19 08:17:15
Modified: App-Options CHANGES MANIFEST TODO
App-Options/lib/App Options.pm
App-Options/t app.conf main.t test1 test2 test3 test4 test5
Log:
major step toward 1.0, removed 'use App::Options' from BEGIN block
Revision Changes Path
1.5 +4 -0 p5ee/App-Options/CHANGES
Index: CHANGES
===================================================================
RCS file: /cvs/public/p5ee/App-Options/CHANGES,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -w -r1.4 -r1.5
--- CHANGES 9 Feb 2004 22:03:50 -0000 1.4
+++ CHANGES 19 Feb 2004 16:17:14 -0000 1.5
@@ -5,6 +5,10 @@
VERSION 0.64
x added $VERSION to App::Options (use VERSION_FROM in Makefile.PL)
x fixed bug where "show_all" wasn't showing all on --help
+ x touched up titles on pod documentation
+ x implement import() method to use module outside the BEGIN block (i.e. use
App::Options (@args))
+ x update documentation with new syntax using import() method
+ x improve show_all logic: show_all = 1 by default always unless overridden
VERSION 0.63
x improve documentation (api reference, logic flow, usage tutorial)
1.3 +4 -0 p5ee/App-Options/MANIFEST
Index: MANIFEST
===================================================================
RCS file: /cvs/public/p5ee/App-Options/MANIFEST,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- MANIFEST 7 Jan 2004 15:24:07 -0000 1.2
+++ MANIFEST 19 Feb 2004 16:17:14 -0000 1.3
@@ -4,9 +4,13 @@
README
TODO
bin/prefix
+examples/app.conf
+examples/test1
+examples/test1.conf
lib/App/Options.pm
t/app.conf
t/main.t
+t/old.t
t/test1
t/test1.conf
t/test2
1.6 +3 -2 p5ee/App-Options/TODO
Index: TODO
===================================================================
RCS file: /cvs/public/p5ee/App-Options/TODO,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -w -r1.5 -r1.6
--- TODO 9 Feb 2004 22:03:50 -0000 1.5
+++ TODO 19 Feb 2004 16:17:14 -0000 1.6
@@ -1,16 +1,17 @@
######################################################################
-## File: $Id: TODO,v 1.5 2004/02/09 22:03:50 spadkins Exp $
+## File: $Id: TODO,v 1.6 2004/02/19 16:17:14 spadkins Exp $
######################################################################
These items are what will be required to go to version 1.00.
o use File::Spec to make file/directory manipulation platform-independent
- o figure out a way to do it outside the BEGIN block (i.e. use App::Options
qw(:init))
These are other interesting things
o here documents, var = <<EOF
o line continuation chars, i.e. var = hello \
world
o make lots more tests (starting with the examples in the documentation)
+ o substitute environment vars with "$ENV{PATH}"
+ o setenv arg to set environment variables
o make example scripts (starting with the examples in the documentation)
o add --version support (print out own version and versions of all modules)
o add "arg" option attribute for the name of the option argument
1.6 +152 -157 p5ee/App-Options/lib/App/Options.pm
Index: Options.pm
===================================================================
RCS file: /cvs/public/p5ee/App-Options/lib/App/Options.pm,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -w -r1.5 -r1.6
--- Options.pm 9 Feb 2004 22:03:50 -0000 1.5
+++ Options.pm 19 Feb 2004 16:17:15 -0000 1.6
@@ -1,6 +1,6 @@
#############################################################################
-## $Id: Options.pm,v 1.5 2004/02/09 22:03:50 spadkins Exp $
+## $Id: Options.pm,v 1.6 2004/02/19 16:17:15 spadkins Exp $
#############################################################################
package App::Options;
@@ -10,7 +10,7 @@
use Carp;
-$VERSION = 0.64;
+$VERSION = "0.90";
=head1 NAME
@@ -20,10 +20,7 @@
#!/usr/local/bin/perl
- BEGIN {
- use App::Options;
- App::Options->init(); # reads option values into %App::options by default
- }
+ use App::Options; # reads option values into %App::options by default
# do something with the options (in %App::options)
use DBI;
@@ -162,17 +159,20 @@
* Throws: "App::Options->init(): 'options' arg must be an array reference"
* Since: 0.60
- Sample Usage:
+ Sample Usage: (normal)
+
+ use App::Options; # invokes init() automatically via import()
+
+ This is functionally equivalent to the following, but that's not
+ near as nice to write at the top of your programs.
BEGIN {
- use App::Options;
- App::Options->init();
+ use App::Options qw(none); # import() does not call init()
+ App::Options->init(); # we call init() manually
}
- ... or, to use every option available ...
+ Or we could have used a more full-featured version ...
- BEGIN {
- use App::Options;
App::Options->init(
values => \%MyPackage::options,
options => [ "option_file", "prefix", "app", "app_path_info",
@@ -192,11 +192,14 @@
no_option_file => 1,
print_usage => sub { my ($values, $init_args) = @_; print "Use it
right!\n"; },
);
- }
+
+The init() method is usually called during the import() operation
+when the normal usage ("use App::Options;") is invoked.
The init() method reads the command line args (@ARGV),
then finds an options file, and loads it, all in a way which
-can be done in a BEGIN block. This is important to be able
+can be done in a BEGIN block (minimal dependencies). This is
+important to be able
to modify the @INC array so that normal "use" and "require"
statements will work with the configured @INC path.
@@ -743,6 +746,13 @@
}
}
+sub import {
+ my ($self, @args) = @_;
+ if ($#args % 2 == 1) {
+ $self->init(@args);
+ }
+}
+
sub print_usage {
shift if ($#_ > -1 && $_[0] eq "App::Options");
my ($values, $init_args) = @_;
@@ -753,15 +763,14 @@
printf STDERR " --%-32s print this message (also -?)\n", "help";
my (@vars, $show_all, %option_seen);
$show_all = $init_args->{show_all};
+ $show_all = 1 if (!defined $show_all);
if ($init_args->{options}) {
@vars = @{$init_args->{options}};
- $show_all = 0 if (! defined $show_all);
}
- if ($init_args->{option} && ($show_all || $#vars == -1)) {
+ if ($init_args->{option}) {
push(@vars, (sort keys %{$init_args->{option}}));
- $show_all = 0 if (! defined $show_all);
}
- if ($show_all || (!defined $show_all && $#vars == -1)) {
+ if ($show_all) {
push(@vars, (sort keys %$values));
}
my ($var, $value, $type, $desc, $option);
@@ -788,17 +797,21 @@
your program parses the command line, environment variables,
and option files, and puts var/value pairs into a
global option hash, %App::options.
+Just include the following at the top of your program
+in order to imbue it with many valuable option-setting
+capabilities.
- BEGIN {
use App::Options;
- App::Options->init();
- }
+
+When you "use" the App::Options module, the import() method
+is called automatically. This calls the init() method,
+passing along all of its parameters.
One of the args to init() is the "values" arg, which allows
for a different hash to be specified as the target of all
option variables and values.
- App::Options->init(values => \%Mymodule::opts);
+ use App::Options (values => \%Mymodule::opts);
Throughout the following description of option processing,
the %App::options hash may be referred to as the "options hash".
@@ -1066,7 +1079,7 @@
"options" arg or the "option" arg to the init() method
(or a combination of both).
- App::Options->init(
+ use App::Options (
options => [ "dbname", "dbuser", "dbpass" ],
option => {
dbname => {
@@ -1183,10 +1196,7 @@
Create a perl program called "demo1".
#!/usr/bin/perl
- BEGIN {
use App::Options;
- App::Options->init(); # call this method
- }
print "Wow. Here are the options...\n";
foreach (sort keys %App::options) { # options appear here!
printf("%-20s => %s\n", $_, $App::options{$_});
@@ -1268,10 +1278,7 @@
We call this program "listcust".
#!/usr/local/bin/perl
- BEGIN {
use App::Options;
- App::Options->init();
- }
use strict;
use DBI;
my $dsn = "dbi:$App::options{dbdriver}:database=$App::options{dbname}";
@@ -1315,9 +1322,7 @@
A developer, however, might decide that the program should
have some defaults.
- BEGIN {
- use App::Options;
- App::Options->init(
+ use App::Options (
option => {
dbdriver => "mysql",
dbname => "prod",
@@ -1325,7 +1330,6 @@
dbpass => "tiger",
},
);
- }
(This supplies defaults and also makes "--help" print something
intelligent, regardless of whether there are any configuration
@@ -1337,9 +1341,7 @@
To use those, you generally would use the more complete form
of the "option" arg.
- BEGIN {
- use App::Options;
- App::Options->init(
+ use App::Options (
option => {
dbdriver => { default => "mysql", },
dbname => { default => "prod", },
@@ -1347,7 +1349,6 @@
dbpass => { default => "tiger", },
},
);
- }
Then we can indicate that these options are all required.
If they are not provided, the program will not run.
@@ -1357,9 +1358,7 @@
the program without providing the password, it would not get
past printing a "usage" statement.
- BEGIN {
- use App::Options;
- App::Options->init(
+ use App::Options (
option => {
dbdriver => { required => 1, default => "mysql", },
dbname => { required => 1, default => "prod", },
@@ -1367,7 +1366,6 @@
dbpass => { required => 1, },
},
);
- }
We now might enhance the code in order to list only the
customers which had certain attributes.
@@ -1396,9 +1394,7 @@
be set with the "options" argument. (Otherwise, they would
print in alphabetical order.)
- BEGIN {
- use App::Options;
- App::Options->init(
+ use App::Options (
options => [ "dbdriver", "dbname", "dbuser", "dbpass",
"first_name", "last_name", "birth_dt", "company_id",
"wholesale_ind", "change_dttm",
@@ -1451,7 +1447,6 @@
},
},
);
- }
It should be noted in the example above that the default environment
variable name ("APP_${varname}") has been overridden for some of
@@ -1461,29 +1456,29 @@
It should also be noted that if only the order of the options rather
than all of their attributes were desired, the following could
-have been used. Using the "options" arg
-limits the printing of options to only those listed unless the
-"show_all" argument is also given. Supplying the "show_all"
-argument allows for all options set in the option files also
-to be printed.
+have been used.
- BEGIN {
- use App::Options;
- App::Options->init(
+ use App::Options (
options => [ "dbdriver", "dbname", "dbuser", "dbpass",
"first_name", "last_name", "birth_dt", "company_id",
"wholesale_ind", "change_dttm",
],
- show_all => 1,
+ show_all => 0,
);
- }
+
+Using the "options" arg causes the options to
+be printed in the order given in the "--help" output. Then the
+remaining options defined in the "option" arg are printed in
+alphabetical order. Finally, all other options which are set
+on the command line or in option files are printed unless
+the "show_all => 0" argument is provided.
If, for some reason, the program needed to put the options
into a different option hash (instead of %App::options) or directly
specify the option file to use (disregarding the standard option
file search path), it may do so using the following syntax.
- App::Options->init(
+ use App::Options (
values => \%Mymodule::opts,
option_file => "/path/to/options.conf",
);
@@ -1493,7 +1488,7 @@
following arguments. Of course, inhibiting all three would
be a bit silly.
- App::Options->init(
+ use App::Options (
no_cmd_args => 1,
no_option_file => 1,
no_env_vars => 1,
1.3 +7 -0 p5ee/App-Options/t/app.conf
Index: app.conf
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/app.conf,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- app.conf 19 Jan 2004 14:51:41 -0000 1.2
+++ app.conf 19 Feb 2004 16:17:15 -0000 1.3
@@ -7,6 +7,9 @@
[main] var1 = pattern match
[main] var2 = old pattern match
[main] var3 = value3
+[old] var1 = pattern match
+[old] var2 = old pattern match
+[old] var3 = value3
dir = /usr/local
htdocs_dir = ${dir}/htdocs
[:dir=] dir = /usr/bad
@@ -25,4 +28,8 @@
[main]
var9 = value9
[/ma/]
+var7 = value7
+[old]
+var9 = value9
+[/ol/]
var7 = value7
1.4 +10 -10 p5ee/App-Options/t/main.t
Index: main.t
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/main.t,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -w -r1.3 -r1.4
--- main.t 19 Jan 2004 14:51:41 -0000 1.3
+++ main.t 19 Feb 2004 16:17:15 -0000 1.4
@@ -1,30 +1,30 @@
#!/usr/local/bin/perl -w
+BEGIN {
+ $ENV{VAR10} = "value10";
+ $ENV{APP_VAR11} = "value11";
+ $ENV{VAR12} = "value12";
+ delete $ENV{PREFIX};
+ delete $ENV{DOCUMENT_ROOT};
+}
+
use Test::More qw(no_plan);
use lib "lib";
use lib "../lib";
-use_ok("App::Options");
-
my ($dir);
$dir = ".";
$dir = "t" if (! -f "app.conf");
-delete $ENV{PREFIX};
-delete $ENV{DOCUMENT_ROOT};
-
-$ENV{VAR10} = "value10";
-$ENV{APP_VAR11} = "value11";
-$ENV{VAR12} = "value12";
-
-App::Options->init(
+use App::Options (
option => {
var10 => { env => "VAR10a;VAR10", },
var11 => { },
var12 => { env => "VAR12", },
},
);
+
#print "CONF:\n ", join("\n ",%App::options), "\n";
ok(%App::options, "put something in %App::options");
is($App::options{prefix}, "/usr/local", "prefix = /usr/local");
1.3 +6 -8 p5ee/App-Options/t/test1
Index: test1
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/test1,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- test1 11 Dec 2003 16:07:00 -0000 1.2
+++ test1 19 Feb 2004 16:17:15 -0000 1.3
@@ -1,11 +1,9 @@
#!/usr/local/bin/perl
-BEGIN {
use lib "lib";
use lib "../lib";
- use App::Options;
- App::Options->init(
+
+use App::Options (
options => [ "invoice_id", "cust_nm" ],
);
-}
1.3 +8 -11 p5ee/App-Options/t/test2
Index: test2
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/test2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- test2 11 Dec 2003 16:07:00 -0000 1.2
+++ test2 19 Feb 2004 16:17:15 -0000 1.3
@@ -1,14 +1,11 @@
#!/usr/local/bin/perl
-BEGIN {
use lib "lib";
use lib "../lib";
- use App::Options;
- App::Options->init(
+use App::Options (
option => {
invoice_id => "4",
cust_nm => "Joe Smith",
},
);
-}
1.3 +12 -14 p5ee/App-Options/t/test3
Index: test3
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/test3,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- test3 11 Dec 2003 16:07:00 -0000 1.2
+++ test3 19 Feb 2004 16:17:15 -0000 1.3
@@ -1,10 +1,8 @@
#!/usr/local/bin/perl
-BEGIN {
use lib "lib";
use lib "../lib";
- use App::Options;
- App::Options->init(
+use App::Options (
option => {
invoice_id => "4;type=integer",
cust_nm => "Joe Smith",
@@ -13,5 +11,5 @@
price => "type=float",
},
);
-}
+
1.3 +11 -14 p5ee/App-Options/t/test4
Index: test4
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/test4,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- test4 11 Dec 2003 16:07:00 -0000 1.2
+++ test4 19 Feb 2004 16:17:15 -0000 1.3
@@ -1,10 +1,8 @@
#!/usr/local/bin/perl
-BEGIN {
use lib "lib";
use lib "../lib";
- use App::Options;
- App::Options->init(
+use App::Options (
option => {
invoice_id => {default => 4, type => "integer"},
cust_nm => {default => "Joe Smith"},
@@ -13,5 +11,4 @@
price => {type => "float"},
},
);
-}
1.3 +13 -16 p5ee/App-Options/t/test5
Index: test5
===================================================================
RCS file: /cvs/public/p5ee/App-Options/t/test5,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -r1.2 -r1.3
--- test5 11 Dec 2003 16:07:00 -0000 1.2
+++ test5 19 Feb 2004 16:17:15 -0000 1.3
@@ -1,10 +1,8 @@
#!/usr/local/bin/perl
-BEGIN {
use lib "lib";
use lib "../lib";
- use App::Options;
- App::Options->init(
+use App::Options (
options => [ "invoice_id", "cust_nm", "price" ],
option => {
invoice_id => {default => 4, type => "integer"},
@@ -15,5 +13,4 @@
sell_ind => {type => '^(Y|N)$'},
},
);
-}
