Takes a string that contains configuration in INI format and parses it into an array of configuration sections. It returns a reference to that array.

Using an array, as opposed to a hash, ensures that the section order is preserved, so we know in which order to process plugins in Brickyard's plugins_with() method.

Each array element corresponds to an INI section. Each section is itself a reference to an array with three elements:

The first element is the section name. The second element is the package name of the plugin; it is obtained by expanding the section name using expand_package(). The third element is a reference to a plugin configuration hash; it is the section's payload. If a section payload key occurs several times, it is turned into an array reference in the plugin configuration hash.

The first section is the global section, denoted by the name _. Any payload in the INI configuration that occurs before the first section ends up in this section.

What if you want to pass more complex configuration like a hash of arrays? An INI file is basically just a key-value mapping. In that case you can use a special notation for the key where you use dots to separate the individual elements - array indices and hash keys. For example:

You can also define custom expansions. There are two ways to do this. First you can pass a reference to an array of expansions to the expand() method, or you can define them using the expand key in the configuration's root section. Each expansion is a string that is evaluated for each package name. Custom expansions are useful if you have plugins in several namespaces, for example.

Here is an example of defining a custom expansion directly on the Brickyard object:

Takes a configuration file name specification or a reference to a string containing the INI string, a root object, and an optional callback. The file specification can be a simple file name or a colon-separated list of file names. Each of these files is parsed with parse_ini() and merged. The result is passed to init_from_config_structure(), along with the root object and optional callback - see its documentation for what these things do.

When two configurations are merged, the root sections are merged like a hash, but any plugin sections are appended in the order they are found.

This mechanism exists so you can, for example, have sensitive information like passwords in a separate file. For example:

Takes a configuration structure and a root object, and an optional callback. For each configuration section it creates a plugin object, initializes it with the plugin configuration hash and adds it to the brickyard's array of plugins.

Any configuration keys that appear in the configuration's root section are set on the root object. So the root object can be anything that has set-accessors for all the configuration keys that can appear in the configuration's root section. One exception is the expand key, which is turned into a custom expansion; see above.

The configuration needs to be a reference to a list of sections as returned by init_from_config(), for example.