augeas

README

Go bindings for Augeas

This package provides Go bindings for Augeas, the configuration editing tool.

Installation

go get honnef.co/go/augeas

Documentation

Documentation can be found at godoc.org.

Examples

Simple example

package main

import (
	"honnef.co/go/augeas"

	"fmt"
)

func main() {
	ag, err := augeas.New("/", "", augeas.None)
	if err != nil {
		panic(err)
	}

	// There is also Augeas.Version(), but we're demonstrating Get
	// here.
	version, err := ag.Get("/augeas/version")
	fmt.Println(version, err)
}

Extended example

An extended example that fetches all host entries from /etc/hosts can be found in the playground.

Documentation

Overview

Package augeas provides Go bindings for Augeas, the configuration editing tool.

For more information on Augeas itself, check out http://augeas.net/

Index

• Constants
• type Augeas
  • func New(root, loadPath string, flags Flag) (Augeas, error)
  • func (a Augeas) Clear(path string) error
  • func (a Augeas) Close()
  • func (a Augeas) DefineNode(name, expression, value string) (num int, created bool, err error)
  • func (a Augeas) DefineVariable(name, expression string) (int, error)
  • func (a Augeas) Get(path string) (value string, err error)
  • func (a Augeas) GetAll(path string) (values []string, err error)
  • func (a Augeas) Insert(path, label string, before bool) error
  • func (a Augeas) Label(path string) (value string, err error)
  • func (a Augeas) Load() error
  • func (a Augeas) LoadFile(file string) error
  • func (a Augeas) Match(path string) (matches []string, err error)
  • func (a Augeas) Move(source, destination string) error
  • func (a Augeas) Remove(path string) (num int)
  • func (a Augeas) RemoveVariable(name string) error
  • func (a Augeas) Save() error
  • func (a Augeas) Set(path, value string) error
  • func (a Augeas) SetMultiple(base, sub, value string) (int, error)
  • func (a Augeas) Span(path string) (Span, error)
  • func (a Augeas) Transform(lens, file string, excl bool) error
  • func (a Augeas) Version() string
• type Error
  • func (err Error) Error() string
• type ErrorCode
• type Flag
• type Span

Constants

const (
	// Keep the original file with a .augsave extension
	SaveBackup = 1 << iota

	// Save changes into a file with extension .augnew, and do not
	// overwrite the original file. Takes precedence over SaveBackup
	SaveNewFile

	// Typecheck lenses; since it can be very expensive it is not done
	// by default
	TypeCheck

	// Do not use the built-in load path for modules
	NoStdinc

	// Make save a no-op process, just record what would have changed
	SaveNoop

	// Do not load the tree automatically
	NoLoad

	NoModlAutoload

	// Track the span in the input of nodes
	EnableSpan

	// Do not close automatically when encountering error during
	// initialization
	NoErrClose

	None Flag = 0
)

Bits or'ed together to modify the behavior of Augeas.

const (
	CouldNotInitialize ErrorCode = -2
	NoMatch                      = -1

	// No error
	NoError = 0

	// Out of memory
	ENOMEM

	// Internal (to augeas itself) error (bug)
	EINTERNAL

	// Invalid path expression
	EPATHX

	// No match for path expression
	ENOMATCH

	// Too many matches for path expression
	EMMATCH

	// Syntax error in lens file
	ESYNTAX

	// Lens lookup failed
	ENOLENS

	// Multiple transforms
	EMXFM

	// No span for this node
	ENOSPAN

	// Cannot move node into its descendant
	EMVDESC

	// Failed to execute command
	ECMDRUN

	// Invalid argument in function call
	EBADARG
)

The possible error codes stored in Error.Code.

Types

type Augeas

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

Augeas encapsulates an Augeas handle.

func New

func New(root, loadPath string, flags Flag) (Augeas, error)

New creates a new Augeas handle, specifying the file system root, a list of module directories and flags.

Call the Close method once done with the handle.

func (Augeas) Clear

func (a Augeas) Clear(path string) error

Clear clears the value associated with a path. Intermediate entries are created if they don't exist.

func (Augeas) Close

func (a Augeas) Close()

Close closes the Augeas instance and frees any storage associated with it. After closing, the handle is invalid and can not be used for any more operations.

func (Augeas) DefineNode

func (a Augeas) DefineNode(name, expression, value string) (num int, created bool, err error)

DefineNode defines a variable whose value is the result of evaluating the expression, which must not be empty and evaluate to a nodeset. If a variable with the name already exists, it will be replaced.

If the expression evaluates to an empty nodeset, a node is created.

Returns the number of nodes in the nodeset and whether a node has been created or of it already existed.

func (Augeas) DefineVariable

func (a Augeas) DefineVariable(name, expression string) (int, error)

DefineVariable defines a variable whose value is the result of evaluating the expression. If a variable with the name already exists, it will be replaced. Context will not be applied to the expression.

If the expression is empty, the variable will be removed.

Path variables can be used in path expressions later on by prefixing them with '$'.

Returns the number of nodes if the expression evaluates to a nodeset.

func (Augeas) Get

func (a Augeas) Get(path string) (value string, err error)

Get looks up the value associated with a path.

Returns an error if there are no or too many matching nodes, or if the path is not a legal path expression.

func (Augeas) GetAll

func (a Augeas) GetAll(path string) (values []string, err error)

GetAll gets all values associated with a path.

func (Augeas) Insert

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

Insert creates a new sibling for a path by inserting into the tree just before the path if before is true or just after it if before is false.

The path must match exactly one existing node in the tree, and the label must not contain a '/', '*' or end with a bracketed index '[N]'.

func (Augeas) Label

func (a Augeas) Label(path string) (value string, err error)

Label gets the label associated with a path.

Returns an error if there are no or too many matching nodes, or if the path is not a legal path expression.

func (Augeas) Load

func (a Augeas) Load() error

Load loads files into the tree. Which files to load and what lenses to use on them is specified under /augeas/load in the tree; each entry /augeas/load/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 /augeas/load specifies which lens to use, and can either be the fully qualified name of a lens 'Module.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 /augeas/load 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 New is first called, it populates /augeas/load with the transforms marked for autoloading in all the modules it finds.

Before loading any files, Load will remove everything underneath /augeas/files and /files, regardless of whether any entries have been modified or not.

Note that success includes the case where some files could not be loaded. Details of such files can be found as '/augeas//error'.

func (Augeas) LoadFile

func (a Augeas) LoadFile(file string) error

LoadFile loads a single file to the Augeas tree.

func (Augeas) Match

func (a Augeas) Match(path string) (matches []string, err error)

Match returns all paths matching a given path. The returned paths are sufficiently qualified to make sure that they match exactly one node in the current tree.

Path expressions use a very simple subset of XPath: the 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.

func (Augeas) Move

func (a Augeas) Move(source, destination string) error

Move moves 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.

func (Augeas) Remove

func (a Augeas) Remove(path string) (num int)

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

func (Augeas) RemoveVariable

func (a Augeas) RemoveVariable(name string) error

RemoveVariable removes a variable previously defined by DefineVariable.

func (Augeas) Save

func (a Augeas) Save() error

Save writes all pending changes to disk.

func (Augeas) Set

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

Set the value associated with a path. Intermediate entries are created if they don't exist.

func (Augeas) SetMultiple

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

SetMultiple sets 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 empty, in which case all the nodes matching base will be modified.

Returns the number of modified nodes.

func (Augeas) Span

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

Span gets the span according to input file of the node associated with a path. If the node is associated with a file, the filename, label and value start and end positions are set.

func (Augeas) Transform

func (a Augeas) Transform(lens, file string, excl bool) error

Transform adds a transform for a lens/file couple.

func (Augeas) Version

func (a Augeas) Version() string

Version returns the Augeas version.

type Error

type Error struct {
	Code ErrorCode

	// Human-readable error message
	Message string

	// Human-readable message elaborating the error. For example, when
	// the error code is AUG_EPATHX, this will explain how the path
	// expression is invalid
	MinorMessage string

	// Details about the error. For example, for AUG_EPATHX, indicates
	// where in the path expression the error occurred.
	Details string
}

Error encapsulates errors returned by Augeas.

func (Error) Error

func (err Error) Error() string

type ErrorCode

type ErrorCode int

ErrorCode is used to differentiate between the different errors returned by Augeas. Positive values are from Augeas itself, while negative values are specific to these bindings.

type Flag

type Flag uint

Flag describes flags that influence the behaviour of Augeas when passed to New.

type Span

type Span struct {
	Filename   string
	LabelStart uint
	LabelEnd   uint
	ValueStart uint
	ValueEnd   uint
	SpanStart  uint
	SpanEnd    uint
}

A Span describes the position of a node in the file it was parsed from.