Name

       App::Sqitch::Command::config - Get and set local, user, or system Sqitch options

Synopsis

         my $cmd = App::Sqitch::Command::config->new(\%params);
         $cmd->execute;

Description

       You can query/set/replace/unset Sqitch options with this command. The name is actually the section and
       the key separated by a dot, and the value will be escaped.

Interface

   Class Methods
       "options"

         my @opts = App::Sqitch::Command::config->options;

       Returns a list of Getopt::Long option specifications for the command-line options for the "config"
       command.

       "configure"

         my $params = App::Sqitch::Command::config->configure(
             $config,
             $options,
         );

       Processes the configuration and command options and returns a hash suitable for the constructor. Exits
       with an error on option specification errors.

   Constructor
       "new"

         my $config = App::Sqitch::Command::config->new($params);

       Creates and returns a new "config" command object. The supported parameters include:

       "sqitch"
           The core Sqitch object.

       "file"
           Configuration file to read from and write to.

       "action"
           The action to be executed. May be one of:

           •   "get"

           •   "get-all"

           •   "get-regexp"

           •   "set"

           •   "add"

           •   "replace-all"

           •   "unset"

           •   "unset-all"

           •   "list"

           •   "edit"

           •   "rename-section"

           •   "remove-section"

           If  not specified, the action taken by execute() will depend on the number of arguments passed to it.
           If only one, the action will be "get". If two or more, the action will be "set".

       "context"
           The configuration file context. Must be one of:

           •   "local"

           •   "user"

           •   "system"

       "type"
           The type to cast a value to be set to or fetched as. May be one of:

           •   "bool"

           •   "int"

           •   "num"

           •   "bool-or-int"

           If not specified or "undef", no casting will be performed.

   Instance Methods
       These methods are mainly provided as utilities for the command subclasses to use.

       "execute"

         $config->execute($property, $value);

       Executes the config command. Pass the name of the property and  the  value  to  be  assigned  to  it,  if
       applicable.

       "get"

         $config->get($key);
         $config->get($key, $regex);

       Emits  the  value  for  the  specified key. The optional second argument is a regular expression that the
       value to be returned must match. Exits with an error if the is more than one value for the specified key,
       or if the key does not exist.

       "get_all"

         $config->get_all($key);
         $config->get_all($key, $regex);

       Like get(), but emits all of the values for the given key, rather then exiting with an error  when  there
       is more than one value.

       "get_regex"

         $config->get_regex($key);
         $config->get_regex($key, $regex);

       Like get_all(), but the first parameter is a regular expression that will be matched against all keys.

       "set"

         $config->set($key, $value);
         $config->set($key, $value, $regex);

       Sets the value for a key. Exits with an error if the key already exists and has multiple values.

       "add"

         $config->add($key, $value);

       Adds a value for a key. If the key already exists, the value will be added as an additional value.

       "replace_all"

         $config->replace_all($key, $value);
         $config->replace_all($key, $value, $regex);

       Replace all matching values.

       "unset"

         $config->unset($key);
         $config->unset($key, $regex);

       Unsets  a key. If the optional second argument is passed, the key will be unset only if the value matches
       the regular expression. If the key has multiple values, unset() will exit with an error.

       "unset_all"

         $config->unset_all($key);
         $config->unset_all($key, $regex);

       Like unset(), but will not exit with an error if the key has multiple values.

       "rename_section"

         $config->rename_section($old_name, $new_name);

       Renames a section. Exits with an error if the section does not exist or if either name  is  not  a  valid
       section name.

       "remove_section"

         $config->remove_section($section);

       Removes a section. Exits with an error if the section does not exist.

       "list"

         $config->list;

       Lists  all  of  the values in the configuration. If the context is "local", "user", or "system", only the
       settings set for that context will be emitted.  Otherwise, all settings will be listed.

       "edit"

         $config->edit;

       Opens the context-specific configuration file in a text editor for  direct  editing.  If  no  context  is
       specified, the local config file will be opened. The editor is determined by "editor" in Sqitch.

   Instance Accessors
       "file"

         my $file_name = $config->file;

       Returns  the  path to the configuration file to be acted upon. If the context is "system", then the value
       returned is  "$($etc_prefix)/sqitch.conf".  If  the  context  is  "user",  then  the  value  returned  is
       "~/.sqitch/sqitch.conf".  Otherwise, the default is ./sqitch.conf.

See Also

       sqitch-config
           Help for the "config" command to the Sqitch command-line client.

       sqitch
           The Sqitch command-line client.

Author

       David E. Wheeler <david@justatheory.com>

License

       Copyright (c) 2012-2024 iovation Inc., David E. Wheeler

       Permission  is  hereby  granted,  free  of  charge,  to  any person obtaining a copy of this software and
       associated documentation files (the "Software"), to deal in the Software without  restriction,  including
       without  limitation  the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
       copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to  the
       following conditions:

       The  above  copyright  notice  and  this permission notice shall be included in all copies or substantial
       portions of the Software.

       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  IMPLIED,  INCLUDING  BUT  NOT
       LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
       EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
       IN  AN  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
       THE USE OR OTHER DEALINGS IN THE SOFTWARE.

perl v5.38.2                                       2024-02-08                  App::Sqitch::Command::config(3pm)