-- 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
--   (http://augeas.net/docs/api.html).
--   
--   Note aug_close is not surfaced in the API because because the
--   ForeignPtr returned by aug_init uses aug_close as its
--   finializer.
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 aug_get 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 aug_set, aug_insert,
--   aug_mv, aug_save, and aug_print 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.
--   
--   Note that the ForeignPtr returned by the function is using
--   aug_close as a finializer, so aug_close is called automatically
--   when the Augeas pointer goes out of scope.
--   
--   Therefore, there is no need to surface aug_close in the
--   library.
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 $.
--   
--   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 /, * 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 /; each segment
--   can either be 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 .augnew, 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 .augsave.
--   
--   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 augeasload in the tree; each entry
--   augeasload/NAME specifies a transform, by having
--   itself exactly one child lens and any number of children
--   labelled incl and excl. The value of NAME has no
--   meaning.
--   
--   The lens grandchild of augeasload specifies which lens
--   to use, and can either be the fully qualified name of a lens
--   lens 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 augeasload
--   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.
--   
--   When AUG_INIT is first called, it populates augeasload with the
--   transforms marked for autoloading in all the modules it finds.
--   
--   Before loading any files, AUG_LOAD will remove everything underneath
--   augeasfiles 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 help 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 quit 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
