Merge pull request #16 from jrha/17.7.0

Add 17.7.0 documentation

Author: jrha

docs/CAF/Application.md

@@ -64,7 +64,7 @@ Applications can extend or overwrite the default methods.
     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

docs/CAF/FileWriter.md

@@ -130,6 +130,8 @@ This is a wrapper class for `IO::String` with customised close based on
     `""`, so it's now possible to do "$fh" and get the contents of the
     file so far.
 
+    (Returns empty string on an already closed file.)
+
 - error, warn, info, verbose, debug, report, log, OK
 
     Convenience methods to access the log/reporter instance that might

docs/CAF/Path.md

@@ -87,7 +87,7 @@ undef on failure and store the error message in the `fail` attribute.
 
 - \_untaint\_path
 
-    Untaint the `path` argument.
+    Untaint the [path](../components/path.md) argument.
 
     Returns undef on failure and sets the fail attribute with `msg`
 
@@ -115,7 +115,7 @@ undef on failure and store the error message in the `fail` attribute.
 
 - any\_exists
 
-    Test if `path` exists.
+    Test if [path](../components/path.md) exists.
 
     This is basically the perl builtin `-e || -l`,
     wrapped in a method to allow unittesting.
@@ -125,9 +125,9 @@ undef on failure and store the error message in the `fail` attribute.
 
 - is\_symlink
 
-    Test if `path` is a symlink.
+    Test if [path](../components/path.md) is a symlink.
 
-    Returns true as long as `path` is a symlink, including when the
+    Returns true as long as [path](../components/path.md) is a symlink, including when the
     symlink target doesn't exist.
 
 - cleanup
@@ -286,3 +286,48 @@ undef on failure and store the error message in the `fail` attribute.
     Additional options
 
     - keeps\_state: boolean passed to `_get_noaction`.
+
+- listdir
+
+    Return an arrayref of sorted directory entry names or undef on failure.
+    (The `.` and `..` are removed).
+
+    Can be used to replace `glob()` as follows:
+
+        ...
+        foreach my $file (glob('/path/*.ext')) {
+        ...
+
+        replace by
+
+        ...
+        foreach my $file (@{$self->listdir('/path', filter => '\.ext$', adddir => 1)}) {
+        ...
+
+    Options
+
+    - test
+
+        An (anonymous) sub used for testing.
+        The return value is interpreted as boolean value for filtering the
+        directory entry names (true value means the name is kept).
+
+        Accepts 2 arguments: first argument (`$_[0]`) the directory entry name,
+        2nd argument (`$_[1]`) the directory.
+
+    - filter
+
+        A pattern or compiled pattern to filter directory entry names.
+        Matching names are kept.
+
+    - inverse
+
+        Apply inverse test (or filter) logic.
+
+    - adddir
+
+        Prefix the directory to the returned filenames (default false).
+
+    - file\_exists
+
+        Shortcut for test function that uses `CAF::Path::file_exists` as test function.

docs/CCM/Path.md

@@ -23,10 +23,10 @@ to manipulate absolute paths
 
     Create new `EDG::WP4::CCM::Path` instance.
 
-    If `path` argument is not specified, root path (`/`) is used.
+    If [path](../components/path.md) argument is not specified, root path (`/`) is used.
     Empty string is not allowed as an argument.
 
-    `path` is a string representation of the path as defined in the NVA-API
+    [path](../components/path.md) is a string representation of the path as defined in the NVA-API
     Specification document.
 
 - depth
@@ -121,7 +121,7 @@ to manipulate absolute paths
 
 - \_safe\_unescape
 
-    Given `path` and `subpath`, test is `path` is in `@safe_unescape`
+    Given [path](../components/path.md) and `subpath`, test is [path](../components/path.md) is in `@safe_unescape`
     and if it is, return unescaped subpath enclosed in `{}` (or not enclosed if
     `strip_unescape` is true).
 

docs/Unittesting/Quattor.md

@@ -191,11 +191,11 @@ automatically:
 
 - is\_symlink
 
-    Test if given `path` is a mocked symlink
+    Test if given [path](../components/path.md) is a mocked symlink
 
 - has\_hardlinks
 
-    Test if given `path` is a mocked hardlink
+    Test if given [path](../components/path.md) is a mocked hardlink
 
     Note that it is not a perfect replacement for the c<CAF::Path> `has_hardlinks` because
     the current implementation of mocked hardlinks does not allow to mimic multiple references
@@ -341,7 +341,7 @@ The following functions are exported by default:
 
 - set\_immutable
 
-    Make `path` immutable. Pass a false `bool` to make the path mutable again
+    Make [path](../components/path.md) immutable. Pass a false `bool` to make the path mutable again
     (not <undef>, default is to make the path immutable).
 
 - is\_mutable
@@ -368,7 +368,7 @@ The following functions are exported by default:
     Test if given `$path` is a mocked directory
 
 - is\_any
-Test if given `path` is known (as file or directory or anything else)
+Test if given [path](../components/path.md) is known (as file or directory or anything else)
 - make\_directory
 
     Add a directory to the mocked directories.
@@ -380,7 +380,7 @@ Test if given `path` is known (as file or directory or anything else)
 
 - remove\_any
 
-    Recursive removal of a `path` from the files\_contents / desired\_file\_contents
+    Recursive removal of a [path](../components/path.md) from the files\_contents / desired\_file\_contents
 
 - move
 

docs/components-grid/condorconfig.md

@@ -1,16 +1,16 @@
 
 ### NAME
 
-The _condorconfig_ component manages the configuration file of 
-Condor.  
+The _condorconfig_ component manages the configuration file of
+Condor.
 
 ### DESCRIPTION
 
 The _condorconfig_ component manages the configuration file (default
 is `/opt/condor/etc/condor.conf`) for Condor.  All of the condor
 parameters are available with exactly the same name in Quattor.  See
 the condor documentation for the names and descriptions of the
-parameters. 
+parameters.
 
 ### RESOURCES
 

docs/components-grid/dpmlfc.md

@@ -5,14 +5,14 @@ ncm-dpmlfc : NCM component to manage DPM and LFC configuration.
 
 ### DESCRIPTION
 
-This component allows to manage configuration of DPM and LFC services, with the exception of DPM xrootd protocol which is managed by 
+This component allows to manage configuration of DPM and LFC services, with the exception of DPM xrootd protocol which is managed by
 the [xrootd](../components-grid/xrootd.md) configuration module.
 
-Configuration module **ncm-dpmlfc** requires that the DPM and/or LFC configuration describes all nodes participating to the service and their respective 
+Configuration module **ncm-dpmlfc** requires that the DPM and/or LFC configuration describes all nodes participating to the service and their respective
 role (in term of daemon running on each node). Each daemon/host combination is called a daemon instance in this documentation.
 
-Using the whole DPM and/or LFC description, **ncm-dpmlfc** takes care of action needed on every node to configure it as requested 
-(you MUST use the same configuration description on every node participating to DPM and/or LFC). This includes restarting 
+Using the whole DPM and/or LFC description, **ncm-dpmlfc** takes care of action needed on every node to configure it as requested
+(you MUST use the same configuration description on every node participating to DPM and/or LFC). This includes restarting
 a service after configuration changes if needed.
 
 There are 2 sets of configuration options:
@@ -49,31 +49,31 @@ DPM and LFC accept the same global options but there is a separate set for each
 
 - `/software/components/dpmlfc/options/PRODUCT/gridmapfile`
 
-    This option defines the local gridmap file used by products daemons. 
+    This option defines the local gridmap file used by products daemons.
 
     Default: None (default configuration provided by RPM will be used)
 
 - `/software/components/dpmlfc/options/PRODUCT/gridmapdir`
 
-    This option defines the gridmap dir used by products daemons. 
+    This option defines the gridmap dir used by products daemons.
 
     Default: None (default configuration provided by RPM will be used)
 
 - `/software/components/dpmlfc/options/PRODUCT/group`
 
-    This option defines the userid used by product daemons. 
+    This option defines the userid used by product daemons.
 
     Default: None (default configuration provided by RPM will be used)
 
 - `/software/components/dpmlfc/options/PRODUCT/user`
 
-    This option defines the userid used by product daemons. 
+    This option defines the userid used by product daemons.
 
     Default: dpmmgr for DPM, lfcmgr for LFC
 
 ### DATABASE CONNECTION OPTIONS (DPM and LFC)
 
-DPM and LFC accepts the same set of options to describe the database connection. In the following option names, 
+DPM and LFC accepts the same set of options to describe the database connection. In the following option names,
 replace `PRODUCT` by either `dpm` or `lfc`. Both sets can coexist.
 
 - `/software/components/dpmlfc/options/PRODUCT/db/configfile`
@@ -113,8 +113,8 @@ replace `PRODUCT` by either `dpm` or `lfc`. Both sets can coexist.
 - `/software/components/dpmlfc/options/PRODUCT/db/server` (string, optional)
 
     This option defines the server running the database. This component checks that
-    DPM and LFC database server run on different node (DPNS and LFC use the same database name). 
-    `localhost` is considered different as DPNS and LFC are not allowed to run on the same node. 
+    DPM and LFC database server run on different node (DPNS and LFC use the same database name).
+    `localhost` is considered different as DPNS and LFC are not allowed to run on the same node.
 
     Default : localhost.
 

docs/components-grid/gip2.md

@@ -58,12 +58,12 @@ Default : none.
 
 ### LDIF entries : nlist (optional)
 
-nlist of LDIF entries (key is the DN, value is a nlist of attribute/value pairs) to put in the resulting file 
+nlist of LDIF entries (key is the DN, value is a nlist of attribute/value pairs) to put in the resulting file
 if staticInfoCmd is not specified or sets of key value/pairs (key is the set name and and value is a nlist of key/value pairs).
 
 Key is interpreted as an escaped value.
 
-If ommitted and confFile is defined, must be defined in `/software/components/gip2/ldifConfEntries` 
+If ommitted and confFile is defined, must be defined in `/software/components/gip2/ldifConfEntries`
 key matching confFile.
 
 Default : none.
@@ -100,7 +100,7 @@ Default : none.
 
 #### `/software/components/gip2/staticInfoCmd` : string (optional)
 
-Path of the command to execute to transform entries into a LDIF file if none is defined in the 
+Path of the command to execute to transform entries into a LDIF file if none is defined in the
 `/software/components/gip2/ldif` entry. It is here for backward compatibility but it is recommended
 to define it as part of the ldif entries. If undefined in both locations, the configuration file
 is read directly without any processing.

docs/components-grid/glitestartup.md

@@ -68,14 +68,14 @@ List of paths where to look for a script matching service name.
 
 Default : `/opt/glite/etc/init.d`
 
-#### `/software/components`/@COMP/services : nlist of string 
+#### `/software/components`/@COMP/services : nlist of string
 
 Nlist with one entry per service to start. Key is the service name,
 value is an optional nlist. This nlist can contain the following element:
 
 - args startup script arguments
 
-Default : none 
+Default : none
 
 ### DEPENDENCIES
 

docs/components-grid/glitestartup::schema.md

@@ -5,7 +5,7 @@
     - `/software/glitestartup/glitestartup_component_service/args`
         - Optional
         - Type: string
-        - Default value: 
+        - Default value:
  - `/software/glitestartup/glitestartup_component_post_restart`
     - `/software/glitestartup/glitestartup_component_post_restart/cmd`
         - Optional