.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::Model::Instance 3pm"
.TH Config::Model::Instance 3pm "2023-08-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Model::Instance \- Instance of configuration tree
.SH "VERSION"
.IX Header "VERSION"
version 2.153
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Config::Model;
\& use File::Path ;
\&
\& # setup a dummy popcon conf file
\& my $wr_dir = \*(Aq/tmp/etc/\*(Aq;
\& my $conf_file = "$wr_dir/popularity\-contest.conf" ;
\&
\& unless (\-d $wr_dir) {
\&     mkpath($wr_dir, { mode => 0755 }) 
\&       || die "can\*(Aqt mkpath $wr_dir: $!";
\& }
\& open(my $conf,"> $conf_file" ) || die "can\*(Aqt open $conf_file: $!";
\& $conf\->print( qq!MY_HOSTID="aaaaaaaaaaaaaaaaaaaa"\en!,
\&   qq!PARTICIPATE="yes"\en!,
\&   qq!USEHTTP="yes" # always http\en!,
\&   qq!DAY="6"\en!);
\& $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   => \*(AqPopCon\*(Aq,
\&                              root_dir          => \*(Aq/tmp\*(Aq,
\&                             );
\& my $root = $inst \-> config_root ;
\&
\& print $root\->describe;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an object that holds a configuration tree.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
An instance object is created by calling instance
method on an existing
model. This model can be specified by its application name:
.PP
.Vb 6
\& my $inst = $model\->instance (
\&   # run \*(Aqcme list\*(Aq to get list of applications
\&   application => \*(Aqfoo\*(Aq,
\&   # optional
\&   instance_name => \*(Aqtest1\*(Aq
\& );
\&
\& my $inst = $model\->instance (
\&   root_class_name => \*(AqSomeRootClass\*(Aq,
\&   instance_name => \*(Aqtest1\*(Aq
\& );
.Ve
.PP
The directory (or directories) holding configuration files is
specified within the configuration model. For test purpose you can
change the \*(L"root\*(R" directory with \f(CW\*(C`root_dir\*(C'\fR parameter.
.PP
Constructor parameters are:
.IP "root_dir" 4
.IX Item "root_dir"
Pseudo root directory where to read \fIand\fR write configuration
files (Path::Tiny object or string). Configuration directory
specified in model or with \f(CW\*(C`config_dir\*(C'\fR option is appended to this
root directory
.IP "root_path" 4
.IX Item "root_path"
Path::Tiny object created with \f(CW\*(C`root_dir\*(C'\fR value or with current
directory if \f(CW\*(C`root_dir\*(C'\fR is empty.
.IP "config_dir" 4
.IX Item "config_dir"
Directory to read or write configuration file. This parameter must be
supplied if not provided by the configuration model. (string)
.IP "backend_arg" 4
.IX Item "backend_arg"
Specify a backend argument that may be retrieved by some
backend. Instance is used as a relay and does not use this data.
.IP "check" 4
.IX Item "check"
Specify whether to check value while reading config files. Either:
.RS 4
.IP "yes" 4
.IX Item "yes"
Check value and throws an error for bad values.
.IP "skip" 4
.IX Item "skip"
Check value and skip bad value.
.IP "no" 4
.IX Item "no"
Do not check.
.RE
.RS 4
.RE
.IP "canonical" 4
.IX Item "canonical"
When true: write config data back using model order. By default, write
items back using the order found in the configuration file. This
feature is experimental and not supported by all backends.
.IP "on_change_cb" 4
.IX Item "on_change_cb"
Call back this function whenever \f(CW\*(C`notify_change\*(C'\fR is called. Called with
arguments: \f(CW\*(C`name => <root node element name>, index => <index_value>\*(C'\fR
.IP "on_message_cb" 4
.IX Item "on_message_cb"
Call back this function when show_message is called. By default,
messages are displayed on \s-1STDOUT.\s0
.IP "error_paths" 4
.IX Item "error_paths"
Returns a list of tree items that currently have an error.
.IP "error_messages" 4
.IX Item "error_messages"
Returns a list of error messages from the tree content.
.PP
Note that the root directory specified within the configuration model
is overridden by \f(CW\*(C`root_dir\*(C'\fR parameter.
.PP
If you need to load configuration data that are not correct, you can
use \f(CW\*(C`force_load => 1\*(C'\fR. Then, wrong data are discarded (equivalent to
\&\f(CW\*(C`check => \*(Aqno\*(Aq\*(C'\fR ).
.SH "METHODS"
.IX Header "METHODS"
.SS "Manage configuration data"
.IX Subsection "Manage configuration data"
.SS "modify"
.IX Subsection "modify"
Calls \*(L"load\*(R" and then \*(L"save\*(R".
.PP
Takes the same parameter as \f(CW\*(C`load\*(C'\fR plus:
.ie n .IP """force_write""" 4
.el .IP "\f(CWforce_write\fR" 4
.IX Item "force_write"
Force saving configuration file even if no value was modified
(default is 0)
.ie n .IP """quiet""" 4
.el .IP "\f(CWquiet\fR" 4
.IX Item "quiet"
Do no display the changes brought by the modification steps
.SS "load"
.IX Subsection "load"
Load configuration tree with configuration data. See
\&\*(L"load\*(R" in Config::Model::Loader for parameters.
Returns <$self>.
.SS "save"
.IX Subsection "save"
Save the content of the configuration tree to
configuration files. (See \*(L"write_back\*(R" for more details)
.PP
Use \f(CW\*(C`force => 1\*(C'\fR option to force saving configuration data.
.SS "config_root"
.IX Subsection "config_root"
Returns the root object of the configuration tree.
.SS "apply_fixes"
.IX Subsection "apply_fixes"
Scan the tree and apply fixes that are attached to warning specifications. 
See \f(CW\*(C`warn_if_match\*(C'\fR or \f(CW\*(C`warn_unless_match\*(C'\fR in "" in Config::Model::Value.
.SS "deep_check"
.IX Subsection "deep_check"
Scan the tree and deep check on all elements that support this. Currently only hash or
list element have this feature.
.SS "needs_save"
.IX Subsection "needs_save"
Returns 1 (or more) if the instance contains data that needs to be
saved. I.e some change were done in the tree that needs to be saved.
.SS "has_changes"
.IX Subsection "has_changes"
Returns true if the instance contains unsasved changes.
.SS "list_changes"
.IX Subsection "list_changes"
In list context, returns a array ref of strings describing the changes.
In scalar context, returns a big string. Useful to print.
.SS "say_changes"
.IX Subsection "say_changes"
Print all changes on \s-1STDOUT\s0 and return \f(CW$self\fR.
.SS "clear_changes"
.IX Subsection "clear_changes"
Clear list of changes. Note that changes pending in the configuration
tree is not affected. This clears only the list shown to user. Use
only for tests.
.SS "has_warning"
.IX Subsection "has_warning"
Returns the number of warning found in the elements of this configuration instance.
.SS "update"
.IX Subsection "update"
Parameters: \f(CW\*(C`( quiet => (0|1), %args )\*(C'\fR
.PP
Try to run update command on all nodes of the configuration tree. Node
without \f(CW\*(C`update\*(C'\fR method are ignored. \f(CW\*(C`update\*(C'\fR prints a message
otherwise (unless \f(CW\*(C`quiet\*(C'\fR is true).
.SS "grab"
.IX Subsection "grab"
Use the steps parameter to retrieve and returns an object from the
configuration tree.  Forwarded to \*(L"grab\*(R" in Config::Model::Role::Grab
.SS "grab_value"
.IX Subsection "grab_value"
Use the steps parameter to retrieve and returns the value of a leaf
object from the configuration tree.  Forwarded to
\&\*(L"grab_value\*(R" in Config::Model::Role::Grab
.SS "searcher"
.IX Subsection "searcher"
Returns an object dedicated to search an element in the configuration
model.
.PP
This method returns a Config::Model::Searcher object. See
Config::Model::Searcher for details on how to handle a search.
.SS "iterator"
.IX Subsection "iterator"
This method returns a Config::Model::Iterator object. See
Config::Model::Iterator for details.
.PP
Arguments are explained in  Config::Model::Iterator
constructor arguments.
.SS "application"
.IX Subsection "application"
Returns the application name of the instance. (E.g \f(CW\*(C`popcon\*(C'\fR, \f(CW\*(C`dpkg\*(C'\fR ...)
.SS "wizard_helper"
.IX Subsection "wizard_helper"
Deprecated. Call \*(L"iterator\*(R" instead.
.SH "Internal methods"
.IX Header "Internal methods"
.SS "name"
.IX Subsection "name"
Returns the instance name.
.SS "read_check"
.IX Subsection "read_check"
Returns which kind of check is performed while reading configuration
files. (see \f(CW\*(C`check\*(C'\fR parameter in \*(L"\s-1CONSTRUCTOR\*(R"\s0 section)
.SS "show_message"
.IX Subsection "show_message"
Parameters: \f(CW\*(C`( string )\*(C'\fR
.PP
Display the message on \s-1STDOUT\s0 unless a custom function was passed to
\&\f(CW\*(C`on_message_cb\*(C'\fR parameter.
.SS "reset_config"
.IX Subsection "reset_config"
Destroy current configuration tree (with data) and returns a new tree with
data (and annotations) loaded from disk.
.SS "config_model"
.IX Subsection "config_model"
Returns the model (Config::Model object) of the configuration tree.
.SS "annotation_saver"
.IX Subsection "annotation_saver"
Returns the object loading and saving annotations. See
Config::Model::Annotation for details.
.SS "preset_start"
.IX Subsection "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)
.SS "preset_stop"
.IX Subsection "preset_stop"
Stop preset mode
.SS "preset"
.IX Subsection "preset"
Get preset mode
.SS "preset_clear"
.IX Subsection "preset_clear"
Clear all preset values stored.
.SS "layered_start"
.IX Subsection "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)
.SS "layered_stop"
.IX Subsection "layered_stop"
Stop layered mode
.SS "layered"
.IX Subsection "layered"
Get layered mode
.SS "layered_clear"
.IX Subsection "layered_clear"
Clear all layered values stored.
.SS "get_data_mode"
.IX Subsection "get_data_mode"
Returns 'normal' or 'preset' or 'layered'. Does not take into account
initial_load.
.SS "initial_load_start"
.IX Subsection "initial_load_start"
Start initial_load mode. This mode tracks the first modifications of
the tree done with data read from the configuration file.
.PP
Instance is built with initial_load as 1. Read backend clears this
value once the first read is done.
.PP
Other modifications, when initial_load is zero, are assumed to be user
modifications.
.SS "initial_load_stop"
.IX Subsection "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.
.SS "initial_load"
.IX Subsection "initial_load"
Get initial_load mode
.SS "data"
.IX Subsection "data"
This method provides a way to store some arbitrary data in the
instance object.
.PP
E.g:
.PP
.Vb 1
\&  $instance\->data(foo => \*(Aqbar\*(Aq);
.Ve
.PP
Later:
.PP
.Vb 1
\&  my $foo = $instance\->data(\*(Aqfoo\*(Aq); # $foo contains \*(Aqbar\*(Aq
.Ve
.SH "Read and write backend features"
.IX Header "Read and write backend features"
Usually, a program based on config model must first create the
configuration model, then load all configuration data.
.PP
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.
.SS "backend_arg"
.IX Subsection "backend_arg"
Get cme command line argument that may be used by the backend to
get the configuration file. These method is typically used in the read
and write method of a backend to know where is the configuration file
to edit.
.SS "root_dir"
.IX Subsection "root_dir"
Returns a Path::Tiny object for the root directory where
configuration data is read from or written to.
.SS "root_path"
.IX Subsection "root_path"
Same as \f(CW\*(C`root_dir\*(C'\fR
.SS "register_write_back"
.IX Subsection "register_write_back"
Parameters: \f(CW\*(C`( node_location )\*(C'\fR
.PP
Register a node path that is called back with
\&\f(CW\*(C`write_back\*(C'\fR method.
.SS "notify_change"
.IX Subsection "notify_change"
Notify that some data has changed in the tree. See
\&\*(L"notify_change\*(R" in Config::Model::AnyThing for more details.
.SS "write_back"
.IX Subsection "write_back"
In summary, save the content of the configuration tree to
configuration files.
.PP
In more details, \f(CW\*(C`write_back\*(C'\fR tries to run all subroutines registered
with \f(CW\*(C`register_write_back\*(C'\fR to write the configuration information.
(See Config::Model::BackendMgr for details).
.PP
You can specify here another config directory to write configuration
data back with \f(CW\*(C`config_dir\*(C'\fR parameter. This overrides the model
specifications.
.PP
\&\f(CW\*(C`write_back\*(C'\fR croaks if no write call-back are known.
.PP
Use \f(CW\*(C`force => 1\*(C'\fR option to force saving configuration data. This
is useful to write back a file even no change are done at semantic
level, i.e. to reformat a file or remove unnecessary data.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, (ddumont at cpan dot org)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Model, 
Config::Model::Node, 
Config::Model::Loader,
Config::Model::Searcher,
Config::Model::Value,
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2005\-2022 by Dominique Dumont.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve