Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

r31980@knight: rjbs | 2007-07-04 22:18:34 -0400

 readme
  • Loading branch information...
commit cb16f56dbe89a81b1d014fd8d396051f180104db 1 parent 9d3cc9c
@rjbs authored
Showing with 131 additions and 0 deletions.
  1. +131 −0 README
View
131 README
@@ -0,0 +1,131 @@
+NAME
+ Data::OptList - parse and validate simple name/value option pairs
+
+VERSION
+ version 0.102
+
+ $Id: /my/cs/projects/Data-OptList/trunk/lib/Data/OptList.pm 31979 2007-07-05T02:17:36.805594Z rjbs $
+
+SYNOPSIS
+ use Data::OptList;
+
+ my $options = Data::Optlist::mkopt([
+ qw(key1 key2 key3 key4),
+ key5 => { ... },
+ key6 => [ ... ],
+ key7 => sub { ... },
+ key8 => { ... },
+ key8 => [ ... ],
+ ]);
+
+ ...is the same thing, more or less, as:
+
+ my $options = [
+ [ key1 => undef, ],
+ [ key2 => undef, ],
+ [ key3 => undef, ],
+ [ key4 => undef, ],
+ [ key5 => { ... }, ],
+ [ key6 => [ ... ], ],
+ [ key7 => sub { ... }, ],
+ [ key8 => { ... }, ],
+ [ key8 => [ ... ], ],
+ ]);
+
+DESCRIPTION
+ Hashes are great for storing named data, but if you want more than one
+ entry for a name, you have to use a list of pairs. Even then, this is
+ really boring to write:
+
+ $values = [
+ foo => undef,
+ bar => undef,
+ baz => undef,
+ xyz => { ... },
+ ];
+
+ Just look at all those undefs! Don't worry, we can get rid of those:
+
+ $values = [
+ map { $_ => undef } qw(foo bar baz),
+ xyz => { ... },
+ ];
+
+ Aaaauuugh! We've saved a little typing, but now it requires thought to
+ read, and thinking is even worse than typing.
+
+ With Data::OptList, you can do this instead:
+
+ $values = Data::OptList::mkopt([
+ qw(foo bar baz),
+ xyz => { ... },
+ ]);
+
+ This works by assuming that any defined scalar is a name and any
+ reference following a name is its value.
+
+FUNCTIONS
+ mkopt
+ my $opt_list = Data::OptList::mkopt(
+ $input,
+ $moniker,
+ $require_unique,
+ $must_be,
+ );
+
+ This produces an array of arrays; the inner arrays are name/value pairs.
+ Values will be either "undef" or a reference.
+
+ Valid values for $input:
+
+ undef -> []
+ hashref -> [ [ key1 => value1 ] ... ] # non-ref values become undef
+ arrayref -> every value followed by a ref becomes a pair: [ value => ref ]
+ every value followed by undef becomes a pair: [ value => undef ]
+ otherwise, it becomes [ value => undef ] like so:
+ [ "a", "b", [ 1, 2 ] ] -> [ [ a => undef ], [ b => [ 1, 2 ] ] ]
+
+ $moniker is a name describing the data, which will be used in error
+ messages.
+
+ If $require_unique is true, an error will be thrown if any name is given
+ more than once.
+
+ $must_be is either a scalar or array of scalars; it defines what kind(s)
+ of refs may be values. If an invalid value is found, an exception is
+ thrown. If no value is passed for this argument, any reference is valid.
+ If $must_be specifies that values must be CODE, HASH, ARRAY, or SCALAR,
+ then Params::Util is used to check whether the given value can provide
+ that interface. Otherwise, it checks that the given value is an object
+ of the kind.
+
+ In other words:
+
+ [ qw(SCALAR HASH Object::Known) ]
+
+ Means:
+
+ _SCALAR0($value) or _HASH($value) or _INSTANCE($value, 'Object::Known')
+
+ mkopt_hash
+ my $opt_hash = Data::OptList::mkopt_hash($input, $moniker, $must_be);
+
+ Given valid "mkopt" input, this routine returns a reference to a hash.
+ It will throw an exception if any name has more than one value.
+
+EXPORTS
+ Both "mkopt" and "mkopt_hash" may be exported on request.
+
+AUTHOR
+ Ricardo SIGNES, "<rjbs@cpan.org>"
+
+BUGS
+ Please report any bugs or feature requests at <http://rt.cpan.org>. I
+ will be notified, and then you'll automatically be notified of progress
+ on your bug as I make changes.
+
+COPYRIGHT
+ Copyright 2006-2007, Ricardo SIGNES. This program is free software; you
+ can redistribute it and/or modify it under the same terms as Perl
+ itself.
+
Please sign in to comment.
Something went wrong with that request. Please try again.