Merge pull request #15 from jrha/17.3.0

Add 17.3.0 documentation

Author: jrha

docs/CAF/Application.md

@@ -43,7 +43,7 @@ Applications can extend or overwrite the default methods.
 - version(): string
 
     Returns the version number as defined in $self->{'VERSION'}, or
-    <unknown> if not defined.
+    <unknown> if not defined.
 
 - hostname(): string
 
@@ -53,12 +53,30 @@ Applications can extend or overwrite the default methods.
 
     Returns the name of the user.
 
+- option\_exists($opt): boolean
+
+    Returns true if the option exists, false otherwhise. Option can be
+    defined either in the application configuration file or on the
+    command line (based on `AppConfig` module).
+
 - option($opt): scalar|undef
 
     Returns the option value coming from the command line and/or
     configuration file. Scalar can be a string, or a reference to a hash
     or an array containing the option's value. option() is a wrapper
-    on top of AppConfig->get($opt).
+    on top of AppConfig->get($opt). 
+
+    If the option doesn't exist, returns `undef`, except if the `default`
+    argument has been specified: in this case this value is returned but
+    the option remains undefined.
+
+- set\_option($opt, $val): SUCCESS
+
+    Defines an option and sets its value. If the option was previously
+    defined, its value is overwritten. This is a wrapper over `AppConfig`
+    methods to hide the internal implementation of a `CAF::Application`.
+
+    This method always returns SUCCESS.
 
 - show\_usage(): boolean
 

docs/CAF/FileReader.md

@@ -17,7 +17,7 @@ This class should be used whenever a file is to be opened for reading,
 and no modifications are expected.
 
 Printing to this file is allowed, but changes will be discarded (in
-effect, the [FileWriter](../CAF/FileWriter.md) is `cancel`-ed.
+effect, the [FileEditor](../CAF/FileEditor.md) is `cancel`-ed.
 
 - new
 

docs/CAF/FileWriter.md

@@ -40,7 +40,8 @@ level.
 
 #### Gory details
 
-This is just a wrapper class for `LC::Check::file`
+This is a wrapper class for `IO::String` with customised close based on
+`File::AtomicWrite`.
 
 #### Public methods
 
@@ -73,7 +74,7 @@ This is just a wrapper class for `LC::Check::file`
 
         Path for the backup file, if this one has to be re-written.
 
-    - keeps\_state
+    - `keeps_state`
 
         A boolean specifying whether a file change respects the current system
         state or not. A file with `keeps_state` will be created/modified,
@@ -83,27 +84,42 @@ This is just a wrapper class for `LC::Check::file`
         By default, file changes modify the state and thus `keeps_state` is
         false.
 
+    - `sensitive`
+
+        A boolean specifying whether a file contains sensitive information
+        (like passwords). When the content of the file is modified, the changes
+        (either the diff or the whole content in case of a new file) themself
+        are not reported and not added to the event history.
+
 - open
 
     Synonym for `new()`
 
 - close
 
-    Closes the file. If it has not been saved and it has not been
-    cancelled, it checks its contents and perhaps re-writes it, in a
-    secure way (not following symlinks, etc).
+    Closes the file.
+
+    If the file has been saved (e.g. previous `close` or `cancel`)
+    nothing happens and undef is returned.
+
+    If the file has not been saved,
+    it checks its contents and perhaps re-writes it, in a
+    secure way (not following symlinks, etc). The (re)write only occurs
+    if there was a change in content and this change (or not) is
+    always determined and returned, even if `NoAction` is true
+    (but in that case nothing is (re)written).
 
     Under a verbose level, it will show in the standard output a diff of
     the old and the newly-generated contents for this file before actually
-    saving to disk. This diff will **not** be stored in any logs to prevent
-    any leakages of confidential information (f.i. when writing to
-    `/etc/shadow`).
+    saving to disk.
 
 - cancel
 
     Marks the printed contents as invalid. The existing file will not be
     altered.
 
+    Option `msg` to add custom message to verbose reporting.
+
 - noAction
 
     Returns the NoAction flag value (boolean)
@@ -114,7 +130,7 @@ This is just a wrapper class for `LC::Check::file`
     `""`, so it's now possible to do "$fh" and get the contents of the
     file so far.
 
-- error, warn, info, verbose, debug, report, OK
+- error, warn, info, verbose, debug, report, log, OK
 
     Convenience methods to access the log/reporter instance that might
     be passed during initialisation and set to `*$self-`{LOG}>.
@@ -125,6 +141,9 @@ This is just a wrapper class for `LC::Check::file`
     If it can't be determined from the reporter instance,
     use the global [Reporter](../CAF/Reporter.md) state.
 
+    Supports boolean option `verbose_logfile` to check if
+    reporting to logfile is verbose.
+
 - event
 
     Method to track an event via LOG [History](../CAF/History.md) instance (if any).
@@ -137,6 +156,26 @@ This is just a wrapper class for `LC::Check::file`
 
 #### Private methods
 
+- \_read\_contents
+
+    Read the contents from file `filename` using `LC::File::file_contents`
+    and return it.
+
+    Optional named arguments
+
+    - event
+
+        A hashref that will be updated in place if an error occured. The `error`
+        attribute is set to the exception text.
+
+    - missing\_ok
+
+        When true and `LC::File::file_contents` fails with `ENOENT`
+        (i.e. when `filename` is missing),
+        the exception is ignored and no warning is reported.
+
+    By default, a warning is reported in case of an error and the exception is (re)thrown.
+
 - DESTROY
 
     Class destructor. Closes the file, perhaps saving it to disk.

docs/CAF/Object.md

@@ -79,20 +79,21 @@ In particular, one should avoid to return the `$self` instance at the end of
     Returns the `env` hashref.
 
     To be used as
+
         # Setup local environment
         local %ENV = %ENV;
-        $self->update\_env(\\%ENV);
+        $self->update_env(\%ENV);
 
     Example:
-        # some method\_1 that prepares a shared environment
-        sub method\_1
+
+        # some method_1 that prepares a shared environment
+        sub method_1
         {
             ...
             # Prepare enviroment modifications
             $self->{ENV}->{PATH} = "/some/new/path:$ENV{PATH}";
             ...
         }
-
         sub do_something
         {
            ...

docs/CAF/ObjectText.md

@@ -104,10 +104,10 @@ a [FileWriter](../CAF/FileWriter.md) instance.
 
     All [FileWriter](../CAF/FileWriter.md) initialisation options are supported
     and passed on. (If no `log` option is provided,
-     the one from the current instance is passed).
+    the one from the current instance is passed).
 
     Two new options `header` and `footer` are supported
-     to respectively prepend and append to the text.
+    to respectively prepend and append to the text.
 
     If `eol` was set during initialisation, the header and footer
     will also be checked for EOL.

docs/CAF/Path.md

@@ -23,6 +23,23 @@ undef on failure and store the error message in the `fail` attribute.
     - SUCCESS: nothing changed (boolean true)
     - CHANGED: something changed (boolean true).
 
+#### Functions
+
+- mkcafpath
+
+    Returns an instance of [Object](../CAF/Object.md) and `CAF::Path`.
+    This instance is a simple way to use `CAF::Path` when
+    subclassing is not possible. Allowed options are
+    `<log =` $logger>> and `<NoAction =` $noaction>>.
+
+    This function is not exported, to be used as e.g.
+        use CAF::Path;
+        ...
+        my $cafpath = CAF::Path::mkcafpath(log => $logger);
+        if(! defined($cafpath->directory($name)) {
+            $logger->error("Failed to make directory $name: $cafpath->{fail}");
+        };
+
 #### Methods
 
 - \_get\_noaction
@@ -53,8 +70,10 @@ undef on failure and store the error message in the `fail` attribute.
 
     Run function reference `funcref` with arrayref `argsref` and hashref `optsref`.
 
-    Return and set fail attribute with `failmsg` on die, verbose `msg` on success
-    (resp. $@ and stringified result are appended).
+    Return and set fail attribute with `failmsg` on die or an error (`undef` returned
+    by `funcref`), or print (at verbose level) `msg` on success (respectively $@ and
+    stringified result are appended). Note that `_safe_eval` doesn't work with functions
+    that don't return a defined value when they succeed.
 
     Resets previous exceptions and/or fail attribute
 
@@ -80,7 +99,7 @@ undef on failure and store the error message in the `fail` attribute.
     wrapped in a method to allow unittesting.
 
     If  `directory` is a symlink, the symlink target
-    is tested. If the symlink is broken (no target), 
+    is tested. If the symlink is broken (no target),
     `directory_exists` returns false.
 
 - file\_exists
@@ -91,7 +110,7 @@ undef on failure and store the error message in the `fail` attribute.
     wrapped in a method to allow unittesting.
 
     If  `filename` is a symlink, the symlink target
-    is tested. If the symlink is broken (no target), 
+    is tested. If the symlink is broken (no target),
     `file_exists` returns false.
 
 - any\_exists
@@ -104,6 +123,13 @@ undef on failure and store the error message in the `fail` attribute.
     A broken symlink (symlink whose target doesn't
     exist) exists: `any_exists` returns true.
 
+- is\_symlink
+
+    Test if `path` is a symlink.
+
+    Returns true as long as `path` is a symlink, including when the
+    symlink target doesn't exist.
+
 - cleanup
 
     cleanup removes `dest` with backup support.
@@ -114,7 +140,7 @@ undef on failure and store the error message in the `fail` attribute.
     Returns CHANGED is something was cleaned-up, SUCCESS if nothing was done
     and undef on failure (and sets the fail attribute).
 
-    The &lt;backup> is a suffix for `dest`.
+    The <backup> is a suffix for `dest`.
 
     If backup is undefined, use `backup` attribute.
     (Pass an empty string to disable backup with `backup` attribute defined)
@@ -159,6 +185,76 @@ undef on failure and store the error message in the `fail` attribute.
 
     - keeps\_state: boolean passed to `_get_noaction`.
 
+- \_make\_link
+
+    This method is mainly a wrapper over `LC::Check::link`
+    returning the standard `CAF::Path` return values. Every option
+    supported by `LC::Check::link` is supported. `NoAction`
+    flag is handled by `LC::Check::link` and `keeps_state` option
+    is honored (overrides `NoAction` if true). One important
+    difference is the order of the arguments: `CAF::Path:_make_link`
+    and the methods based on it are following the Perl `symlink`
+    (and `ln` command) argument order.
+
+    This is an internal method, not supposed to be called directly.
+    Either call [symlink](../components/symlink.md) or `hardlink` public methods instead.
+
+- hardlink
+
+    Create a hardlink `link_path` whose target is `target`.
+
+    On failure, returns undef and sets the fail attribute.
+    If `link_path` exists and is a file, it is updated.
+    `target` must exist (`check` flag available in symlink()
+    is ignored for hardlinks) and it must reside in the same
+    filesystem as `link_path`. If `target_path` is a
+    relative path, it is interpreted from the current directory.
+    `link_name` parent directory is created if it doesn't exist.
+
+    Returns SUCCESS on sucess if the hardlink already existed
+    with the same target, CHANGED if the hardlink was created
+    or updated, undef otherwise.
+
+    This method relies on `_make_link` method to do the real work,
+    after enforcing the option saying that it is a hardlink.
+
+- symlink
+
+    Create a symlink `link_path` whose target is `target`.
+
+    Returns undef and sets the fail attribute if `link_path`
+    already exists and is not a symlink, except if this is a file
+    and option `force` is defined and true. If `link_path` exists
+    and is a symlink, it is updated. By default, the target is not
+    required to exist. If you want to ensure that it exists,
+    define option `check` to true. Both `link_path` and `target`
+    can be relative paths: `link_path` is interpreted as relatif
+    to the current directory and `target` is kept relative.
+    `link_path` parent directory is created if it doesn't exist.
+
+    Returns SUCCESS on sucess if the symlink already existed
+    with the same target, CHANGED if the symlink was created
+    or updated, undef otherwise.
+
+    This method relies on `_make_link` method to do the real work,
+    after enforcing the option saying that it is a symlink.
+
+- has\_hardlinks
+
+    Method that returns the number of hardlinks for `file`. The number of
+    hardlinks is the number of entries referring to the inodes minus 1. If
+    `file` has no hardlink, the return value is 0. If `file` is not a file,
+    the return value is `undef`.
+
+- is\_hardlink
+
+    This method returns SUCCESS if `path1` and `path2` refer to the same file (inode).
+    It returns 0 if `path1` and `path2` both exist but are different files or are the same path
+    and `undef` if one of the paths doesn't exist or is not a file.
+
+    Note: the result returned will be identical whatever is the order of `path1` and `path2`
+    arguments.
+
 - status
 
     Set the path stat options: `owner`, `group`, `mode` and/or `mtime`.
@@ -182,7 +278,7 @@ undef on failure and store the error message in the `fail` attribute.
     does not exist to start with, success is immediately returned,
     and no backup of `dest` is created).
 
-    The &lt;backup> is a suffix for the cleanup of `dest`
+    The <backup> is a suffix for the cleanup of `dest`
     (and passed to `cleanup` method).
 
     (The basedir of `dest` is created using `directory` method.)

docs/CAF/Process.md

@@ -81,7 +81,7 @@ secure.
     `noaction_value` is is the value to return with `NoAction`.
 
     `msg` and `postmsg` are used to construct log message
-    `<<msg` command: <COMMAND>\[ &lt;postmsg>\]>>.
+    `<<msg` command: <COMMAND>\[ <postmsg>\]>>.
 
 #### Public methods