Config::Scoped(3pm)

📦
version 0.22 · 3 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 Config::Scoped 💖

okay bestie, sit down, because this is the Config::Scoped manual page — it's Config::Scoped(3pm), a User Contributed Perl Documentation page, and it's a feature rich configuration file parser. yes. a whole parser. for your config files. she's giving main character energy and she's literally built on Parse::RecDescent. iykyk ✨

✨ NAME ✨

Config::Scoped — feature rich configuration file parser 💅

🎀 SYNOPSIS 🎀

  use Config::Scoped;

  $cs = Config::Scoped->new( file => $config_file, ... );
  $cfg_hash = $cs->parse;

like… that's it. that's the whole vibe. three lines and you're parsing. periodt. 💜

🦋 ABSTRACT 🦋

Config::Scoped is a configuration file parser. she parses. she scopes. she serves. 🌈

💖 Features 💖

  • recursive data structures with scalars, lists, and hashes — nesting all the way down, no cap
  • simplified syntax with minimal punctuation — your fingers will thank you, fr fr
  • parses many Perl data structures without eval, do or require — no sketchy code execution, we love a safe queen 👑
  • Perl quoting syntax: single quotes (''), double quotes (""), and here-docs (<<EOF) — all the classics, iconic
  • Perl code evaluation in Safe compartments — contained, controlled, responsible 💅
  • parses ISC named and dhcpd config files — yes bestie, she speaks named AND dhcpd
  • include files with recursion checks — so you can't accidentally eat your own tail 🐍
  • controlled macro expansion in double quoted tokens
  • lexically scoped parameter assignments and directives — scoped, like her name says, the way that she literally tells you in the title
  • duplicate macro, parameter, and declaration checks — she will catch you being messy 🙈
  • file permission and ownership safety checks — she checks IDs at the door
  • fine control over error checking — tune it to your exact vibe
  • error messages report config file names and line numbers — so you know exactly where it went wrong, no guessing games
  • exception-based error handling
  • based on Parse::RecDescent
  • configuration caching with MD5 checksums on the original files — cache it, verify it, slay it
  • may be subclassed to build parsers with specialized features — go off, build your own, we support you 🫶

⭐ REQUIRES ⭐

  • Parse::RecDescent
  • Error

that's the whole shopping list. two things. go install them. 🛍️

🧚 EXPORTS 🧚

Nothing. 💀

literally nothing. zero. she exports nothing and she's not sorry. you want stuff? call methods. 💅

💅 METHODS 💅

💖 Config::Scoped->new 💖

  $cs = Config::Scoped->new(
    file     => $config_file,
    lc       => $lc,
    safe     => $compartment,
    warnings => $warnings,
    your_key => $your_value, { ... },
  );

Creates and returns a new Config::Scoped object. The following parameters are optional — yes all of them, she's chill like that. 🌸

  • $config_file — The configuration file to parse. If you omit it, then a $config_string must be provided to the parse method instead (see below, bestie, keep reading).
  • $lc — If true, all declaration and parameter names will be converted to lower case. lowercase era. 🔡
  • $compartment — A Safe compartment for evaluating Perl code blocks in the configuration file. Defaults to a Safe compartment with no extra shares and the :default operator tag.
  • $warnings — may be the literal string 'on' or 'off' to set all warnings at once.

Or define a hash reference with the following keys to set each warning as specified. 🎚️

  $warnings = { declaration  => 'off',
                digests      => 'off',
                macro        => 'off',
                parameter    => 'off',
                permissions  => 'off',
                your_warning => 'off',
   };

All warnings are on by default. so if you're seeing a lot of noise, that's why, and now you know how to hush her. 🤫

  • Arbitrary key/value pairs — will be stored in the $cs object. This is useful primarily for subclassing. stash whatever you want in there, she doesn't judge. 🫶

💜 $cs->parse 💜

  $cfg_hash = $cs->parse;
  $cfg_hash = $cs->parse(text => $config_string);

Parses the configuration and returns a reference to the config hash. 🎉

The first form parses the $config_file that was provided to the constructor. If $config_file was not provided to the constructor, this form dies. 😭

The second form parses the $config_string.

🚨 This method must only be called once. one and done. no re-runs. she said what she said. 💅

🍓 $cs->store_cache 🍓

  $cs->store_cache;
  $cs->store_cache(cache => $cache_file);

Stores the config hash on disk for rapid retrieval. ⚡ If $config_file was provided to the constructor, then the stored form includes checksums of $config_file and any included files.

The first form writes to $config_file.dump. The second form writes to $cache_file.

If $config_file was not provided to the constructor, the first form dies. 😭

🌈 $cs->retrieve_cache 🌈

  $cfg_hash = $cs->retrieve_cache;
  $cfg_hash = $cs->retrieve_cache>(cache => $cache_file);

Retrieves the $config hash from a file that was created by store_cache. it's the comeback era. ✨

The first form reads $config_file.dump. The second form reads $cache_file.

If $config_file was not provided to the constructor, the first form dies. 😭

🔍 The stored file is subject to digests and permissions checks. she verifies. always. no cap.

🎀 $cs->set_warnings 🎀

  $cs->set_warnings(name => $name, switch => 'on|off');

Change warning for $name after construction. flip the switch, bestie. 🎚️

🦋 $cs->warnings_on 🦋

  $on = $cs->warnings_on(name => $name);

Returns true if warning $name is on. This is useful primarily for subclassing. 🫶

💀 EXCEPTIONS 💀

All methods die on error. every single one. dramatic? maybe. effective? absolutely. 😭

Config::Scoped::Error defines a hierarchy of classes that represent Config::Scoped errors. When a method detects an error, it creates an instance of the corresponding class and throws it. The error classes are all subclasses of Config::Scoped::Error. See Config::Scoped::Error for the complete list. 👑

If the exception is not caught, the program terminates, and Config::Scoped prints the config file name and line number where the error was detected to STDERR. so at least you get receipts. 🧾✨

✨ and that's part 1 bestie, there's more coming, don't go anywhere ✨

💖 CONFIG FILE FORMAT 💖

Config::Scoped parses configuration files. That's literally its whole thing, bestie.

So say we have a config file like

% cat host.cfg
host {
    name = cpan.org
    port = 22
}
%

we can parse it into Perl with code like

$cs = Config::Scoped->new( file => 'host.cfg' );
$cfg_hash = $cs->parse;

And the result is always a hash ref. We're gonna call this the config hash, and for the file above it looks like:

$cfg_hash = {
   host => {
      name => 'cpan.org',
      port => 22,
   }
  }

📁 Config files and config strings

Like we said, Config::Scoped can get a configuration from a $config_file, passed to the constructor, or from a $config_string, passed to the parse method. For simplicity we're gonna talk about parsing configuration files, and only call out configuration strings when it actually matters. ✨

📄 File layout

Config files are free-form text files. Comments start with #, and they run all the way to the end of the line. Periodt.

🧱 Declarations

The top-level elements of a config file are called declarations. A declaration is a name, followed by a block

foo {
}

bar {
}

The declaration names become keys in the config hash. The value of each key is another hash ref. So the config above parses to

$cfg_hash = {
   foo => {},
   bar => {},
  }

You can create extra levels in the config hash just by listing successive declaration names before the block. This config

dog hound {
}

dog beagle {
}

cat {
}

parses to

$cfg_hash = {
   dog => {
      hound  => {},
      beagle => {},
   },

   cat => {}
  }
🚨 Declarations may not be nested. No nesting, no exceptions, iykyk.

🔢 Parameters

The ultimate purpose of a configuration file is to hand your program some data values. Those values are specified by parameters.

Parameters look like

name = value

and they live inside declaration blocks. The

name = value

parameters in a spec file become key and value pairs inside the declaration hashes in Perl code.

For example, this configuration

dog {
    legs  = 4
    wings = 0
}

bird {
    legs  = 2
    wings = 2
}

parses to

$cfg_hash = {
   dog => {
      legs  => 4,
      wings => 0,
   },

   bird => {
      legs  => 2,
      wings => 2,
   }
  }

Parameter values can be scalars, lists or hashes.

Scalar values may be numbers or strings

shape = square
sides = 4

List values are wrapped in square brackets

colors = [ red green blue ]
primes = [ 2 3 5 7 11 13  ]

Hash values are wrapped in curly brackets

capitals = {
      England => London
      France  => Paris
}

A hash value is also called a hash block. 💅

Lists and hashes can be nested to arbitrary depth

Europe {
   currency = euro

   cities   = {
      England => [ London Birmingham Liverpool ]
      France  => [ Paris Canne Calais ]
   }
 }

parses to

$cfg_hash = {
   Europe => {
      currency => 'euro',

      cities => {
         England => [ 'London', 'Birmingham', 'Liverpool' ],
         France  => [ 'Paris',  'Canne',      'Calais' ],
      }
   }
  }

The Config::Scoped data syntax is similar to the Perl data syntax, and Config::Scoped will parse <em>many</em> Perl data structures. In general, though, Config::Scoped needs less punctuation than Perl. Note that Config::Scoped allows arrow (=>) or equals (=) between hash keys and values, but not comma (,)

capitals = { England => London        # OK
             France  =  Paris         # OK
             Germany ,  Berlin        # error
           }

🌍 _GLOBAL

If a config file contains no declarations at all

name = cpan.org
port = 22

then any parameters will be placed in a _GLOBAL declaration in the config hash

$cfg_hash = {
   _GLOBAL => {
      name => 'cpan.org',
      port => 22,
   }
  }

This is what lets you have super simple config files with just parameters and no declarations. Slay. 🎀

🪆 Blocks, scoping and inheritance

Every declaration block in a config file creates a lexical scope. Parameters inside a declaration are scoped to that block. And parameters are inherited by all following declarations within their scope.

So if all your animals have four legs, you can save yourself some typing by writing

legs = 4
cat {}
dog {}

which parses to

$cfg_hash = {
   cat => { legs => 4 },
   dog => { legs => 4 },
  }

And if some of your animals have two legs, you can create additional scopes with anonymous blocks to control inheritance

{
  legs = 4
  cat {}
  dog {}
}
{
  legs = 2
  bird {}
}

parses to

$cfg_hash = {
   cat  => { legs => 4 },
   dog  => { legs => 4 },
   bird => { legs => 2 },
  }

Anonymous blocks may be nested.

Each hash block also creates a scope. And important: the hash does not inherit parameters from outside its own scope. 🫶

🧚 Perl code evaluation

If you can't express what you need within the Config::Scoped syntax, your escape hatch is

eval { ... }

This does a Perl eval on the block, and replaces the construct with the results of the eval.

start = eval { localtime }
foo   = eval { warn 'foo,' if $debug; return 'bar' }

The block is evaluated in scalar context. However, it may return a list or hash reference, and the underlying list or hash can become a parameter value.

For example

foo {
  list = eval { [ 1 .. 3 ]                 }
  hash = eval { { a => 1, b => 2, c => 3 } }
}

parses to

$cfg_hash = {
   foo => {
      list => [ 1, 2, 3 ],
      hash => { a => 1, b => 2, c => 3 },
   }
  }

The block is evaluated inside the parser's Safe compartment. Variables can be made available to the eval by sharing them with the compartment.

To set the $debug variable in the example above, do

$compartment     = Safe->new('MY_SHARE');
$MY_SHARE::debug = 1;

$cs = Config::Scoped->new(
  file => 'config.txt',
  safe => $compartment,
);

$cfg_hash = $cs->parse;
⚠️ Only global variables can be shared with a compartment; lexical variables cannot. Don't try it, bestie.

perl_code is a synonym for eval.

🏷️ Tokens and quoting

A token is a

  • declaration name
  • parameter name
  • hash key
  • scalar value
  • macro name
  • macro value
  • include path
  • warning name

Any token may be quoted.

Tokens that contain special characters must be quoted. The special characters are

\s {} [] <> () ; , ' " = # %

Config::Scoped uses the Perl quoting syntax.

Tokens may be quoted with either single or double quotes

a = 'New York'
b = "New Jersey\n"

Here-docs are supported

a = <<EOT
New York
New Jersey
EOT

but generalized quotes (q(), qq(), etc.) are not. Text in here-docs is regarded as single-quoted if the delimiter is enclosed in single quotes, and double-quoted if the delimiter is enclosed in double quotes or unquoted.

Double-quoted tokens are evaluated as Perl strings inside the parser's Safe compartment. They're subject to the usual Perl backslash and variable interpolation, as well as macro expansion. Variables to be interpolated are passed via the Safe compartment, as shown above in "Perl code evaluation". If you need a literal $ or @ in a double-quoted string, be sure to escape it with a backslash (\) to suppress interpolation. 😌

An

eval { ... }

may appear anywhere that a token is expected. For example

foo {
    eval { 'b' . 'c' } = 1
}

parses to

$cfg_hash = { foo => { bc => 1 } }

💅 DIRECTIVES 💅

Okay bestie, listen. Config::Scoped has exactly three directives: %macro, %warning, and %include. That's the whole squad, no cap. ✨

🪄 Macros 🪄

A macro gets defined like this:

%macro name value

Macros may be defined:

  • at file scope
  • within anonymous blocks
  • within declaration blocks
  • within hash blocks

Macros defined inside blocks are lexically scoped to those blocks. They stay in their lane, fr fr.

Macro substitution happens:

  • within any double-quoted text
  • within the entirety of Perl eval blocks
  • nowhere else

Nowhere else, bestie. That's the vibe check. 💅

📦 Include files 📦

Config::Scoped supports include files.

To include one config file within another, write:

%include path/to/file

%include directives may appear:

  • at file scope
  • within anonymous blocks
  • nowhere else

In particular, %include directives may not appear within declaration blocks or hash blocks.

Parameters and macros in include files are imported to the current scope. You can control this scope with an anonymous block:

{
  %include dog.cfg
  dog { }  # sees imports from dog.cfg
}
bird { }   # does not see imports from dog.cfg

Warnings are scoped to the included file and do not leak to the parent file. It's giving "what happens in the include stays in the include." 🫶

Pathnames are either:

  • absolute
  • relative to the dirname of the current configuration file

For example, this config:

    # in configuration file /etc/myapp/global.cfg
    %include shared.cfg

includes the file /etc/myapp/shared.cfg.

When parsing a configuration string, the path is relative to the current working directory.

Include files are not actually included as text. Rather, they are processed by a recursive call to Config::Scoped. Subclass implementers may need to be aware of this.

🚨 Warnings 🚨

Config::Scoped can check for 5 problems with config files:

  • duplicate declaration names
  • duplicate parameter definitions
  • duplicate macro definitions
  • insecure config file permissions
  • invalid config cache digests

The API refers to these as "warnings", but they are actually errors, and if they occur, the parse fails and throws an exception. For consistency with the API, we'll use the term "warning" in the POD. Not me calling an error a warning, but the API said so. 💅

The five warnings are identified by five predefined warning names:

  • declaration
  • parameter
  • macro
  • permissions
  • digests

The permissions check requires that the config file:

  • be owned by root or the real UID of the running process AND
  • have no group or world write permissions

These restrictions help prevent an attacker from subverting a program by altering its config files. Highkey important.

The store_cache method computes MD5 checksums for the config file and all included files. These checksums are stored with the cached configuration.

The retrieve_cache method recomputes the checksums of the files and compares them to the stored values.

The digests check requires that the checksums agree. This helps prevent programs from relying on stale configuration caches.

All warnings are enabled by default.

Warnings can be disabled by passing the warning key to the constructor or with the set_warnings method.

Warnings can also be controlled with the %warnings directive, which has the form:

%warnings [name] off|on

A %warnings directive applies to the named warning, or to all warnings, if name is omitted.

%warnings directives allow warnings to be turned on and off as necessary throughout the config file. A %warnings directive may appear:

  • at file scope
  • within anonymous blocks
  • within declaration blocks
  • within hash blocks

Each %warnings directive is lexically scoped to its enclosing file or block.

Example:

  legs = 4
  cat  {}
  dog  {}
  bird
  {
      legs = 2
  }

fails with a duplicate parameter warning, but:

  legs = 4
  cat  {}
  dog  {}
  bird
  {
      %warnings parameter off;
      legs = 2
  }

successfully parses to:

    $cfg_hash = {
        cat  => { legs => 4 },
        dog  => { legs => 4 },
        bird => { legs => 2 },
      }

🌸 Best practices 🌸

As with all things Perl, there's more than one way to write configuration files. Here are some suggestions for writing config files that are concise, readable, and maintainable.

🍓 Perl data 🍓

Config::Scoped accepts most Perl data syntax. This allows Perl data to pulled into config files largely unaltered:

  foo
  {
     a = 1;
     b = [ 'red', 'green', 'blue' ];
     c = { x => 5,
           y => 6 };
  }

However, Config::Scoped doesn't require as much punctuation as Perl, and config files written from scratch will be cleaner without it:

  foo
  {
     a = 1
     b = [ red green blue ]
     c = { x => 5
           y => 6 }
  }

🫧 Anonymous blocks 🫧

Don't use anonymous blocks unless you need to restrict the scope of something. In particular, there is no need for a top-level anonymous block around the whole config file:

  {             # unnecessary
      foo { }
  }

👑 Inheritance 👑

Parameters that are outside of a declaration are inherited by all following declarations in their scope. Don't do this unless you mean it:

  wheels = 4
  car
  {
      # OK
  }
  cat
  {
      # I can haz weelz?
  }

🧱 Blocks, blocks, we got blocks... 🧱

Config::Scoped has four different kinds of blocks:

  • anonymous
  • declaration
  • eval
  • hash

They all look the same, but they aren't, and they have different rules and restrictions. See "CONFIG FILE FORMAT" for descriptions of each.

💀 Macros 💀

Macros are evil, and Config::Scoped macros are specially evil, because:

  • they don't respect token boundaries
  • where multiple substitutions are possible, the substitution order is undefined
  • substituted text may or may not be rescanned for further substitutions
Caveat scriptor. Periodt.

🧚 SUBCLASSING 🧚

Config::Scoped has no formally defined subclass interface. Here are some guidelines for writing subclasses. Implementers who override (or redefine) base class methods may need to read the Config::Scoped sources for more information. Iykyk.

Arbitrary

  $your_key => $value

pairs may be passed to the Config::Scoped constructor. They will be stored in the $cs->{local} hashref, and methods may access them with code like:

  $cs->{local}{$your_key}

To avoid conflict with existing keys in the local hash, consider distinguishing your keys with a unique prefix.

Arbitrary warning names may be defined, set with new and set_warnings, used in %warnings directives, and tested with warnings_on. Methods can call warnings_on to find out whether a warning is currently enabled.

All methods throw exceptions (die) on error. The exception object should be a subclass of Config::Scoped::Error. You can use one of the classes defined in Config::Scoped::Error, or you can derive your own. This code:

    Config::Scoped::Error->throw(
        -file => $cs->_get_file(%args),
        -line => $cs->_get_line(%args),
        -text => $message,
    );

will generate an error message that reports the location in the config file where the error was detected, rather than a location in Perl code. Iconic, honestly.

Config::Scoped performs validation checks on the elements of configuration files (declarations, parameters, macros, etc). Here are the interfaces to the validation methods. Subclasses can override these methods to modify or extend the validation checks.

  • $macro_value = $cs->macro_validate>(name => $name, value => $value) — Called for each %macro directive.
    • Receives the $name and $value from the directive. The returned $macro_value becomes the actual value of the macro.
    • If the macro is invalid, throws a Config::Scoped::Error::Validate::Macro exception.
  • $param_value = $cs->parameter_validate>(name => $name, value => $value) — Called for each parameter definition.
    • Receives the $name and $value from the definition. The returned $param_value becomes the actual value of the parameter.
    • If the parameter is invalid, throws a Config::Scoped::Error::Validate::Parameter exception.
  • $cs->declaration_validate(name => $name, value => $value, tail => $tail) — Called for each declaration.
    • $name is an array ref giving the chain of names for the declaration block. $value is a hash ref containing all the parameters in the declaration block. $tail is a hash ref containing all the parameters in any previously defined declaration with the same name(s).
    • For example, the declaration:
      foo bar baz { a=1 b=2 }

leads to the call:

      $cs->declaration_validate(name  => [ qw(foo bar baz) ],
                                    value => { a => '1', b => '2' },
                                    tail  => $cs->{local}{config}{foo}{bar}{baz});
  • The method can test %$tail to discover if there is an existing, non-empty declaration with the same name(s).
  • The method has no return value. However, the method can alter the contents of %$value. Upon return, the parameters in %$value become the actual contents of the declaration block.
  • If the declaration is invalid, throws a Config::Scoped::Error::Validate::Declaration exception.
  • $cs->permissions_validate(file => $file, handle => $handle) — Called for the config file, each included file, and each retrieved cache file. One of $file or $handle must be non-null.
    • Throws a Config::Scoped::Error::Validate::Permissions exception if the file is not safe to read.

👀 SEE ALSO 👀

  • Error
  • Safe
  • Config::Scoped::Error
  • Parse::RecDescent
  • "Quote and Quote-like Operators" in perlop

📝 TODO 📝

🧪 Tests 🧪

Still more tests needed.

🐛 BUGS 🐛

If you find parser bugs, please send the stripped down config file and additional version information to the author.

💖 CREDITS 💖

POD by Steven W. McDougall <swmcd@world.std.com>

✨ AUTHOR ✨

Karl Gaissmaier <karl.gaissmaier at uni-ulm.de>

Copyright (c) 2004-2012 by Karl Gaissmaier

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

💖 And that's the whole page, bestie! This was Config::Scoped(3pm), generated for perl v5.38.2, dated 2024-01-21. Periodt. 💖

📦 where this page comes from