[vala-extra-vapis] Add transform () to augeas.vapi

[Evan Nemerson <evann src gnome org>]

commit 8fd012233dab18352189a57d6f34e1f54cb9fe56
Author: Alistair Thomas <astavale yahoo co uk>
Date:   Fri Aug 12 22:24:13 2016 +0100

    Add transform () to augeas.vapi
    
    transform() allows individual lens and configuration file combinations to be loaded.
    So InitFlags.NO_MODL_AUTOLOAD can now be used when initializing the library resulting
    in much quicker start up times. Reducing the time from several seconds without the
    flag to a fraction of a second with the flag.
    
    This patch also adds sensible default values for print () and srun () and adds valadoc
    comments for a number of functions.

 augeas.vapi |  131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 126 insertions(+), 5 deletions(-)
---
diff --git a/augeas.vapi b/augeas.vapi
index 618bcbe..2111052 100644
--- a/augeas.vapi
+++ b/augeas.vapi
@@ -20,6 +20,39 @@
  *  Fabian Deutsch <fabian deutsch gmx de>
  */
 
+/**
+ * A configuration file editing tool
+ *
+ * Augeas parses a configuration file in its native format using a "lens" and
+ * transforms it into a tree. Configuration changes are made by manipulating
+ * this tree and saving it back into the native configuration file.
+ *
+ *  * ''Home'': [[http://augeas.net/]]
+ *  * ''C-Documentation'': [[http://augeas.net/docs/references/c_api/files/augeas-h.html]]
+ *
+ * == Loading a Configuration File into the Tree ==
+ *
+ * The following example uses a //hosts// file. A hosts file maps network host
+ * names to Internet Protocol (IP) addresses. For Unix systems this is usually
+ * located at /etc/hosts
+ * {{{
+ * void main () {
+ *    var tree = new Augeas.Tree ();
+ *    tree.transform ("hosts", "/etc/hosts");
+ *    tree.load ();
+ *    tree.print ();
+ * }
+ * }}}
+ * The example creates an instance of Augeas.Tree and then adds a transform to
+ * the tree using the "hosts" lens for the file "/etc/hosts". A tree can
+ * have many transforms. There are also many lenses available for parsing
+ * different types of configuration files. The Augeas website has a list of
+ * [[http://augeas.net/stock_lenses.html|stock lenses]].
+ *
+ * The configuration file is then loaded in to the tree using the specified
+ * lens. The print () call shows how the tree is structured with the
+ * transformed configuration file.
+ */
 [CCode (cheader_filename = "augeas.h")]
 namespace Augeas {
   /**
@@ -94,8 +127,36 @@ namespace Augeas {
   [CCode (cname = "augeas", cprefix = "aug_", free_function = "aug_close")]
   public class Tree {
 
+/**
+ * Initialize the library.
+ *
+ * The Vala binding uses InitFlags.NO_MOD_AUTOLOAD as the default flag to make
+ * a quick initialization of the library. Otherwise the library can take several
+ * seconds to initialize because it will load all lenses and any corresponding
+ * files marked for auto-loading. With InitFlags.NO_MOD_AUTOLOAD
+ * //transform ()// and //load ()// need to be used to identify the lens and
+ * configuration file to load.
+ *
+ * @param root the filesystem root. If ROOT is NULL, use the value
+ * of the environment variable AUGEAS_ROOT.  If that doesn’t exist, use "/".
+ * @param loadpath a colon-separated list of directories that modules should
+ * be searched in.  This is in addition to the standard load path and the
+ * directories in AUGEAS_LENS_LIB
+ * @param flags a bitmask made up of values from InitFlags. The flag
+ * InitFlags.NO_ERR_CLOSE can be used to get more information on why
+ * initialization failed. If it is set in flags, the caller must check that
+ * //error ()// returns ErrorCode.NOERROR before using the returned augeas
+ * handle for any other operation. If the handle reports any error, the caller
+ * should only call the //error// functions and //close ()// on this handle.
+ * @return a handle to the Augeas tree upon success.  If initialization fails,
+ * returns NULL if InitFlags.NO_ERR_CLOSE is not set in //flags//.  If
+ * InitFlags.NO_ERR_CLOSE is set, might return an Augeas handle even on
+ * failure. In that case, caller must check for errors using //error ()//, and,
+ * if an error is reported, only use the handle with the //error// functions
+ * and //close ()//.
+ */
     [CCode (cname = "aug_init")]
-    public Tree (string? root = null, string? loadpath = null, InitFlags flags = InitFlags.NONE);
+    public Tree (string? root = null, string? loadpath = null, InitFlags flags = InitFlags.NO_MODL_AUTOLOAD);
 
     public int defvar (string name, string? expr);
     public int defnode (string name, string expr, string val, out int created);
@@ -121,18 +182,78 @@ namespace Augeas {
     }
 
     public int save ();
+
+/**
+ * Load files into the tree.
+ *
+ * Which files to load and which lenses to use on them is specified under
+ * /augeas/load in the tree. Each entry /augeas/load/NAME specifies a
+ * "transform", having exactly one child "lens" and any number of children
+ * labelled //incl// and //excl//. The value of NAME has no meaning.
+ *
+ * The //lens// grandchild of /augeas/load specifies which lens to use, and can
+ * either be the fully qualified name of a lens 'module.lns' or 'module'.
+ * The latter form means that the lens from the transform marked for
+ * autoloading in MODULE should be used.
+ *
+ * The //incl// and //excl// grandchildren of /augeas/load indicate which files
+ * to transform. Their value are used as glob patterns. Any file that matches
+ * at least one 'incl' pattern and no 'excl' pattern is transformed. The order
+ * of //incl// and //excl// entries is irrelevant.
+ *
+ * Before loading any files, //load ()// will remove everything underneath
+ * /augeas/files and /files, regardless of whether any entries have been
+ * modified or not.
+ *
+ * @return 0 on success, -1 on error.  Note that success includes the case
+ * where some files could not be loaded. Details of such files can be found
+ * under /augeas/ /error
+ */
     public int load ();
 #if POSIX
-    public int print (Posix.FILE fout, string path);
-    public int srun (Posix.FILE fout, string path);
+    public int print (string path = "/*", [CCode (pos = 0.5)] Posix.FILE output = Posix.stdout);
+    public int srun (string command = "help", [CCode (pos = 0.5)] Posix.FILE output = Posix.stdout);
 #else
-    public int print (GLib.FileStream fout, string path);
-    public int srun (GLib.FileStream fout, string path);
+
+/**
+ * Print each node matching //path// and its descendants to //output//.
+ *
+ * @param path path expression, default is all nodes "/*"
+ * @param output file to send output to, default is STDOUT
+ * @return 0 on success, or a negative value on failure
+ */
+    public int print (string path = "/*", [CCode (pos = 0.5)] GLib.FileStream output = GLib.stdout);
+
+/**
+ * Run one or more newline separated commands.
+ *
+ * The output of the commands will be printed to //output//.  Running just 'help'
+ * will print the available commands.  Commands accepted by this are identical
+ * to those augtool accepts.
+ * @param command one or more newline separated commands, default is 'help'
+ * @param output file to send output to, default is STDOUT
+ * @return the number of executed commands on success, -1 on failure, and -2
+ * if a 'quit' command was encountered
+ */
+    public int srun (string command = "help", [CCode (pos = 0.5)] GLib.FileStream output = GLib.stdout);
+
 #endif
     public void close ();
 
     public int to_xml (string path, out Xml.Node doc, uint flags = 0);
 
+/**
+ * Add a transform using //lens// for //file//.
+ *
+ * //excl// specifies if the file is to be included (0) or excluded (1) from
+ * the lens.  The lens may be a module name or a full lens name.  If a module
+ * name is given, then lns will be the lens assumed.
+ * @param lens lens name
+ * @param file file to transform
+ * @param excl include file if 0, exclude file if 1
+ * @return 1 on success, -1 on failure
+ */
+    public int transform (string lens, string file, int excl = 0);
     public ErrorCode error ();
     public string error_message ();
     public string error_minor_message ();