System.Augeas

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.

Types

type Augeas = ()

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

data AugFlag

Instances

Eq AugFlag

Show AugFlag

none :: AugFlag

save_backup :: AugFlag

save_newfile :: AugFlag

type_check :: AugFlag

data AugMatch

The possible aug_get return values.

Instances

Eq AugMatch

Show AugMatch

exactly_one :: AugMatch

Exactly one match was found.

no_match :: AugMatch

No matches were found

invalid_match :: AugMatch

Either an invalid paths, or multiple matches were found.

data AugRet

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

Instances

Eq AugRet

Show AugRet

success :: AugRet

The function worked as expected

error :: AugRet

The function failed

data AugBefore

The possible BEFORE values fro the aug_insert function

Instances

Eq AugBefore

Show AugBefore

just_before :: AugBefore

Insert the LABEL just before the PATH

just_after :: AugBefore

Insert the LABEL just after the PATH

Functions

aug_init

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_get

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.

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

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_insert

Arguments

:: Ptr Augeas

Augeas pointer

-> ByteString

PTH

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

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

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

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

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

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