class Augeas

Define the ruby class

Wrapper class for the augeas library.

Constants

ERRORS_HASH

Public Class Methods

create(opts={}, &block) click to toggle source

Create a new Augeas instance and return it.

Use :root as the filesystem root. If :root is nil, 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

The following flags can be specified in a hash. They all default to false and can be enabled by setting them to true

:type_check - typecheck lenses (since it can be very expensive it is not done by default)

:no_stdinc - do not use the builtin load path for modules

:no_load - do not load the tree during the initialization phase

:no_modl_autoload - do not load the tree during the initialization phase

:enable_span - track the span in the input nodes

:save_mode can be one of :backup, :newfile, :noop as explained below.

:noop - make save a no-op process, just record what would have changed

:backup - keep the original file with an .augsave extension

:newfile - save changes into a file with an .augnew extension and
do not overwrite the original file.

When a block is given, the Augeas instance is passed as the only argument into the block and closed when the block exits. With no block, the Augeas instance is returned.

# File lib/augeas.rb, line 98
def self.create(opts={}, &block)
  Augeas::Facade::create(opts, &block)
end

open(root = nil, loadpath = nil, flags = NONE) { |aug| ... } click to toggle source

Create a new Augeas instance and return it.

Use root as the filesystem root. If root is nil, 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 bitmask (see enum aug_flags)

When a block is given, the Augeas instance is passed as the only argument into the block and closed when the block exits. In that case, the return value of the block is the return value of open. With no block, the Augeas instance is returned.

# File lib/augeas.rb, line 118
def self.open(root = nil, loadpath = nil, flags = NONE, &block)
    aug = open3(root, loadpath, flags)
    if block_given?
        begin
            rv = yield aug
            return rv
        ensure
            aug.close
        end
    else
        return aug
    end
end

open3(p1, p2, p3) click to toggle source

VALUE augeas_init(VALUE m, VALUE r, VALUE l, VALUE f) {
    return init(c_augeas, m, r, l, f);
}

Public Instance Methods

clear(path) click to toggle source

Clear the path, i.e. make its value nil

# File lib/augeas.rb, line 147
def clear(path)
    set_internal(path, nil)
end

clear_transforms() click to toggle source

Clear all transforms under /augeas/load. If load is called right after this, there will be no files under /files

# File lib/augeas.rb, line 166
def clear_transforms
    rm("/augeas/load/*")
end

clearm(base, sub) click to toggle source

Clear multiple nodes values in one operation. Find or create a node matching sub by interpreting sub as a path expression relative to each node matching base. If sub is ‘.’, the nodes matching base will be modified.

# File lib/augeas.rb, line 154
def clearm(base, sub)
    setm(base, sub, nil)
end

close() click to toggle source

VALUE augeas_close (VALUE s) {
    augeas *aug = aug_handle(s);

    aug_close(aug);
    DATA_PTR(s) = NULL;

    return Qnil;
}

context() click to toggle source

Get path expression context (from /augeas/context)

# File lib/augeas.rb, line 209
def context
  get('/augeas/context')
end

context=(path) click to toggle source

Set path expression context to path (in /augeas/context)

# File lib/augeas.rb, line 204
def context=(path)
  set_internal('/augeas/context', path)
end

defnode(NAME, EXPR, VALUE) → boolean click to toggle source

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.

Returns false if aug_defnode fails, and the number of nodes in the nodeset on success.

VALUE augeas_defnode(VALUE s, VALUE name, VALUE expr, VALUE value) {
    augeas *aug = aug_handle(s);
    const char *cname = StringValueCStr(name);
    const char *cexpr = StringValueCStrOrNull(expr);
    const char *cvalue = StringValueCStrOrNull(value);

    /* FIXME: Figure out a way to return created, maybe accept a block
       that gets run when created == 1 ? */
    int r = aug_defnode(aug, cname, cexpr, cvalue, NULL);

    return (r < 0) ? Qfalse : INT2NUM(r);
}

defvar(NAME, EXPR) → boolean click to toggle source

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.

If EXPR is NULL, the variable NAME will be removed if it is defined.

VALUE augeas_defvar(VALUE s, VALUE name, VALUE expr) {
    augeas *aug = aug_handle(s);
    const char *cname = StringValueCStr(name);
    const char *cexpr = StringValueCStrOrNull(expr);

    int r = aug_defvar(aug, cname, cexpr);

    return (r < 0) ? Qfalse : Qtrue;
}

error → HASH click to toggle source

Retrieve details about the last error encountered and return those details in a HASH with the following entries:

:code error code from aug_error
:message error message from aug_error_message
:minor minor error message from aug_minor_error_message
:details error details from aug_error_details

VALUE augeas_error(VALUE s) {
    augeas *aug = aug_handle(s);
    int code;
    const char *msg;
    VALUE result;

    result = rb_hash_new();

    code = aug_error(aug);
    hash_set(result, "code", INT2NUM(code));

    msg = aug_error_message(aug);
    if (msg != NULL)
        hash_set(result, "message", rb_str_new2(msg));

    msg = aug_error_minor_message(aug);
    if (msg != NULL)
        hash_set(result, "minor", rb_str_new2(msg));

    msg = aug_error_details(aug);
    if (msg != NULL)
        hash_set(result, "details", rb_str_new2(msg));

    return result;
}

exists(PATH) → boolean click to toggle source

Return true if there is an entry for this path, false otherwise

VALUE augeas_exists(VALUE s, VALUE path) {
    augeas *aug = aug_handle(s);
    const char *cpath = StringValueCStr(path);
    int ret = aug_get(aug, cpath, NULL);

    return (ret == 1) ? Qtrue : Qfalse;
}

get(PATH) → String click to toggle source

Lookup the value associated with PATH

VALUE augeas_get(VALUE s, VALUE path) {
    augeas *aug = aug_handle(s);
    const char *cpath = StringValueCStr(path);
    const char *value = NULL;

    int r = aug_get(aug, cpath, &value);
    /* There used to be a bug in Augeas that would make it not properly set
     * VALUE to NULL when PATH was invalid. We check RETVAL, too, to avoid
     * running into that */
    if (r == 1 && value != NULL) {
        return rb_str_new(value, strlen(value)) ;
    } else {
        return Qnil;
    }
}

insert(PATH, LABEL, BEFORE) → int click to toggle source

Make LABEL a sibling of PATH by inserting it directly before or after PATH. The boolean BEFORE determines if LABEL is inserted before or after PATH.

VALUE augeas_insert(VALUE s, VALUE path, VALUE label, VALUE before) {
    augeas *aug = aug_handle(s);
    const char *cpath = StringValueCStr(path) ;
    const char *clabel = StringValueCStr(label) ;

    int callValue = aug_insert(aug, cpath, clabel, RTEST(before));
    return INT2FIX(callValue) ;
}

label(PATH) → String click to toggle source

Lookup the label associated with PATH

VALUE augeas_label(VALUE s, VALUE path) {
    augeas *aug = aug_handle(s);
    const char *cpath = StringValueCStr(path);
    const char *label;

    aug_label(aug, cpath, &label);
    if (label != NULL) {
        return rb_str_new(label, strlen(label)) ;
    } else {
        return Qnil;
    }
}

load() → boolean click to toggle source

Load files from disk according to the transforms under /augeas/load

VALUE augeas_load(VALUE s) {
    augeas *aug = aug_handle(s);
    int callValue = aug_load(aug);
    VALUE returnValue ;

    if (callValue == 0)
        returnValue = Qtrue ;
    else
        returnValue = Qfalse ;

    return returnValue ;
}

load!() click to toggle source

The same as load, but raises Augeas::Error if loading fails

# File lib/augeas.rb, line 199
def load!
    raise Augeas::Error unless load
end

match(PATH) → an_array click to toggle source

Return all the paths that match the path expression PATH as an aray of strings.

VALUE augeas_match(VALUE s, VALUE p) {
    augeas *aug = aug_handle(s);
    const char *path = StringValueCStr(p);
    VALUE result;
    char **matches = NULL;
    int cnt, i;

    cnt = aug_match(aug, path, &matches) ;
    if (cnt < 0)
        rb_raise(rb_eSystemCallError, "Matching path expression '%s' failed",
                 path);

    result = rb_ary_new();
    for (i = 0; i < cnt; i++) {
        rb_ary_push(result, rb_str_new(matches[i], strlen(matches[i])));
        free(matches[i]) ;
    }
    free (matches) ;

    return result ;
}

mv(SRC, DST) → int click to toggle source

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.

VALUE augeas_mv(VALUE s, VALUE src, VALUE dst) {
    augeas *aug = aug_handle(s);
    const char *csrc = StringValueCStr(src);
    const char *cdst = StringValueCStr(dst);
    int r = aug_mv(aug, csrc, cdst);

    return INT2FIX(r);
}

rename(SRC, LABEL) → int click to toggle source

Rename the label of all nodes matching SRC to LABEL.

Returns false if aug_rename fails, and the number of nodes renamed on success.

VALUE augeas_rename(VALUE s, VALUE src, VALUE label) {
    augeas *aug = aug_handle(s);
    const char *csrc = StringValueCStr(src);
    const char *clabel = StringValueCStr(label);
    int r = aug_rename(aug, csrc, clabel);

    return (r < 0) ? Qfalse : INT2NUM(r);
}

rm(PATH) → int click to toggle source

Remove path and all its children. Returns the number of entries removed

VALUE augeas_rm(VALUE s, VALUE path) {
    augeas *aug = aug_handle(s);
    const char *cpath = StringValueCStr(path) ;

    int callValue = aug_rm(aug, cpath) ;
    return INT2FIX(callValue) ;
}

save() → boolean click to toggle source

Write all pending changes to disk

VALUE augeas_save(VALUE s) {
    augeas *aug = aug_handle(s);

    return (aug_save(aug) == 0) ? Qtrue : Qfalse;
}

save!() click to toggle source

The same as save, but raises Augeas::Error if saving fails

# File lib/augeas.rb, line 194
def save!
    raise Augeas::Error unless save
end

set(path, *values) click to toggle source

Set one or multiple elemens to path. Multiple elements are mainly sensible with a path like …/array, since this will append all elements.

# File lib/augeas.rb, line 135
def set(path, *values)
    values.flatten.each { |v| set_internal(path, v) }
end

set!(path, *values) click to toggle source

The same as set, but raises Augeas::Error if setting fails

# File lib/augeas.rb, line 140
def set!(path, *values)
    values.flatten.each do |v|
        raise Augeas::Error unless set_internal(path, v)
    end
end

set(PATH, VALUE) → int click to toggle source

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.

VALUE augeas_set(VALUE s, VALUE path, VALUE value) {
    int callValue = set(s, path, value);

    return (callValue == 0) ? Qtrue : Qfalse;
}

setm(BASE, SUB, VALUE) → boolean click to toggle source

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

VALUE augeas_setm(VALUE s, VALUE base, VALUE sub, VALUE value) {
    augeas *aug = aug_handle(s);
    const char *cbase = StringValueCStr(base) ;
    const char *csub = StringValueCStrOrNull(sub) ;
    const char *cvalue = StringValueCStrOrNull(value) ;

    int callValue = aug_setm(aug, cbase, csub, cvalue) ;
    return INT2FIX(callValue);
}

span(p1) click to toggle source

VALUE augeas_span(VALUE s, VALUE path) {
    augeas *aug = aug_handle(s);
    char *cpath = StringValueCStr(path);
    char *filename = NULL;
    unsigned int label_start, label_end, value_start, value_end,
        span_start, span_end;
    int r;
    VALUE result;

    r = aug_span(aug, cpath,
                 &filename,
                 &label_start, &label_end,
                 &value_start, &value_end,
                 &span_start, &span_end);

    result = rb_hash_new();

    if (r == 0) {
        hash_set(result, "filename", rb_str_new2(filename));
        hash_set_range(result, "label", label_start, label_end);
        hash_set_range(result, "value", value_start, value_end);
        hash_set_range(result, "span", span_start, span_end);
    }

    free(filename);

    return result;
}

srun(COMMANDS) → [int, String] click to toggle source

Run one or more newline-separated commands, returning their output.

Returns: an array where the first element is the number of executed commands on success, -1 on failure, and -2 if a ‘quit’ command was encountered. The second element is a string of the output from all commands.

VALUE augeas_srun(VALUE s, VALUE text) {
    augeas *aug = aug_handle(s);
    const char *ctext = StringValueCStr(text);
    int r;
    VALUE result;
    struct memstream ms;
    __aug_init_memstream(&ms);

    r = aug_srun(aug, ms.stream, ctext);
    __aug_close_memstream(&ms);

    result = rb_ary_new();
    rb_ary_push(result, INT2NUM(r));
    rb_ary_push(result, rb_str_new2(ms.buf));

    free(ms.buf);
    return result;
}

text_retrieve(LENS, NODE_IN, PATH, NODE_OUT) → boolean click to toggle source

Transform the tree at PATH into a string using lens LENS and store it in the node NODE_OUT, assuming the tree was initially generated using the value of node NODE_IN. PATH, NODE_IN, and NODE_OUT are path expressions.

VALUE augeas_text_retrieve(VALUE s, VALUE lens, VALUE node_in, VALUE path, VALUE node_out) {
    augeas *aug = aug_handle(s);
    const char *clens = StringValueCStr(lens);
    const char *cnode_in = StringValueCStr(node_in);
    const char *cpath = StringValueCStr(path);
    const char *cnode_out = StringValueCStr(node_out);
    int r = aug_text_retrieve(aug, clens, cnode_in, cpath, cnode_out);

    return (r < 0) ? Qfalse : Qtrue;
}

text_store(LENS, NODE, PATH) → boolean click to toggle source

Use the value of node NODE as a string and transform it into a tree using the lens LENS and store it in the tree at PATH, which will be overwritten. PATH and NODE are path expressions.

VALUE augeas_text_store(VALUE s, VALUE lens, VALUE node, VALUE path) {
    augeas *aug = aug_handle(s);
    const char *clens = StringValueCStr(lens);
    const char *cnode = StringValueCStr(node);
    const char *cpath = StringValueCStr(path);
    int r = aug_text_store(aug, clens, cnode, cpath);

    return (r < 0) ? Qfalse : Qtrue;
}

touch(path) click to toggle source

Create the path with empty value if it doesn’t exist

# File lib/augeas.rb, line 159
def touch(path)
    set_internal(path, nil) if match(path).empty?
end

transform(hash) click to toggle source

Add a transform under /augeas/load

The HASH can contain the following entries

:lens - the name of the lens to use
:name - a unique name; use the module name of the LENS when omitted
:incl - a list of glob patterns for the files to transform
:excl - a list of the glob patterns to remove from the list that matches :INCL

# File lib/augeas.rb, line 177
def transform(hash)
    lens = hash[:lens]
    name = hash[:name]
    incl = hash[:incl]
    excl = hash[:excl]
    raise ArgumentError, "No lens specified" unless lens
    raise ArgumentError, "No files to include" unless incl
    lens = "#{lens}.lns" unless lens.include? '.'
    name = lens.split(".")[0].sub("@", "") unless name

    xfm = "/augeas/load/#{name}/"
    set(xfm + "lens", lens)
    set(xfm + "incl[last()+1]", incl)
    set(xfm + "excl[last()+1]", excl) if excl
end