-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Haskell FFI wrapper for the Augeas API
--   
--   A Haskell FFI wrapper for the Augeas API
@package augeas
@version 0.6.1


-- | This module provides FFI bindings for the Augeas API
--   (<a>http://augeas.net/docs/api.html</a>).
--   
--   <i>Note aug_close is not surfaced in the API because because the
--   ForeignPtr returned by</i> <i>aug_init uses aug_close as its
--   finializer.</i>
module System.Augeas

-- | A pointer to the Augeas tree structure Not using a typed pointer (as
--   per RWH p416) because of the compiler warning
type Augeas = ()
newtype AugFlag
AugFlag :: CInt -> AugFlag
unAugFlag :: AugFlag -> CInt
none :: AugFlag
save_backup :: AugFlag
save_newfile :: AugFlag
type_check :: AugFlag
no_stdinc :: AugFlag
save_noop :: AugFlag
no_load :: AugFlag
no_modl_autoload :: AugFlag
enable_span :: AugFlag

-- | The possible <a>aug_get</a> return values.
data AugMatch

-- | Exactly one match was found.
exactly_one :: AugMatch

-- | No matches were found
no_match :: AugMatch

-- | Either an invalid paths, or multiple matches were found.
invalid_match :: AugMatch

-- | The possible return values for the <a>aug_set</a>, <a>aug_insert</a>,
--   <a>aug_mv</a>, <a>aug_save</a>, and <a>aug_print</a> functions
newtype AugRet
AugRet :: CInt -> AugRet

-- | The function worked as expected
success :: AugRet
one :: AugRet

-- | The function failed
error :: AugRet

-- | The possible BEFORE values fro the aug_insert function
newtype AugBefore
AugBefore :: CInt -> AugBefore

-- | Insert the LABEL just before the PATH
just_before :: AugBefore

-- | Insert the LABEL just after the PATH
just_after :: AugBefore
newtype AugErrCode
AugErrCode :: CInt -> AugErrCode
unAugErrCode :: AugErrCode -> CInt
no_error :: AugErrCode
err_no_memory :: AugErrCode
err_internal :: AugErrCode
err_bad_path :: AugErrCode
err_no_match :: AugErrCode
err_multi_matches :: AugErrCode
err_syntax :: AugErrCode
err_no_lens :: AugErrCode
err_multi_xfm :: AugErrCode
err_no_span :: AugErrCode
err_mv_desc :: AugErrCode
err_cmd_run :: AugErrCode

-- | Initialize the library.
--   
--   Use ROOT as the filesystem root. If ROOT is NULL, use the value of the
--   environment variable AUGEAS_ROOT. If that doesn't exist either, use
--   "/".
--   
--   LOADPATH is a colon-spearated 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
--   
--   FLAGS is a list of AugFlags
--   
--   Return a ForeignPtr to the Augeas tree upon success. If initialization
--   fails, returns Nothing.
--   
--   <i>Note that the ForeignPtr returned by the function is using
--   aug_close as a finializer,</i> <i>so aug_close is called automatically
--   when the Augeas pointer goes out of scope.</i>
--   
--   <i>Therefore, there is no need to surface aug_close in the
--   library.</i>
aug_init :: ByteString -> ByteString -> [AugFlag] -> IO (Maybe (ForeignPtr Augeas))

-- | Function: aug_defvar
--   
--   Define a variable NAME whose value is the result of evaluating EXPR.
--   If a variable NAME already exists, its name will be replaced with the
--   result of evaluating EXPR. Context will not be applied to EXPR.
--   
--   If (Maybe EXPR) is Nothing, the variable NAME will be removed if it is
--   defined.
--   
--   Path variables can be used in path expressions later on by prefixing
--   them with <a>$</a>.
--   
--   Returns -1 on error; on success, returns 0 if EXPR evaluates to
--   anything other than a nodeset, and the number of nodes if EXPR
--   evaluates to a nodeset
aug_defvar :: Ptr Augeas -> ByteString -> (Maybe ByteString) -> IO (AugRet)

-- | Function: aug_defnode
--   
--   Define a variable NAME whose value is the result of evaluating EXPR,
--   which must be non-NULL and evaluate to a nodeset. If a variable NAME
--   already exists, its name will be replaced with the result of
--   evaluating EXPR.
--   
--   If EXPR evaluates to an empty nodeset, a node is created, equivalent
--   to calling AUG_SET(AUG, EXPR, VALUE) and NAME will be the nodeset
--   containing that single node.
--   
--   If CREATED is non-NULL, it is set to 1 if a node was created, and 0 if
--   it already existed.
--   
--   Returns -1 on error; on success, returns the number of nodes in the
--   nodeset
aug_defnode :: Ptr Augeas -> ByteString -> ByteString -> ByteString -> IO (AugRet, Maybe Bool)

-- | Lookup the value associated with PATH. VALUE can be NULL, in which
--   case it is ignored. If VALUE is not NULL, it is used to return a
--   pointer to the value associated with PATH if PATH matches exactly one
--   node. If PATH matches no nodes or more than one node, *VALUE is set to
--   NULL. Note that it is perfectly legal for nodes to have a NULL value,
--   and that that by itself does not indicate an error.
--   
--   Return AugMatch.exactly_one if there is exactly one node matching
--   PATH, AugMatch.no_match if there is none, and AugMatch.invalid_match
--   if there is more than one node matching PATH, or if PATH is not a
--   legal path expression.
aug_get :: Ptr Augeas -> ByteString -> IO (Either AugMatch (Maybe String))

-- | Set the value associated with PATH to VALUE. VALUE is copied into the
--   internal data structure. Intermediate entries are created if they
--   don't exist.
--   
--   Return AugRet.success on success, AugRet.error on error. It is an
--   error if more than one node matches PATH.
aug_set :: Ptr Augeas -> ByteString -> ByteString -> IO (AugRet)

-- | Set the value of multiple nodes in one operation. Find or create a
--   node matching SUB by interpreting SUB as a path expression relative to
--   each node matching BASE. SUB may be NULL, in which case all the nodes
--   matching BASE will be modified.
--   
--   Returns: number of modified nodes on success, -1 on error
aug_setm :: Ptr Augeas -> ByteString -> (Maybe ByteString) -> ByteString -> IO (AugRet)

-- | Function: aug_span
--   
--   Get the span according to input file of the node associated with PATH.
--   If the node is associated with a file, the filename, label and value
--   start and end positions are set, and return value is 0. The caller is
--   responsible for freeing returned filename. If an argument for return
--   value is NULL, then the corresponding value is not set. If the node
--   associated with PATH doesn't belong to a file or is doesn't exists,
--   filename and span are not set and return value is Nothing.
--   
--   Returns: on success Just (filename, label_start, label_stop,
--   value_start, value_end, start_span, end_span) on error Nothing
aug_span :: Ptr Augeas -> ByteString -> IO (Maybe (String, CInt, CInt, CInt, CInt, CInt, CInt))

-- | Create a new sibling LABEL for PATH by inserting into the tree just
--   before PATH if BEFORE == just_before or just after PATH if BEFORE ==
--   just_after.
--   
--   PATH must match exactly one existing node in the tree, and LABEL must
--   be a label, i.e. not contain a <a>/</a>, <a>*</a> or end with a
--   bracketed index '[N]'.
--   
--   Return AugRet.success on success, and AugRet.error if the insertion
--   fails.
aug_insert :: Ptr Augeas -> ByteString -> ByteString -> AugBefore -> IO (AugRet)

-- | Remove path and all its children. Returns the number of entries
--   removed. All nodes that match PATH, and their descendants, are
--   removed.
aug_rm :: Ptr Augeas -> ByteString -> IO (CInt)

-- | Move the node SRC to DST. SRC must match exactly one node in the tree.
--   DST must either match exactly one node in the tree, or may not exist
--   yet. If DST exists already, it and all its descendants are deleted. If
--   DST does not exist yet, it and all its missing ancestors are created.
--   
--   Note that the node SRC always becomes the node DST: when you move /a/b
--   to /x, the node /a/b is now called /x, no matter whether /x existed
--   initially or not.
--   
--   Return AugRet.success on success and AugRet.error on failure.
aug_mv :: Ptr Augeas -> ByteString -> ByteString -> IO (AugRet)

-- | Return the number of matches of the path expression PATH in AUG. If
--   MATCHES is non-NULL, an array with the returned number of elements
--   will be allocated and filled with the paths of the matches. The caller
--   must free both the array and the entries in it. The returned paths are
--   sufficiently qualified to make sure that they match exactly one node
--   in the current tree.
--   
--   If MATCHES is NULL, nothing is allocated and only the number of
--   matches is returned.
--   
--   Returns -1 on error, or the total number of matches (which might be
--   0).
--   
--   Path expressions use a very simple subset of XPath: the path PATH
--   consists of a number of segments, separated by <a>/</a>; each segment
--   can either be a <a>*</a>, matching any tree node, or a string,
--   optionally followed by an index in brackets, matching tree nodes
--   labelled with exactly that string. If no index is specified, the
--   expression matches all nodes with that label; the index can be a
--   positive number N, which matches exactly the Nth node with that label
--   (counting from 1), or the special expression 'last()' which matches
--   the last node with the given label. All matches are done in fixed
--   positions in the tree, and nothing matches more than one path segment.
aug_match :: Ptr Augeas -> ByteString -> IO (Int, Maybe [String])

-- | Write all pending changes to disk.
--   
--   Return AugRet.error if an error is encountered, AugRet.success on
--   success. Only files that had any changes made to them are written.
--   
--   If AUG_SAVE_NEWFILE is set in the FLAGS passed to AUG_INIT, create
--   changed files as new files with the extension <a>.augnew</a>, and
--   leave the original file unmodified.
--   
--   Otherwise, if AUG_SAVE_BACKUP is set in the FLAGS passed to AUG_INIT,
--   move the original file to a new file with extension <a>.augsave</a>.
--   
--   If neither of these flags is set, overwrite the original file.
aug_save :: Ptr Augeas -> IO (AugRet)

-- | Function: aug_load
--   
--   Load files into the tree. Which files to load and what lenses to use
--   on them is specified under <i>augeas</i>load in the tree; each entry
--   <i>augeas</i>load/NAME specifies a <tt>transform</tt>, by having
--   itself exactly one child <tt>lens</tt> and any number of children
--   labelled <tt>incl</tt> and <tt>excl</tt>. The value of NAME has no
--   meaning.
--   
--   The <tt>lens</tt> grandchild of <i>augeas</i>load specifies which lens
--   to use, and can either be the fully qualified name of a lens
--   <a>lens</a> or '@Module'. The latter form means that the lens from the
--   transform marked for autoloading in MODULE should be used.
--   
--   The <tt>incl</tt> and <tt>excl</tt> grandchildren of <i>augeas</i>load
--   indicate which files to transform. Their value are used as glob
--   patterns. Any file that matches at least one <tt>incl</tt> pattern and
--   no <tt>excl</tt> pattern is transformed. The order of <tt>incl</tt>
--   and <tt>excl</tt> entries is irrelevant.
--   
--   When AUG_INIT is first called, it populates <i>augeas</i>load with the
--   transforms marked for autoloading in all the modules it finds.
--   
--   Before loading any files, AUG_LOAD will remove everything underneath
--   <i>augeas</i>files and /files, regardless of whether any entries have
--   been modified or not.
--   
--   Returns -1 on error, 0 on success. Note that success includes the case
--   where some files could not be loaded. Details of such files can be
--   found as '/augeas//error'.
aug_load :: Ptr Augeas -> IO (AugRet)

-- | Print each node matching PATH and its descendants to OUT. Return
--   AugRet.success on success, or AugRet.error on failure
aug_print :: Ptr Augeas -> Handle -> ByteString -> IO (AugRet)

-- | Function: aug_srun
--   
--   Run one or more newline-separated commands. The output of the commands
--   will be printed to OUT. Running just <tt>help</tt> will print what
--   commands are available. Commands accepted by this are identical to
--   what augtool accepts.
--   
--   Returns: the number of executed commands on success, -1 on failure,
--   and -2 if a <tt>quit</tt> command was encountered
aug_srun :: Ptr Augeas -> Handle -> ByteString -> IO (AugRet)

-- | Return a human-readable message for the error code */
aug_error :: Ptr Augeas -> IO (AugErrCode)

-- | Return a human-readable message for the error code */
aug_error_message :: Ptr Augeas -> IO (ByteString)

-- | Return a human-readable message elaborating the error code; might be
--   NULL. For example, when the error code is AUG_EPATHX, this will
--   explain how the path expression is invalid */
aug_error_minor_message :: Ptr Augeas -> IO (ByteString)

-- | Return details about the error, which might be NULL. For example, for
--   AUG_EPATHX, indicates where in the path expression the error occurred.
--   The returned value can only be used until the next API call
aug_error_details :: Ptr Augeas -> IO (ByteString)

-- | Function: aug_to_xml
--   
--   Turn the Augeas tree(s) matching PATH into an XML tree XMLDOC. The
--   parameter FLAGS is currently unused and must be set to 0.
--   
--   Returns: 0 on success, or a negative value on failure
--   
--   In case of failure, *xmldoc is set to Nothing
aug_to_xml :: Ptr Augeas -> ByteString -> [AugFlag] -> IO (AugRet, Maybe (Ptr AugeasXmlNode))
instance Eq AugMatch
instance Show AugMatch
instance Eq AugRet
instance Show AugRet
instance Eq AugBefore
instance Show AugBefore
