augeas

README

go-ruby-augeas/augeas

Pure-Go (CGO=0) adapter presenting the ruby-augeas gem API over the configuration-editing engine github.com/go-augeas/augeas.

It mirrors the engine+adapter split used by go-facter/go-ruby-facter and go-hiera/go-ruby-hiera: all Augeas semantics live in the engine; this package is a thin, faithful, importable rename of that surface to the gem's method names, with no Ruby-runtime dependency.

a := augeas.Open("/", "", augeas.None)
lens, _ := augeas.LensByName("Hosts")
_ = a.TextStore(lens, "/files/etc/hosts", "127.0.0.1 localhost\n")

v, _ := a.Get("/files/etc/hosts/1/canonical") // "localhost"
_ = a.Set("/files/etc/hosts/1/alias", "loopback")
n := a.Rm("/files/etc/hosts/1/alias")         // 1

API

Constructors New() and Open(root, loadpath string, flags int) plus the AUG_* flag constants (None, SaveBackup, SaveNewFile, TypeCheck, NoStdinc, SaveNoop, NoLoad, NoModlAutoload, EnableSpan).

Methods, each delegating to the engine: Get, Exists, Set, Setm, Insert, Rm, Mv, Match, Label, Defvar, Defnode, TextStore, TextRetrieve, Load, Save, Span, Error, plus Root, LoadPath, Flags, Engine and SetFileSystem.

The Lens, Span and FileSystem types and LensByName are re-exported from the engine so callers need not import it directly.

Scope

This adapter adds no new Augeas behaviour; the supported path constructs, the built-in lenses (Hosts, Fstab, Shellvars/Simplevars, Ini/Keyvalue) and the explicit list of deferred features (the ~200-lens catalogue, the .aug lens DSL, span tracking, extended path functions, aug_load autodetection) are documented in the engine README.

Because the pure-Go engine performs no file autoload, Open records its arguments but reads nothing until Load is called explicitly.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package augeas is a pure-Go (no cgo) adapter that presents the ruby-augeas gem API over the configuration-editing engine github.com/go-augeas/augeas.

The go-augeas engine already implements Augeas semantics: the tree model, the XPath-like path language, the get/set/insert/move/remove editing operations, the lens framework and file load/save behind a filesystem seam. This package does not reimplement any of that; it wraps the engine and renames the surface to match the Ruby gem so a consumer such as go-embedded-ruby (rbgo) can expose a Ruby "Augeas" class:

• a constructor pair, New and Open(root, loadpath, flags), mirroring Augeas.new / Augeas.open, with the AUG_* flag constants;
• the gem method surface: Augeas.Get, Augeas.Exists, Augeas.Set, Augeas.Setm, Augeas.Insert, Augeas.Rm, Augeas.Mv, Augeas.Match, Augeas.Save, Augeas.Load, Augeas.Defvar, Augeas.Defnode, Augeas.Label, Augeas.TextStore, Augeas.TextRetrieve, Augeas.Span and Augeas.Error, each delegating to the engine;
• type aliases (Lens, Span, FileSystem) and LensByName re-exported so callers need not import the engine directly;
• an injectable filesystem seam (Augeas.SetFileSystem) where the Ruby interpreter's I/O would otherwise plug in.

The package has no dependency on any Ruby runtime: the surface is Go-typed and a Ruby binding layer marshals Ruby values onto these Go types.

Index

• Constants
• Variables
• type Augeas
  • func New() *Augeas
  • func Open(root, loadPath string, flags int) *Augeas
  • func (a *Augeas) Defnode(name, expr, value string) (string, bool)
  • func (a *Augeas) Defvar(name, expr string) (int, error)
  • func (a *Augeas) Engine() *engine.Augeas
  • func (a *Augeas) Error() error
  • func (a *Augeas) Exists(path string) bool
  • func (a *Augeas) Flags() int
  • func (a *Augeas) Get(path string) (string, bool)
  • func (a *Augeas) Insert(path, label string, before bool) error
  • func (a *Augeas) Label(path string) (string, bool)
  • func (a *Augeas) Load(lens Lens, pattern, mount string) error
  • func (a *Augeas) LoadPath() string
  • func (a *Augeas) Match(path string) []string
  • func (a *Augeas) Mv(src, dst string) error
  • func (a *Augeas) Rm(path string) int
  • func (a *Augeas) Root() string
  • func (a *Augeas) Save(lens Lens, mount, filename string) error
  • func (a *Augeas) Set(path, value string) error
  • func (a *Augeas) SetFileSystem(fs FileSystem)
  • func (a *Augeas) Setm(base, sub, value string) (int, error)
  • func (a *Augeas) Span(path string) (Span, error)
  • func (a *Augeas) TextRetrieve(lens Lens, path string, node *engine.Node) (string, error)
  • func (a *Augeas) TextStore(lens Lens, path, text string) error
• type FileSystem
• type Lens
  • func LensByName(name string) (Lens, bool)
• type Span

Constants

const (
	None           = 0
	SaveBackup     = 1 << 0
	SaveNewFile    = 1 << 1
	TypeCheck      = 1 << 2
	NoStdinc       = 1 << 3
	SaveNoop       = 1 << 4
	NoLoad         = 1 << 5
	NoModlAutoload = 1 << 6
	EnableSpan     = 1 << 7
)

Flag values mirror the ruby-augeas AUG_* constants passed to Augeas.open. They are recorded on the handle so a Ruby binding round-trips them; the pure-Go engine does not perform file autoload, type checking or backups, so only NoLoad changes behaviour here (Open never touches the filesystem regardless).

Variables

var ErrSpanUnsupported = engine.ErrSpanUnsupported

ErrSpanUnsupported is returned by Augeas.Span; span tracking is a documented deferred feature of the engine.

Types

type Augeas

type Augeas struct {
	// contains filtered or unexported fields
}

Augeas is a ruby-augeas-shaped handle over a go-augeas engine tree.

func New

func New() *Augeas

New returns a handle with default settings, mirroring Augeas.new with no arguments.

func Open

func Open(root, loadPath string, flags int) *Augeas

Open mirrors Augeas.open(root, loadpath, flags), recording the arguments on the handle. The pure-Go engine does not autoload files, so nothing is read until Augeas.Load is called explicitly.

func (*Augeas) Defnode

func (a *Augeas) Defnode(name, expr, value string) (string, bool)

Defnode binds name to expr, creating a node with value when expr matches nothing; it returns the node path and whether it was created (aug_defnode).

func (*Augeas) Defvar

func (a *Augeas) Defvar(name, expr string) (int, error)

Defvar binds name to the node-set from expr and returns the count (aug_defvar).

func (*Augeas) Engine

func (a *Augeas) Engine() *engine.Augeas

Engine exposes the underlying engine handle for advanced use.

func (*Augeas) Error

func (a *Augeas) Error() error

Error returns the last error recorded by the engine (aug_error).

func (*Augeas) Exists

func (a *Augeas) Exists(path string) bool

Exists reports whether at least one node matches path (aug_exists).

func (*Augeas) Flags

func (a *Augeas) Flags() int

Flags returns the flags passed to Open (None for New).

func (*Augeas) Get

func (a *Augeas) Get(path string) (string, bool)

Get returns the value at path; the boolean reports whether exactly one node matched (aug_get).

func (*Augeas) Insert

func (a *Augeas) Insert(path, label string, before bool) error

Insert inserts a sibling labelled label next to path (aug_insert).

func (*Augeas) Label

func (a *Augeas) Label(path string) (string, bool)

Label returns the label of the single node matching path (aug_label).

func (*Augeas) Load

func (a *Augeas) Load(lens Lens, pattern, mount string) error

Load reads files matching pattern, parses them with lens and mounts them under mount (aug_load, given an explicit lens/glob).

func (*Augeas) LoadPath

func (a *Augeas) LoadPath() string

LoadPath returns the loadpath argument passed to Open ("" for New).

func (*Augeas) Match

func (a *Augeas) Match(path string) []string

Match returns the paths of all nodes matching path (aug_match).

func (*Augeas) Mv

func (a *Augeas) Mv(src, dst string) error

Mv moves the node matching src onto dst (aug_mv).

func (*Augeas) Rm

func (a *Augeas) Rm(path string) int

Rm removes every node matching path and returns the count (aug_rm).

func (*Augeas) Root

func (a *Augeas) Root() string

Root returns the root argument passed to Open ("" for New).

func (*Augeas) Save

func (a *Augeas) Save(lens Lens, mount, filename string) error

Save serialises the subtree at mount with lens and writes it to filename (aug_save, given an explicit lens/mount/target).

func (*Augeas) Set

func (a *Augeas) Set(path, value string) error

Set sets the value at path, creating the node if absent (aug_set).

func (*Augeas) SetFileSystem

func (a *Augeas) SetFileSystem(fs FileSystem)

SetFileSystem injects the filesystem seam used by Load and Save.

func (*Augeas) Setm

func (a *Augeas) Setm(base, sub, value string) (int, error)

Setm sets value on every node matching sub under each node matching base, returning the count (aug_setm).

func (*Augeas) Span

func (a *Augeas) Span(path string) (Span, error)

Span mirrors aug_span; span tracking is deferred, so it always returns ErrSpanUnsupported.

func (*Augeas) TextRetrieve

func (a *Augeas) TextRetrieve(lens Lens, path string, node *engine.Node) (string, error)

TextRetrieve serialises the subtree with lens (aug_text_retrieve). When node is nil the single subtree at path is used.

func (*Augeas) TextStore

func (a *Augeas) TextStore(lens Lens, path, text string) error

TextStore parses text with lens and stores the tree at path (aug_text_store).

type FileSystem

type FileSystem = engine.FileSystem

FileSystem is the engine filesystem seam, re-exported for adapter callers.

type Lens

type Lens = engine.Lens

Lens is the engine lens interface, re-exported for adapter callers.

func LensByName

func LensByName(name string) (Lens, bool)

LensByName returns the built-in engine lens registered under name.

type Span

type Span = engine.Span

Span is the engine span record, re-exported for adapter callers.