.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "Padre::Config 3pm"
.TH Padre::Config 3pm "2014-09-11" "perl v5.20.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"
Padre::Config \- Configuration subsystem for Padre
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Padre::Config;
\&    [...]
\&    if ( Padre::Config\->main_statusbar ) { [...] }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module not only stores the complete Padre configuration, it also holds
the functions for loading and saving the configuration.
.PP
The Padre configuration lives in two places:
.IP "a user-editable text file usually called \fIconfig.yml\fR" 4
.IX Item "a user-editable text file usually called config.yml"
.PD 0
.IP "an SQLite database which shouldn't be edited by the user" 4
.IX Item "an SQLite database which shouldn't be edited by the user"
.PD
.SS "Generic usage"
.IX Subsection "Generic usage"
Every setting is accessed by a mutator named after it as follows:
.PP
.Vb 2
\&  # Get the identity of the current user
\&  my $name = $config\->identity_name;
\&  
\&  # Set the identity of the current user
\&  my $changed = $config\->identity_name("John Smith");
.Ve
.SS "Different types of settings"
.IX Subsection "Different types of settings"
Padre needs to store different types of settings, storing them in different
places depending on their impact. \f(CW\*(C`Padre::Config\*(C'\fR allows one to access
them with a unified \s-1API \s0(a mutator).
.PP
Here are the various types of settings that \f(CW\*(C`Padre::Config\*(C'\fR can manage:
.IP "\(bu" 4
User settings
.Sp
Those settings are general settings that relates to user preferences. They range
from general user interface \fIlook & feel\fR (whether to show the line numbers, etc.)
to editor preferences (tab width, etc.) and other personal settings.
.Sp
Those settings are stored in a \s-1YAML\s0 file in your configuration directory (which you
can see in the About dialog)
.IP "\(bu" 4
Host settings
.Sp
Those preferences are related to the host on which Padre is run. The principal
example of those settings is the locatio of the main window appearance, and other
values which could be different between different operating systems and machines.
.Sp
Those settings are stored in a SQLite file.
.IP "\(bu" 4
Project settings
.Sp
Those preferences are related to the project of the file you are currently
editing and allow, in principle, projects to set policies on certain values.
.Sp
Examples of those settings are whether to use tabs or spaces, etc.
.SH "METHODS"
.IX Header "METHODS"
While the vast majority of the methods for this class are mutator front ends,
a number of methods exist which allow you to interact with the config system
more directly.
.SS "settings"
.IX Subsection "settings"
.Vb 1
\&  my @names = Padre::Config\->settings;
.Ve
.PP
Returns the names of all registered settings as a sorted list.
.SS "read"
.IX Subsection "read"
.Vb 1
\&  my $config = Padre::Config\->read;
.Ve
.PP
The \f(CW\*(C`read\*(C'\fR method reads and loads the config singleton for the current instance of Padre
from the various places it is stored, or returns the singleton again if it has already
been loaded.
.PP
Returns a \fBPadre::Config\fR object, or throws an exception if loaded of the configuration
fails.
.SS "meta"
.IX Subsection "meta"
.Vb 1
\&  my $setting = Padre::Config\->meta("identity_name");
.Ve
.PP
The \f(CW\*(C`meta\*(C'\fR method finds the configuration metadata for a named
setting.
.PP
Returns a Padre::Config::Setting object, or throws an exception if the
named setting does not exist.
.SS "default"
.IX Subsection "default"
.Vb 1
\&  my $value = Padre::Config\->default("main_directory_panel");
.Ve
.PP
The \f(CW\*(C`default\*(C'\fR method reports the default value for the setting in the
context of the currently running instance of Padre (some settings may have
different default on different operating systems, for example)
.PP
Returns a value that is legal for the setting type, or throws an exception if
the named setting does not exist.
.SS "changed"
.IX Subsection "changed"
.Vb 1
\&  my $same = ! $config\->changed( "identity_name", "John Smith" );
.Ve
.PP
The \f(CW\*(C`changed\*(C'\fR method takes a named setting and a value for that setting,
and determines if setting that value on the config would result in the
configuration being changed.
.PP
Returns true if the value provided is different to the current setting, or
false if the value provided is the same (or effectively the same) as the
current setting.
.SS "set"
.IX Subsection "set"
.Vb 1
\&  my $changed = $config\->set("identity_name", "John Smith");
.Ve
.PP
The \f(CW\*(C`set\*(C'\fR method takes a named setting and a value and modifies the
configuration object to have that value.
.PP
Changes made to the configuration in this manner will not be reflected in
the running instance, for that you should use the \f(CW\*(C`apply\*(C'\fR method.
.PP
Returns true, or throws an exception on errors such as a non-existant setting
name or an illegal value for that setting type.
.SS "apply"
.IX Subsection "apply"
.Vb 1
\&  my $changed = $config\->apply("main_directory_panel", "right");
.Ve
.PP
The \f(CW\*(C`apply\*(C'\fR method is a higher order version of the \f(CW\*(C`set\*(C'\fR which will set
the configuration value, and then immediately update the running instance of
Padre to reflect the change.
.PP
For example, if the directory panel is open and on the left side of the
display, running the sample code above will change the location preference to
the right side and immediately move the directory panel to the other side of
the \s-1IDE.\s0
.PP
See Padre::Config::Apply for more information on Padre's on-the-fly
configuration change support.
.PP
Returns true if the configuration was changed, false if the value was the
same as the existing configuration value and did not need to be modified,
or throws an exception on errors such as a non-existant setting name or
an illegal value for that setting type.
.SH "ADDING CONFIGURATION OPTIONS"
.IX Header "ADDING CONFIGURATION OPTIONS"
Add a \*(L"\fIsetting()\fR\*(R" \- call to the correct section of this file.
.PP
The \fIsetting()\fR call initially creates the option and defines some
metadata like the type of the option, it's living place and the
default value which should be used until the user configures
a own value.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2008\-2013 The Padre development team as listed in Padre.pm.
.PP
This program is free software; you can redistribute it and/or modify it under the
same terms as Perl 5 itself.