.\" 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::Warper 3pm"
.TH Config::Model::Warper 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::Warper \- Warp tree properties
.SH "VERSION"
.IX Header "VERSION"
version 2.153
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # internal class
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Depending on the value of a warp master (In fact a Config::Model::Value or a Config::Model::CheckList object),
this class changes the properties of a node (Config::Model::WarpedNode),
a hash (Config::Model::HashId), a list (Config::Model::ListId), 
a checklist (Config::Model::CheckList) or another value.
.SH "Warper and warped"
.IX Header "Warper and warped"
Warping an object means that the properties of the object is
changed depending on the value of another object.
.PP
The changed object is referred as the \fIwarped\fR object.
.PP
The other object that holds the important value is referred as the
\&\fIwarp master\fR or the \fIwarper\fR object.
.PP
You can also set up several warp master for one warped object. This
means that the properties of the warped object is changed
according to a combination of values of the warp masters.
.SH "Warp arguments"
.IX Header "Warp arguments"
Warp arguments are passed in a hash ref whose keys are \f(CW\*(C`follow\*(C'\fR and
and \f(CW\*(C`rules\*(C'\fR:
.SS "Warp follow argument"
.IX Subsection "Warp follow argument"
Grab string leading to the
\&\f(CW\*(C`Config::Model::Value\*(C'\fR or Config::Model::CheckList warp master. E.g.:
.PP
.Vb 1
\& follow => \*(Aq! tree_macro\*(Aq
.Ve
.PP
In case of several warp master, \f(CW\*(C`follow\*(C'\fR is set to an array ref
of several grab string:
.PP
.Vb 1
\& follow => [ \*(Aq! macro1\*(Aq, \*(Aq\- macro2\*(Aq ]
.Ve
.PP
You can also use named parameters:
.PP
.Vb 1
\& follow => { m1 => \*(Aq! macro1\*(Aq, m2 => \*(Aq\- macro2\*(Aq }
.Ve
.PP
Note: By design \f(CW\*(C`follow\*(C'\fR argument of warper module is a plain path to keep
warp mechanism (relatively) simple. \f(CW\*(C`follow\*(C'\fR argument
of Config::Model::ValueComputer has more features and is documented
there
.SS "Warp rules argument"
.IX Subsection "Warp rules argument"
String, hash ref or array ref that specify the warped object property
changes.  These rules specifies the actual property changes for the
warped object depending on the value(s) of the warp master(s).
.PP
E.g. for a simple case (rules is a hash ref) :
.PP
.Vb 4
\& follow => \*(Aq! macro1\*(Aq ,
\& rules => { A => { <effect when macro1 is A> },
\&            B => { <effect when macro1 is B> }
\&          }
.Ve
.PP
In case of similar effects, you can use named parameters and
a boolean expression to specify the effect. The first match
is applied. In this case, rules is a list ref:
.PP
.Vb 4
\&  follow => { m => \*(Aq! macro1\*(Aq } ,
\&  rules => [ \*(Aq$m eq "A"\*(Aq               => { <effect for macro1 == A> },
\&             \*(Aq$m eq "B" or $m eq"C "\*(Aq  => { <effect for macro1 == B|C > }
\&           ]
.Ve
.PP
In case of several warp masters, \f(CW\*(C`follow\*(C'\fR must use named parameters, and
rules must use boolean expression:
.PP
.Vb 7
\& follow => { m1 => \*(Aq! macro1\*(Aq, m2 => \*(Aq\- macro2\*(Aq } ,
\& rules => [
\&           \*(Aq$m1 eq "A" && $m2 eq "C"\*(Aq => { <effect for A C> },
\&           \*(Aq$m1 eq "A" && $m2 eq "D"\*(Aq => { <effect for A D> },
\&           \*(Aq$m1 eq "B" && $m2 eq "C"\*(Aq => { <effect for B C> },
\&           \*(Aq$m1 eq "B" && $m2 eq "D"\*(Aq => { <effect for B D> },
\&          ]
.Ve
.PP
Of course some combinations of warp master values can have the same
effect:
.PP
.Vb 7
\& follow => { m1 => \*(Aq! macro1\*(Aq, m2 => \*(Aq\- macro2\*(Aq } ,
\& rules => [
\&           \*(Aq$m1 eq "A" && $m2 eq "C"\*(Aq => { <effect X> },
\&           \*(Aq$m1 eq "A" && $m2 eq "D"\*(Aq => { <effect Y> },
\&           \*(Aq$m1 eq "B" && $m2 eq "C"\*(Aq => { <effect Y> },
\&           \*(Aq$m1 eq "B" && $m2 eq "D"\*(Aq => { <effect Y> },
\&          ]
.Ve
.PP
In this case, you can use different boolean expression to save typing:
.PP
.Vb 6
\& follow => { m1 => \*(Aq! macro1\*(Aq, m2 => \*(Aq\- macro2\*(Aq } ,
\& rules => [
\&           \*(Aq$m1 eq "A" && $m2 eq "C"\*(Aq => { <effect X> },
\&           \*(Aq$m1 eq "A" && $m2 eq "D"\*(Aq => { <effect Y> },
\&           \*(Aq$m1 eq "B" && ( $m2 eq "C" or $m2 eq "D") \*(Aq => { <effect Y> },
\&          ]
.Ve
.PP
Note that the boolean expression is sanitized and used in a Perl
eval, so you can use most Perl syntax and regular expressions.
.PP
Functions (like \f(CW&foo\fR) are called like \f(CW\*(C`$self\->foo\*(C'\fR before evaluation
of the boolean expression.
.PP
The rules must be declared with a slightly different way when a
check_list is used as a warp master: a check_list has not a simple
value. The rule must check whether a value is checked or not amongs
all the possible items of a check list.
.PP
For example, let's say that \f(CW$cl\fR in the rule below point to a check list whose
items are \f(CW\*(C`A\*(C'\fR and \f(CW\*(C`B\*(C'\fR. The rule must verify if the item is set or not:
.PP
.Vb 6
\&  rules => [
\&       \*(Aq$cl.is_set(A)\*(Aq =>  { <effect when A is set> },
\&       \*(Aq$cl.is_set(B)\*(Aq =>  { <effect when B is set> },
\&       # can be combined
\&       \*(Aq$cl.is_set(B) and $cl.is_set(A)\*(Aq =>  { <effect when A and B are set> },
\&   ],
.Ve
.PP
With this feature, you can control with a check list whether some element must
be shown or not (assuming \f(CW\*(C`FooClass\*(C'\fR and \f(CW\*(C`BarClass\*(C'\fR classes are declared):
.PP
.Vb 10
\&    element => [
\&        # warp master
\&        my_check_list => {
\&            type       => \*(Aqcheck_list\*(Aq,
\&            choice     => [\*(Aqhas_foo\*(Aq,\*(Aqhas_bar\*(Aq]
\&        },
\&        # controlled element that show up only when has_foo is set
\&        foo => {
\&            type => \*(Aqwarped_node\*(Aq,
\&            level => \*(Aqhidden\*(Aq,
\&            config_class_name => \*(AqFooClass\*(Aq,
\&            follow => {
\&                selected => \*(Aq\- my_check_list\*(Aq
\&            },
\&            \*(Aqrules\*(Aq => [
\&                \*(Aq$selected.is_set(has_foo)\*(Aq => {
\&                    level => \*(Aqnormal\*(Aq
\&                }
\&            ]
\&        },
\&        # controlled element that show up only when has_bar is set
\&        bar => {
\&            type => \*(Aqwarped_node\*(Aq,
\&            level => \*(Aqhidden\*(Aq,
\&            config_class_name => \*(AqBarClass\*(Aq,
\&            follow => {
\&                selected => \*(Aq\- my_check_list\*(Aq
\&            },
\&            \*(Aqrules\*(Aq => [
\&                \*(Aq$selected.is_set(has_bar)\*(Aq => {
\&                    level => \*(Aqnormal\*(Aq
\&                }
\&            ]
\&        }
\&    ]
.Ve
.SH "Methods"
.IX Header "Methods"
.SS "warp_error"
.IX Subsection "warp_error"
This method returns a string describing:
.IP "\(bu" 4
The location(s) of the warp master
.IP "\(bu" 4
The current value(s) of the warp master(s)
.IP "\(bu" 4
The other values accepted by the warp master that can be tried (if the
warp master is an enumerated type)
.SH "How does this work ?"
.IX Header "How does this work ?"
.IP "Registration" 4
.IX Item "Registration"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
When a warped object is created, the constructor registers to the
warp masters. The warp master are found by using the special string
passed to the \f(CW\*(C`follow\*(C'\fR parameter. As explained in 
grab method,
the string provides the location of the warp master in the
configuration tree using a symbolic form.
.IP "\(bu" 4
Then the warped object retrieve the value(s) of the warp master(s)
.IP "\(bu" 4
Then the warped object warps itself using the above
value(s). Depending on these value(s), the properties of the warped
object are modified.
.RE
.RS 4
.RE
.IP "Master update" 4
.IX Item "Master update"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
When a warp master value is updated, the warp master calls \fIall\fR
its warped object and pass them the new master value.
.IP "\(bu" 4
Then each warped object modifies properties according to the
new warp master value.
.RE
.RS 4
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, (ddumont at cpan dot org)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Model::AnyThing,
Config::Model::HashId,
Config::Model::ListId,
Config::Model::WarpedNode,
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