augeas-0.6.1: A Haskell FFI wrapper for the Augeas API

Safe Haskell | None

System.Augeas

Contents

- Types
- Functions

Description

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.

Synopsis

- type Augeas = ()
- newtype AugFlag = AugFlag {
  - unAugFlag :: 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
- data AugMatch
- exactly_one :: AugMatch
- no_match :: AugMatch
- invalid_match :: AugMatch
- newtype AugRet = AugRet CInt
- success :: AugRet
- one :: AugRet
- error :: AugRet
- newtype AugBefore = AugBefore CInt
- just_before :: AugBefore
- just_after :: AugBefore
- newtype AugErrCode = AugErrCode {
  - unAugErrCode :: 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
- aug_init :: ByteString -> ByteString -> [AugFlag] -> IO (Maybe (ForeignPtr Augeas))
- aug_defvar :: Ptr Augeas -> ByteString -> Maybe ByteString -> IO AugRet
- aug_defnode :: Ptr Augeas -> ByteString -> ByteString -> ByteString -> IO (AugRet, Maybe Bool)
- aug_get :: Ptr Augeas -> ByteString -> IO (Either AugMatch (Maybe String))
- aug_set :: Ptr Augeas -> ByteString -> ByteString -> IO AugRet
- aug_setm :: Ptr Augeas -> ByteString -> Maybe ByteString -> ByteString -> IO AugRet
- aug_span :: Ptr Augeas -> ByteString -> IO (Maybe (String, CInt, CInt, CInt, CInt, CInt, CInt))
- aug_insert :: Ptr Augeas -> ByteString -> ByteString -> AugBefore -> IO AugRet
- aug_rm :: Ptr Augeas -> ByteString -> IO CInt
- aug_mv :: Ptr Augeas -> ByteString -> ByteString -> IO AugRet
- aug_match :: Ptr Augeas -> ByteString -> IO (Int, Maybe [String])
- aug_save :: Ptr Augeas -> IO AugRet
- aug_load :: Ptr Augeas -> IO AugRet
- aug_print :: Ptr Augeas -> Handle -> ByteString -> IO AugRet
- aug_srun :: Ptr Augeas -> Handle -> ByteString -> IO AugRet
- aug_error :: Ptr Augeas -> IO AugErrCode
- aug_error_message :: Ptr Augeas -> IO ByteString
- aug_error_minor_message :: Ptr Augeas -> IO ByteString
- aug_error_details :: Ptr Augeas -> IO ByteString
- aug_to_xml :: Ptr Augeas -> ByteString -> [AugFlag] -> IO (AugRet, Maybe (Ptr AugeasXmlNode))

# Types

type Augeas = ()Source

A pointer to the Augeas tree structure Not using a typed pointer (as per RWH p416) because of the compiler warning

newtype AugFlag Source

Constructors

AugFlag |

Fields

unAugFlag :: CInt

Instances

Eq AugFlag |
Show AugFlag |

none :: AugFlag Source

save_backup :: AugFlag Source

save_newfile :: AugFlag Source

type_check :: AugFlag Source

no_stdinc :: AugFlag Source

save_noop :: AugFlag Source

no_load :: AugFlag Source

no_modl_autoload :: AugFlag Source

enable_span :: AugFlag Source

data AugMatch Source

The possible `aug_get` return values.

Instances

Eq AugMatch |
Show AugMatch |

exactly_one :: AugMatch Source

Exactly one match was found.

no_match :: AugMatch Source

No matches were found

invalid_match :: AugMatch Source

Either an invalid paths, or multiple matches were found.

newtype AugRet Source

The possible return values for the `aug_set`, `aug_insert`, `aug_mv`, `aug_save`, and `aug_print` functions

Constructors

AugRet CInt |

Instances

Eq AugRet |
Show AugRet |

success :: AugRet Source

The function worked as expected

one :: AugRet Source

error :: AugRet Source

The function failed

newtype AugBefore Source

The possible BEFORE values fro the aug_insert function

Constructors

AugBefore CInt |

Instances

Eq AugBefore |
Show AugBefore |

just_before :: AugBefore Source

Insert the LABEL just before the PATH

just_after :: AugBefore Source

Insert the LABEL just after the PATH

newtype AugErrCode Source

Constructors

AugErrCode |

Fields

unAugErrCode :: CInt

Instances

Eq AugErrCode |
Show AugErrCode |

no_error :: AugErrCode Source

err_no_memory :: AugErrCode Source

err_internal :: AugErrCode Source

err_bad_path :: AugErrCode Source

err_no_match :: AugErrCode Source

err_multi_matches :: AugErrCode Source

err_syntax :: AugErrCode Source

err_no_lens :: AugErrCode Source

err_multi_xfm :: AugErrCode Source

err_no_span :: AugErrCode Source

err_mv_desc :: AugErrCode Source

err_cmd_run :: AugErrCode Source

# Functions

aug_init Source

Arguments

:: ByteString | ROOT
-> ByteString | LOADPATH
-> [AugFlag] | FLAGS
-> IO (Maybe (ForeignPtr Augeas)) | Augeas pointer

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_defvar Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | NAME
-> Maybe ByteString | Maybe EXPR
-> IO AugRet | AugRet

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_defnode Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | NAME
-> ByteString | EXPR
-> ByteString | VALUE
-> IO (AugRet, Maybe Bool) | (AugMatch,b_NodeCreated)

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_get Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | PATH
-> IO (Either AugMatch (Maybe String)) | Either AugMatch or VALUE

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_set Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | PATH
-> ByteString | VALUE
-> IO AugRet | return value

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_setm Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString |
-> Maybe 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_span Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | Path
-> IO (Maybe (String, CInt, CInt, CInt, CInt, CInt, CInt)) |

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_insert Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | PATH
-> ByteString | LABEL
-> AugBefore | BEFORE
-> IO AugRet | return value

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_rm Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | PATH
-> IO CInt | number of entries removed

Remove path and all its children. Returns the number of entries removed. All nodes that match PATH, and their descendants, are removed.

aug_mv Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | SRC
-> ByteString | DEST
-> IO AugRet | return value

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_match Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | PATH
-> IO (Int, Maybe [String]) | (match count, MATCHES)

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_save Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO AugRet | return value

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_load Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO AugRet | return value

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_print Source

Arguments

:: Ptr Augeas | Augeas pointer
-> Handle | Already opened file handle
-> ByteString | PATH
-> IO AugRet | return value

Print each node matching PATH and its descendants to OUT. Return AugRet.success on success, or AugRet.error on failure

aug_srun Source

Arguments

:: Ptr Augeas | Augeas pointer
-> Handle | OUT Already opened file handle
-> ByteString | TEXT
-> IO AugRet | return value

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_error Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO AugErrCode | return value

Return a human-readable message for the error code */

aug_error_message Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO ByteString | return value

Return a human-readable message for the error code */

aug_error_minor_message Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO ByteString | return value

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_details Source

Arguments

:: Ptr Augeas | Augeas pointer
-> IO ByteString | return value

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_to_xml Source

Arguments

:: Ptr Augeas | Augeas pointer
-> ByteString | path
-> [AugFlag] | flags
-> IO (AugRet, Maybe (Ptr AugeasXmlNode)) | error code

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