__ini_value: add man.rst
This commit is contained in:
parent
10427fde84
commit
72c6306ba2
|
|
@ -0,0 +1,127 @@
|
|||
cdist-type__ini_value(7)
|
||||
========================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-type__ini_value - Handles ini- and conf-style configuration options
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
This cdist type allow changes to more advanced key-value based configurations.
|
||||
Most commonly this would be ini- or conf-style configurations.
|
||||
|
||||
The type can have following states:
|
||||
|
||||
present
|
||||
The line exists with the correct value.
|
||||
|
||||
commented
|
||||
The key-value is outcommented.
|
||||
|
||||
absent
|
||||
The key-value line does not exist in the given section.
|
||||
|
||||
|
||||
REQUIRED PARAMETERS
|
||||
-------------------
|
||||
file
|
||||
The file to modify.
|
||||
|
||||
delimiter
|
||||
The delimiter which seperates each key-value pair.
|
||||
|
||||
|
||||
OPTIONAL PARAMETERS
|
||||
-------------------
|
||||
state
|
||||
One of the states defined in the above section. Defaults to `present`.
|
||||
|
||||
section
|
||||
The section where the value is located at. It always need to be surrounded
|
||||
by square brackets as common for ini files. If not, the section will not be
|
||||
found. If no section is specified, the block before any section is meant.
|
||||
|
||||
key
|
||||
The key to identify the key-value pair. Must be set if the state is not
|
||||
absent.
|
||||
|
||||
value
|
||||
The value assigned to the key. Must be set if the state is not absent.
|
||||
Else, an empty value is assigned to the given key.
|
||||
|
||||
comment
|
||||
The comment which should be placed above the configuration line.
|
||||
|
||||
indentation
|
||||
The indentation the key-value pair should have. Will be applied on inserts,
|
||||
but also be enforced if ``--normalize`` is set.
|
||||
|
||||
comment-sign
|
||||
This declares the comment signs that are valid to use in the configuration
|
||||
file. Each parameter must declare a single character only; multiple
|
||||
parameters are possible. It uses the first specified sign as comment
|
||||
character if this type needs to insert comments.
|
||||
|
||||
|
||||
BOOLEAN PARAMETERS
|
||||
------------------
|
||||
normalize
|
||||
This parameter enforces that the parameter is always pretty in the
|
||||
configuration file. Even if a key-value pair is correct as-is, it will
|
||||
correct the line to be pretty and perfect.
|
||||
|
||||
|
||||
MESSAGES
|
||||
--------
|
||||
The type currently fails to give a correct information of what he did cause of
|
||||
the following construct. It has two `awk` scripts which do the job:
|
||||
|
||||
1. The explorer script which will outputs a single state of the given
|
||||
key-value. Because the current state can contain much more states than the
|
||||
state that should be, one state is returned like `wrongvalue` even if
|
||||
`commented` is correct, too. Therefor, it vanishes the information that the
|
||||
line is commented, too, even this could be a nice information that the
|
||||
messaging system could emit.
|
||||
|
||||
2. The `code-remote` script also goes through the whole file and print out the
|
||||
same file except the line line that should be changed. This is done because
|
||||
it can not be garanteed that an other type already modifed the file, which
|
||||
may moved the key-value to an other position. Then, the script replaces the
|
||||
line which a pretty-printed key-value pair.
|
||||
|
||||
So the detected state is not important for the remote script, as it only needs
|
||||
to know that it must be run cause of differences and what the state should be.
|
||||
So if there are a state like `wrongvalue`, it triggers to correction of the
|
||||
line, but it do not care if it was `wrongvalue`, `wrongformat` or `commented`
|
||||
which trigged the run. Because of this need, the explorer retuns only an
|
||||
easy-to-use value to detect if something needs to be changed.
|
||||
|
||||
Therefor, it is unable to correctly emit messages with the current base.
|
||||
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# set a value in a configuration
|
||||
__ini_value fancy-id --file /etc/foo/bar.ini --section '[welcome]' \
|
||||
--key hi --value baz --delimiter ' = '
|
||||
|
||||
# outcomment a value
|
||||
__ini_value foo --file /etc/bar/foo.conf --state commented \
|
||||
--key noop --value true --delimiter ' = ' --comment 'not this time!'
|
||||
|
||||
|
||||
AUTHORS
|
||||
-------
|
||||
Matthias Stecher <matthiasstecher at gmx.de>
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2021 Matthias Stecher. You can redistribute it
|
||||
and/or modify it under the terms of the GNU General Public License as
|
||||
published by the Free Software Foundation, either version 3 of the
|
||||
License, or (at your option) any later version.
|
||||
Loading…
Reference in New Issue