view release on metacpan or  search on metacpan

lib/sqitch-config.pod  view on Meta::CPAN

=head1 Name

sqitch-config - Get and set local, user, or system Sqitch options

=head1 Synopsis

  sqitch config [<file-option>] [type] name [value [value_regex]]
  sqitch config [<file-option>] [type] --add name value
  sqitch config [<file-option>] [type] --replace-all name value [value_regex]
  sqitch config [<file-option>] [type] --get name [value_regex]
  sqitch config [<file-option>] [type] --get-all name [value_regex]
  sqitch config [<file-option>] [type] --get-regexp name_regex [value_regex]
  sqitch config [<file-option>] --unset name [value_regex]
  sqitch config [<file-option>] --unset-all name [value_regex]
  sqitch config [<file-option>] --rename-section old_name new_name
  sqitch config [<file-option>] --remove-section name
  sqitch config [<file-option>] -l | --list
  sqitch config [<file-option>] -e | --edit

=head1 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.

Multiple lines can be added to an option by using the C<--add> option. If you
want to update or unset an option which can occur on multiple lines, a Perl
regular expression C<value_regex> needs to be given. Only the existing values
that match the regex will be updated or unset. If you want to handle lines
that do not match the regex, just prepend a single C<!> (exclamation point) in
front (see L<Examples>).

The C<type> specifier can be C<--int>, C<--num>, or C<--bool>, to ensure that
the variable(s) are of the given type and convert the value to the canonical
form (simple integer for C<--int>, decimal number for C<--num>, a "true" or
"false" string for C<--bool>) If no type specifier is passed, no checks or
transformations are performed on the value.

The C<file-option> can be one of C<--local>, C<--user>, C<--system>, or
C<--file>, which specify where the values will be read from or written to. The
default is to assume the local config file in the current project directory,
for editing, and the all files merged for fetching (see L</Files>).

=begin comment

XXX Need to implmenent these.

This command will fail (with exit code ret) if:

=over

=item 1.

The config file is invalid (ret=3)

=item 2.

Cannot write to the config file (ret=4)

=item 3.

No section or name was provided (ret=2)

=item 4.

The section or key is invalid (ret=1)

=item 5.

You try to unset an option which does not exist (ret=5)

=item 6.

You try to unset/set an option for which multiple lines match (ret=5)

=item 7.

You try to use an invalid regexp (ret=6)

=item 8.

You use C<--user> option without C<$HOME> being properly set (ret=128)

=back

=end comment

On success, the command returns the exit code 0.