class Augeas
Define the ruby class
Wrapper class for the augeas library.
Constants
- ERRORS_HASH
Public Class Methods
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
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
VALUE augeas_init(VALUE m, VALUE r, VALUE l, VALUE f) { return init(c_augeas, m, r, l, f); }
Public Instance Methods
Clear the path
, i.e. make its value nil
# File lib/augeas.rb, line 147 def clear(path) set_internal(path, nil) end
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
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
VALUE augeas_close (VALUE s) { augeas *aug = aug_handle(s); aug_close(aug); DATA_PTR(s) = NULL; return Qnil; }
Get path expression context (from /augeas/context)
# File lib/augeas.rb, line 209 def context get('/augeas/context') end
Set path expression context to path
(in /augeas/context)
# File lib/augeas.rb, line 204 def context=(path) set_internal('/augeas/context', path) end
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); }
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; }
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; }
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; }
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; } }
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) ; }
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 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 ; }
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
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 ; }
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 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); }
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) ; }
Write all pending changes to disk
VALUE augeas_save(VALUE s) { augeas *aug = aug_handle(s); return (aug_save(aug) == 0) ? Qtrue : Qfalse; }
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 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
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 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; }
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); }
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; }
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; }
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; }
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; }
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
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