Config...nstance(3pm)

📦

version 2.166 · 8 versions

🌸 NAME 🌸

Config::Model::Instance — an Instance of configuration tree. Yes bestie, that's literally the whole name. It's giving "I hold a whole config tree and I'm chill about it". 💅

This is part of the User Contributed Perl Documentation, i.e. the Config...nstance(3pm) page, so if you were looking for the manual you found her. ✨

🎀 VERSION 🎀

version 2.166

✨ SYNOPSIS ✨

okay so here's the entire vibe in code form, copy it exactly, no cap:

use Config::Model;
use File::Path ;

# setup a dummy popcon conf file
my $wr_dir = '/tmp/etc/';
my $conf_file = "$wr_dir/popularity-contest.conf" ;

unless (-d $wr_dir) {
    mkpath($wr_dir, { mode => 0755 })
      || die "can't mkpath $wr_dir: $!";
}
open(my $conf,"> $conf_file" ) || die "can't open $conf_file: $!";
$conf->print( qq!MY_HOSTID="aaaaaaaaaaaaaaaaaaaa"\n!,
  qq!PARTICIPATE="yes"\n!,
  qq!USEHTTP="yes" # always http\n!,
  qq!DAY="6"\n!);
$conf->close ;

my $model = Config::Model->new;

# PopCon model is provided. Create a new Config::Model::Instance object
my $inst = $model->instance (root_class_name   => 'PopCon',
                             root_dir          => '/tmp',
                            );
my $root = $inst -> config_root ;

print $root->describe;

🦋 DESCRIPTION 🦋

This module provides an object that holds a configuration tree. That's the whole job. She's a container, she's holding the whole tree, main character energy honestly. 🌳

👑 CONSTRUCTOR 👑

So to make an instance object, you call the instance method on an existing model. And you can point at that model by its application name, like:

my $inst = $model->instance (
  # run 'cme list' to get list of applications
  application => 'foo',
  # optional
  instance_name => 'test1'
);

my $inst = $model->instance (
  root_class_name => 'SomeRootClass',
  instance_name => 'test1'
);

The directory (or directories, plural, she's flexible 💁) that holds the configuration files is specified inside the configuration model itself. But for testing purposes you can switch up that "root" directory with the root_dir parameter. iykyk. 🧚

Constructor parameters are, bestie, listen:

root_dir — the pseudo root directory where config files get read from and written to. Takes a Path::Tiny object or a plain string. Whatever configuration directory the model specifies (or the one you pass with config_dir) gets appended onto this root directory. 💖
root_path — a Path::Tiny object built from the root_dir value, or from the current directory if root_dir is empty.
config_dir — the directory to read or write the configuration file. You must supply this if the configuration model doesn't already provide one. (string, periodt.)
backend_arg — specify a backend argument that some backend might retrieve later. The Instance is just the relay here, she does not use this data herself. 💅
check — says whether to check values while reading config files. Either:
- yes — check the value and throw an error for bad values. 😤
- skip — check the value and skip the bad value. 🫣
- no — do not check. At all. Zero checking. 💀
canonical — when true, write config data back using model order. By default, items get written back in the order found in the configuration file. Heads up though: this feature is experimental and not supported by all backends. ⚠️
on_change_cb — call back this function whenever notify_change is called. It's called with arguments: name => <root node element name>, index => <index_value>
on_message_cb — call back this function when show_message is called. By default, messages are displayed on STDOUT. 📢
error_paths — returns a list of tree items that currently have an error.
error_messages — returns a list of error messages from the tree content.

Note that the root directory specified within the configuration model gets overridden by the root_dir parameter. No arguing with her. 🙈

And if you need to load configuration data that is, mm, not correct, you can use force_load => 1. In that case the wrong data are discarded (equivalent to check => 'no'). 🌈

💅 METHODS 💅

🌈 Manage configuration data 🌈

modify — calls load and then save. Takes the same parameters as load, plus:
- force_write — force saving the configuration file even if no value was modified (default is 0).
- quiet — do no display the changes brought by the modification steps.
load — load the configuration tree with configuration data. See load in Config::Model::Loader for the parameters. Returns <$self>. 🫶
save — save the content of the configuration tree to configuration files. (See write_back for more details.) Use the force => 1 option to force saving configuration data.
config_root — returns the root object of the configuration tree. The mother of all roots. 👑
apply_fixes — scan the tree and apply fixes that are attached to warning specifications. See warn_if_match or warn_unless_match in "" in Config::Model::Value. (yeah bestie, that's exactly how the original points at it, we don't question the citation.)
deep_check — scan the tree and deep check on all elements that support this. Currently only hash or list element have this feature.
needs_save — returns 1 (or more) if the instance contains data that needs to be saved. I.e. some change was done in the tree that needs to be saved. 👀
has_changes — returns true if the instance contains unsasved changes. (yes, "unsasved", she said what she said 💀)
list_changes — in list context, returns an array ref of strings describing the changes. In scalar context, returns a big string. Useful to print. 📝
say_changes — print all changes on STDOUT and return $self.
clear_changes — clear the list of changes. Note that changes pending in the configuration tree are not affected. This clears only the list shown to the user. Use only for tests.
has_warning — returns the number of warning found in the elements of this configuration instance.
update — parameters: ( quiet => (0|1), %args )

Try to run the update method on all nodes and leaves of the configuration tree.

Nodes without an update method get ignored. update prints a message otherwise (unless quiet is true). Note that a plain Config::Model::Node has no update method. Only classes inheriting from Config::Model::Node can have update methods.

update is called on all leaves. update in Config::Model::Values is called as well, to update value from external files, like INI or YAML file, according to the user's configuration model.

The goal of the update method is to update configuration data from external data. For instance, update is called on Config::Model::Dpkg::Copyright nodes to update copyright data from sources files. 🔥

grab — use the steps parameter to retrieve and returns an object from the configuration tree. Forwarded to grab in Config::Model::Role::Grab.
grab_value — use the steps parameter to retrieve and returns the value of a leaf object from the configuration tree. Forwarded to grab_value in Config::Model::Role::Grab.
searcher — returns an object dedicated to search an element in the configuration model. This method returns a Config::Model::Searcher object. See Config::Model::Searcher for details on how to handle a search. 🔍
iterator — this method returns a Config::Model::Iterator object. See Config::Model::Iterator for details. The arguments are explained in the Config::Model::Iterator constructor arguments.
application — returns the application name of the instance. (E.g popcon, dpkg …) 🎀
wizard_helper — Deprecated. Call iterator instead. (we do not use her anymore bestie 🚫)

🧚 Internal methods 🧚

name — returns the instance name.
read_check — returns which kind of check is performed while reading configuration files. (see the check parameter in the CONSTRUCTOR section)
show_message — parameters: ( string )

Display the message on STDOUT unless a custom function was passed to the on_message_cb parameter.

reset_config — destroy the current configuration tree (with data) and returns a new tree with data (and annotations) loaded from disk. ✨
config_model — returns the model (Config::Model object) of the configuration tree.
annotation_saver — returns the object loading and saving annotations. See Config::Model::Annotation for details.
preset_start — all values stored in preset mode are shown to the user as default values. This feature is useful to enter configuration data entered by an automatic process (like hardware scan). 🤖
preset_stop — stop preset mode.
preset — get preset mode.
preset_clear — clear all preset values stored.
layered_start — all values stored in layered mode are shown to the user as default values. This feature is useful to enter configuration data entered by an automatic process (like hardware scan). 🧅
layered_stop — stop layered mode.
layered — get layered mode.
layered_clear — clear all layered values stored.
get_data_mode — returns 'normal' or 'preset' or 'layered'. Does not take into account initial_load.
initial_load_start — start initial_load mode. This mode tracks the first modifications of the tree done with data read from the configuration file.

Instance is built with initial_load as 1. Read backend clears this value once the first read is done.

Other modifications, when initial_load is zero, are assumed to be user modifications. 🙋

initial_load_stop — stop initial_load mode. Instance is built with initial_load as 1. Read backend clears this value once the first read is done.
initial_load — get initial_load mode.
data — this method provides a way to store some arbitrary data in the instance object. E.g:

$instance->data(foo => 'bar');

Later:

my $foo = $instance->data('foo'); # $foo contains 'bar'

💜 Read and write backend features 💜

Usually, a program based on config model must first create the configuration model, then load all configuration data.

This feature enables you to declare with the model a way to load configuration data (and to write it back). See Config::Model::BackendMgr for details.

backend_arg — get the cme command line argument that may be used by the backend to get the configuration file. This method is typically used in the read and write method of a backend to know where the configuration file to edit is. 📂
root_dir — returns a Path::Tiny object for the root directory where configuration data is read from or written to.
root_path — same as root_dir.
register_write_back — parameters: ( node_location )

notify_change — notify that some data has changed in the tree. See notify_change in Config::Model::AnyThing for more details. 🔔
write_back — in summary, save the content of the configuration tree to configuration files.

In more details, write_back tries to run all subroutines registered with register_write_back to write the configuration information. (See Config::Model::BackendMgr for details.)

You can specify here another config directory to write configuration data back with the config_dir parameter. This overrides the model specifications.

write_back croaks if no write call-backs are known. 💀

Use the force => 1 option to force saving configuration data. This is useful to write back a file even when no change is done at the semantic level, i.e. to reformat a file or remove unnecessary data. 🌟

💖 AUTHOR 💖

Dominique Dumont, (ddumont at cpan dot org)

Give her flowers, she wrote all of this. 🫶🌹

✨ SEE ALSO ✨

okay bestie, when you're done here and you wanna go meet the rest of the family 💖 — these are the modules that ride with Config::Model::Instance:

Config::Model — the mothership 👑
Config::Model::Node — the node situation
Config::Model::Loader — the one that loads stuff in
Config::Model::Searcher — the one that goes hunting 🔍
Config::Model::Value — the value girlies

👑 AUTHOR

Dominique Dumont

(yes, them again — and we're still obsessed, the range is unreal 💅)

📜 COPYRIGHT AND LICENSE

And this is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999

free software, licensed correctly, we love to see it ✨

ngl, that's the whole page bestie 🫶 you read all of it, main character energy fr fr. now go instantiate something and slay 💅

this page came from perl v5.42.3, dated 2026-07-23, and it's the Config...nstance(3pm) page — periodt 💖🌸🦋

📦 where this page comes from

ubuntu stonking: libconfig-model-perl 2.166-1 · LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms