NAME

       Padre::Config - Configuration subsystem for Padre

SYNOPSIS

           use Padre::Config;
           [...]
           if ( Padre::Config->main_statusbar ) { [...] }

DESCRIPTION

       This module not only stores the complete Padre configuration, it also holds the functions
       for loading and saving the configuration.

       The Padre configuration lives in two places:

       a user-editable text file usually called config.yml
       an SQLite database which shouldn't be edited by the user

   Generic usage
       Every setting is accessed by a mutator named after it as follows:

         # 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");

   Different types of settings
       Padre needs to store different types of settings, storing them in different places
       depending on their impact. "Padre::Config" allows one to access them with a unified API (a
       mutator).

       Here are the various types of settings that "Padre::Config" can manage:

       •   User settings

           Those settings are general settings that relates to user preferences. They range from
           general user interface look & feel (whether to show the line numbers, etc.)  to editor
           preferences (tab width, etc.) and other personal settings.

           Those settings are stored in a YAML file in your configuration directory (which you
           can see in the About dialog)

       •   Host settings

           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.

           Those settings are stored in a SQLite file.

       •   Project settings

           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.

           Examples of those settings are whether to use tabs or spaces, etc.

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.

   settings
         my @names = Padre::Config->settings;

       Returns the names of all registered settings as a sorted list.

   read
         my $config = Padre::Config->read;

       The "read" 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.

       Returns a Padre::Config object, or throws an exception if loaded of the configuration
       fails.

   meta
         my $setting = Padre::Config->meta("identity_name");

       The "meta" method finds the configuration metadata for a named setting.

       Returns a Padre::Config::Setting object, or throws an exception if the named setting does
       not exist.

   default
         my $value = Padre::Config->default("main_directory_panel");

       The "default" 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)

       Returns a value that is legal for the setting type, or throws an exception if the named
       setting does not exist.

   changed
         my $same = ! $config->changed( "identity_name", "John Smith" );

       The "changed" 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.

       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.

   set
         my $changed = $config->set("identity_name", "John Smith");

       The "set" method takes a named setting and a value and modifies the configuration object
       to have that value.

       Changes made to the configuration in this manner will not be reflected in the running
       instance, for that you should use the "apply" method.

       Returns true, or throws an exception on errors such as a non-existant setting name or an
       illegal value for that setting type.

   apply
         my $changed = $config->apply("main_directory_panel", "right");

       The "apply" method is a higher order version of the "set" which will set the configuration
       value, and then immediately update the running instance of Padre to reflect the change.

       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 IDE.

       See Padre::Config::Apply for more information on Padre's on-the-fly configuration change
       support.

       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.

ADDING CONFIGURATION OPTIONS

       Add a "setting()" - call to the correct section of this file.

       The setting() 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.

COPYRIGHT & LICENSE

       Copyright 2008-2013 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl 5 itself.