Data Types

Scalars

A scalar is represented as a simple integer or string value. If it is composed only of letters, numbers, and the underscore character, it can be written literally:

  foo
  all_word_characters
  123
  alpha_123_numeric
  4sure
    

However, if the value contains whitespace or other non-word characters, it must be quoted:

  "telnet/tcp"
  "use quotes for whitespace"
  "quotes can be escaped like this \" inside quoted strings"
  "quoted
     strings
   can span
   multiple lines"
    

Lists

A list is represented as a sequence of comma-delimited values enclosed by square brackets:

  [ this, is, a, list ]
    

Note that each value in a list can itself be a scalar, list, or hash:

  [ this, is, a, [ nested, list ] ]
  [ this, list, contains, a, { hash => value } ]
    

Hashes

A hash is represented as a sequence of zero or more comma-delimited entries enclosed in curly braces:

  { this => 1, is => 2, a => 3, hash => 4 }
    

As in perl, each entry contains a key and a value. However, unlike perl, the value is optional:

  { this, is, a, hash, without, values }
  { this => hash, has => "some values", but, not, others }
    

When no value is specified for a given entry, its value is undefined.

Note that hash keys must always be scalars. However, values may be scalars, lists, or hashes:

  { "this is a" => [ list, within, a, hash ] }
  { "this is a" => { sub => hash } }
    

Configuration Statements

  object[->method] [args];

In this syntax, "object" is the name of the object. The object must be created and passed to the Config::Objective constructor, as described above.

The "->method" portion is optional. If specified, it indicates which method should be called on the object. If not specified, a method called default() will be used.

The "args" portion is also optional. It specifies one or more comma-delimited arguments to pass to the method. If multiple arguments are provided, the entire argument list must be enclosed in parentheses. Each argument can be a simple scalar, list, hash, or a complex, nested list or hash structure, as described above.

So, putting this all together, here are some example configuration statements:

  ### call default method with no arguments
  object;

  ### call a specific method, but still no args
  object->method;

  ### call default method, but specify a single scalar argument
  object scalar_arg;

  ### call default method, but specify a single list argument
  object [ this, is, a, single, list, argument ];

  ### call a specific method and specify a single hash argument
  object->method { this, is, a, single, hash, argument };

  ### call a specific method with multiple scalar args
  object->method(arg1, arg2, arg3);

  ### call a specific method with multiple args of different types
  object->method(scalar_arg, [ list, argument ], { hash => argument });

Conditional Evaluation

The conditional directives are %if, %else, %elif, and %endif . They can be used to enclose other config statements, which are evaluated or skipped based on whether the conditional expression evaluates to true. For example:

  %if ( expression )
    ... other config directives ...
  %endif

The most basic expression is simply a method call that returns a true or false value. The syntax for this is the same as a normal config statement, except without the trailing semicolon:

  %if ( object[->method] [args] )

If no method is specified, the equals() method will be called by default.

Multiple expressions can be combined using the "&&", "||", and "!" operators. Additional parentheses can also be used for grouping within the expression. For example:

  %if ( ( object1 foo && ! object2 bar ) || object3 baz )

File Inclusion

  %include "filename"

If the specified filename is not an absolute path, Config::Objective will look for it in the directory specified by the include_dir attribute when the Config::Objective object was created.

Note that the %include directive will be ignored within an %if block whose condition is false. This means that you cannot start an %if block in one file, add a %include directive, and provide the %endif directive in the included file. All %if blocks must be fully contained within the same file.

Comments

Recommended Methods

get()

Return the value encapsulated by the object. This is used when you use call the variable name as a method of the Config::Objective object. For example:

  print "var1 = '" . $conf->var1 . "'\n";
    

This will implicitly call the get() method of the object named var1.

default()

This is the default method used when a configuration file references an object with no method.

equals()

This is the default method used when a configuration file references an object with no method as part of an expression. (See "Conditional Evaluation" above.)

Supplied Object Classes

Config::Objective::Boolean

Config::Objective::Hash

Config::Objective::Integer

Config::Objective::List

Config::Objective::String

Config::Objective::Table

See the documentation for each of these classes for more information.