NAME

Config::Tree::CmdLine - Read configuration tree from command line options

SYNOPSIS

# READING CONFIG FROM COMMAND LINE

# in shell:

% perl script.pl --foo/bar=3
% perl script.pl --foo='{bar: 3}'; # same thing
% perl script.pl '{bar: 3}'; # same thing, since ui.order of foo is 0

# in script.pl:

use Config::Tree::CmdLine;

my $conf = Config::Tree::CmdLine->new(
    schema => [hash=>{keys=>{
        foo=>[hash=>{ keys=>{bar=>"int"}, "ui.order"=>0, "ui.description"=>"Foo is blah" }],
        baz=>[str=>{ "ui.order"=>1, "ui.description"=>"Baz is blah..." }],
    }}],
    # when_invalid => ...,
    # include_path_re => qr/.../,
    # exclude_path_re => qr/.../,
    # must_exist => 0|1,
    # special_options => {...},
    ro    => 0,
);
my $val = $conf->get('/foo/bar'); # 3
$conf->cd('/foo');
$conf->set('bar', 10); # same as set('/foo/bar', 10);


# DISPLAYING HELP

# in shell:
% perl script.pl --help; # will display help using information from schema

DESCRIPTION

ATTRIBUTES

METHODS

new(%args)

Construct a new Config::Tree::CmdLine object. Arguments.

• ro. Optional, default is 0. Whether we should disallow set() and save().

• when_invalid. Optional, default is 'die'. What to do when a command line option is unknown in schema or does not validate schema. Choices: 'die', 'warn', 'quiet'. Will do nothing if no schema is supplied.

• exclude_path_re. Optional. When set, config path matching the regex will not be retrieved. See also: include_path_re.

• include_path_re. Optional. When set, only config path matching the regex will be retrieved. Takes precedence over exclude_path_re.

• schema. Optional. When specified, after the tree is retrieved, it will be validated against this schema using Data::Schema.

• special_options. Optional. Normally each command line option will be added to the config tree. However, if a hashref is supplied for this property, and an option name matches the key in the hashref, then the supplied special instructions will be used. This is used for example to display help/usage, add synonyms, etc.

  Default value for special_options is:

  {help => { schema=>'bool', sub=>{$self->usage(); exit 0} }

  The code in sub will be called with option value as the first argument and $self as the second argument, and should return nothing or a hashref containing option names and values which will be added to config tree. Another example for special option:

  {
   help    => ...,
   debug   => { schema=>'bool', sub=>sub {{log_level=>"debug"}} }
   verbose => { schema=>'bool', sub=>sub {{log_level=>"info"}} }
   quiet   => { schema=>'bool', sub=>sub {{log_level=>"error"}} }
  }

  In other words, specifying --debug, --verbose, and --quiet will set log_level accordingly. This might be a preferred syntax over the slightly longer --log_level=debug, etc.

• short_options. Optional. A hashref which map letter to long name equivalent. Example:

  {h => "help", d => "debug", v => "verbose"}

  This means, specifying -d will be the same as --debug, and so on.

• stop_after_first_arg. Optional. Default is 1. If enabled, then command line options processing will stop as soon as first non-option (i.e., argument) is encountered. Under stop_after_first_arg=1:

  % script.pl --foo 1 3 --bar 2

  will result in config tree {foo=>1} and @ARGV (3, '--bar', 2). Under stop_after_first_arg=0, the same command line will result in config tree {foo=>1, bar=>2} and @ARGV (3).

• argv. Optional, an arrayref. Instead of the default @ARGV, process command line on this array instead.

usage()

Prints usage information. Requires schema be specified.

set($path, $val)

Does nothing.

save()

Does nothing.

SEE ALSO

Data::Schema, Config::Tree::Base

AUTHOR

Steven Haryanto, <stevenharyanto at gmail.com>

COPYRIGHT & LICENSE

Copyright 2009 Steven Haryanto, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.