.\" 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
.\" ========================================================================
.\"
.IX Title "SReview::Config 3pm"
.TH SReview::Config 3pm "2023-11-03" "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"
SReview::Config \- Self\-reproducing and self\-documenting configuration file system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use SReview::Config;
\&
\&  my $config = SReview::Config\->new(\*(Aq/etc/sreview/config.pm\*(Aq);
\&  $config\->define(\*(Aqname\*(Aq, \*(AqThe name of this element\*(Aq, \*(Aqdefault\*(Aq);
\&  ...
\&  print "You configured " . $config\->get(\*(Aqname\*(Aq) . " as the name\en";
\&  print "Full configuration: \en" . $config\->dump;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SReview::Config is a class to easily manage self-reproducing and
self-documenting configuration. You create an SReview::Config object,
populate it with possible configuration values, and then retrieve them.
.SH "METHODS"
.IX Header "METHODS"
.SS "SReview::Config\->new('path/to/filename');"
.IX Subsection "SReview::Config->new('path/to/filename');"
Create a new SReview::Config object.
.ie n .SS "$config\->define(name, doc, default)"
.el .SS "\f(CW$config\fP\->define(name, doc, default)"
.IX Subsection "$config->define(name, doc, default)"
Define a new configuration value. Not legal after \f(CW\*(C`get\*(C'\fR has already
been called.
.PP
Name should be the name of the configuration value. Apart from the fact
that it should not have a sigil, it should be a valid name for a perl
scalar variable.
.ie n .SS "$config\->define_deprecated(oldname, newname, conversion_sub)"
.el .SS "\f(CW$config\fP\->define_deprecated(oldname, newname, conversion_sub)"
.IX Subsection "$config->define_deprecated(oldname, newname, conversion_sub)"
Define a name as a deprecated way of configuring things. When this value
is set, SReview::Config will issue a warning that this option is now
deprecated, and that the user should use some other option instead.
.PP
The conversion subroutine is an optional argument that should mangle the
value given to \*(L"oldname\*(R" into the value expected by \*(L"newname\*(R". If it
returns nonzero, then SReview::Config will croak. It will receive a
reference to the \*(L"config\*(R" object, the value that is trying to be set, and the
name of the new parameter.
.PP
The default conversion sub just sets the value of the newname
configuration without any conversion.
.ie n .SS "$config\->define_computed('name')"
.el .SS "\f(CW$config\fP\->define_computed('name')"
.IX Subsection "$config->define_computed('name')"
Defines a default value for a particular configuration parameter through
a subroutine.
.PP
If the subroutine returns \f(CW\*(C`undef\*(C'\fR, that value will be ignored (and the
normal logic for defining a default will be used).
.PP
Should be used on a parameter that has already been defined through
  \f(CW$config\fR\->define
.ie n .SS "$config\->get('name')"
.el .SS "\f(CW$config\fP\->get('name')"
.IX Subsection "$config->get('name')"
Return the value of the given configuration item. Also finalizes the
definitions of this configuration file; that is, once this method has
been called, the \f(CW\*(C`define\*(C'\fR method above will croak.
.PP
The returned value will either be the default value configured at
\&\f(CW\*(C`define\*(C'\fR time, the value configured in the configuration file, or the
value set (in \s-1JSON\s0 format) in the environment variable
\&\f(CW\*(C`SREVIEW_\f(CIname\f(CW \*(C'\fR, where \fIname\fR is the upper-case version of the name
of the configuration item.
.ie n .SS "$config\->set('name', value);"
.el .SS "\f(CW$config\fP\->set('name', value);"
.IX Subsection "$config->set('name', value);"
Change the current value of the given configuration item.
.PP
Note, this does not change the defaults, only the configured value.
.ie n .SS "$config\->describe('name');"
.el .SS "\f(CW$config\fP\->describe('name');"
.IX Subsection "$config->describe('name');"
Return the documentation string for the given name
.ie n .SS "$config\->dump"
.el .SS "\f(CW$config\fP\->dump"
.IX Subsection "$config->dump"
Return a string describing the whole configuration.
.PP
Each configuration item will produced in one of the following two
formats:
.IP "\(bu" 4
For an item that only has a default set:
.Sp
.Vb 2
\&  # Documentation value given to define
\&  #$name = "default value";
.Ve
.IP "\(bu" 4
For an item that has a different value configured (either through the
configuration file, or through \f(CW\*(C`set\*(C'\fR):
.Sp
.Vb 2
\&  # Documentation value given to define
\&  $name = "current value";
.Ve
.ie n .SS "$config\->dump_item(""item"")"
.el .SS "\f(CW$config\fP\->dump_item(``item'')"
.IX Subsection "$config->dump_item(item)"
Print a \s-1JSON\s0 value for the given configuration item. Prints the default
item if this item hasn't been set a value.
.ie n .SS "$config\->is_default(""item"")"
.el .SS "\f(CW$config\fP\->is_default(``item'')"
.IX Subsection "$config->is_default(item)"
Return a truthy value if the given configuration item is still at its
default value.
.ie n .SS "$config\->keys"
.el .SS "\f(CW$config\fP\->keys"
.IX Subsection "$config->keys"
Returns a list (unsorted) of all the known configuration names.
.SH "BUGS"
.IX Header "BUGS"
It is currently not possible to load more than one configuration file in
the same process space. This will be fixed at some point in the future.