auger

Documentation

Index

• Constants
• Variables
• func AugpathToFspath(augPath string) (fsPath string, err error)
• type Aug
  • func NewAuger(root, loadPath string, flags *AugFlags) (aug *Aug, err error)
  • func NewAugerFromAugeas(orig augeas.Augeas) (aug *Aug)
  • func (a *Aug) Close()
  • func (a *Aug) Interact() (err error)
  • func (a *Aug) RecursiveInclude(augLens, includeDirective, fsRoot string, optFlags ...includeOpt) (err error)
• type AugFlags
  • func (a *AugFlags) Eval() (augFlags augeas.Flag)

Constants

const (
	// IncludeOptNoExist specifies that inclusions are allowed to not exist, otherwise an error will be raised while attempting to parse them.
	IncludeOptNoExist includeOpt = 1 << iota
	// IncludeOptGlobbing indicates that the inclusion system supports globbing (as supported by (github.com/gobwas/glob).Match).
	IncludeOptGlobbing
	// IncludeOptRegex indicates that the inclusion system supports matching by regex (as supported by regexp).
	IncludeOptRegex
	// IncludeOptDirs indicates that the inclusion system supports matching by directory.
	IncludeOptDirs
	// IncludeOptDirsRecursive indicates that the inclusion system also recurses into subdirectories of matched directories. Only used if IncludeOptDirs is also set.
	IncludeOptDirsRecursive
)

const IncludeOptNone includeOpt = 0

IncludeOptNone is the default include recursion option for Aug.RecursiveInclude. * No special behavior is defined * All include directives are assumed to refer:

• Explicitly/exclusively to file paths
• That must exist

Variables

var (
	// PtrTrue and PtrFalse are convenience references for constructing an AugFlags if needed. It is recommended you do not change these values if you do not like being confused.
	PtrTrue  *bool = &dstPtrTrue
	PtrFalse *bool = &dstPtrFalse
)

Functions

func AugpathToFspath

func AugpathToFspath(augPath string) (fsPath string, err error)

AugpathToFspath returns the filesystem path (i.e. an existing file) from an Augeas path.

It is *required* and expected that the Augeas standard /files prefix be removed first; if not, it is assumed to be part of the filesystem path.

If a valid path cannot be determined, fsPath will be empty.

To be clear, a file must exist for fsPath to not be empty; the way AugpathToFsPath works is it recurses bottom-up a given path and checks for the existence of a file, continuing upwards if not found.

Types

type Aug

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

Aug is a wrapper around (honnef.co/go/)augeas.Augeas. Remember to call Aug.Close().

func NewAuger

func NewAuger(root, loadPath string, flags *AugFlags) (aug *Aug, err error)

NewAuger returns an auger.Aug.

See:

https://pkg.go.dev/honnef.co/go/augeas#readme-examples
https://pkg.go.dev/honnef.co/go/augeas#New

for the `root` and `loadPath` parameters (and, by extension, the `flags` paraemter; note that the `flags` is an auger.AugFlags, not an augeas.Flag!).

`flags` may be nil.

func NewAugerFromAugeas

func NewAugerFromAugeas(orig augeas.Augeas) (aug *Aug)

NewAugerFromAugeas returns a wrapped auger.Aug from a (honnef.co/go/augeas).Augeas.

func (*Aug) Close

func (a *Aug) Close()

Close cleanly closes the underlying Augeas connection.

func (*Aug) Interact

func (a *Aug) Interact() (err error)

Interact provides an interactive shell-like interface for debugging purposes to explore the loaded Augeas tree.

func (*Aug) RecursiveInclude

func (a *Aug) RecursiveInclude(augLens, includeDirective, fsRoot string, optFlags ...includeOpt) (err error)

RecursiveInclude parses the configuration files belonging to Augeas lens name augLens, searching for all occurrences of includeDirective, loading those files (if they exist), and continuing so forth recursively, loading them into the Augeas file tree.

If any relative paths are found, they will be assumed to be relative to fsRoot ("/" if empty). For e.g. Nginx, you almost absolutely want to set this to "/etc/nginx", but you really should use absolute paths for every include in your configs if supported by the application; it will lead to much less guesswork and much more accurate recursing/walking.

Some lens recursively load depending on their respective include directive(s) automatically; some (such as the Nginx lens) do not.

For example for Nginx, augLens should be "Nginx". RecursiveInclude will then iterate over /augeas/load/Nginx/incl (/augeas/load/<augLens>/incl), parsing each file for includeDirective (the "include" keyword, in Nginx's case), check if it is already loaded in /augeas/load/<augLens>/incl, adding it and reloading if not, and then scanning *that* file for includeDirective, etc.

An error will be returned if augLens is a nonexistent or not-loaded Augeas lens module.

Depending on how many files there are and whether globs vs. explicit filepaths are included, this may take a while.

optFlags may be nil, multiple includeOpt (see the IncludeOpt* constants) as variadic parameters/expanded slice, bitwise-OR'd together, or multiple non-OR'd and OR'd together (all will be combined to a single value).

type AugFlags

type AugFlags struct {
	/*
		Backup, if true, will enable Augeas backup mode (original files are saved with a .augsave suffix).
		const: augeas.SaveBackup
	*/
	Backup *bool `toml:"Backup,omitempty"`
	/*
		NewFile, if true, will create new files (.augnew suffix) instead of overwriting the original file.
		const: augeas.SaveNewFile
	*/
	NewFile *bool `toml:"NewFile,omitempty"`
	/*
		TypeCheck, if true, will perform a Lens typecheck.
		HIGHLY UNRECOMMENDED; WILL INDUCE A HUGE FRONTLOAD.
		const: augeas.TypeCheck
	*/
	TypeCheck *bool `toml:"TypeCheck,omitempty"`
	/*
		NoDfltModLoad, if true, will suppress loading the built-in/default modules.
		Highly unrecommended, as we do not have a current way in the config to define load paths (yet).
		const: augeas.NoStdinc
	*/
	NoDfltModLoad *bool `toml:"NoDfltModLoad,omitempty"`
	/*
		DryRun, if true, will make all saves NO-OPs.
		const: augeas.SaveNoop
	*/
	DryRun *bool `toml:"DryRun,omitempty"`
	/*
		NoTree, if true, will not load the filetree automatically. Doesn't really affect this program.
		const: augeas.NoLoad
	*/
	NoTree *bool `toml:"NoTree,omitempty"`
	/*
		NoAutoModLoad, if true, will supress automatically loading modules.
		const: augeas.NoModlAutoload
	*/
	NoAutoModLoad *bool `toml:"NoAutoModLoad,omitempty"`
	/*
		EnableSpan, if true, will track span in input nodes (location information, essentially).
		See https://augeas.net/docs/api.html#getting-the-span-of-a-node-related-to-a-file
		const: augeas.EnableSpan
	*/
	EnableSpan *bool `toml:"EnableSpan,omitempty"`
	/*
		NoErrClose, if true, will suppress automatically closing on error.
		const: augeas.NoErrClose
	*/
	NoErrClose *bool `toml:"NoErrClose,omitempty"`
}

AugFlags contains flags to pass to the Augeas instance.

func (*AugFlags) Eval

func (a *AugFlags) Eval() (augFlags augeas.Flag)

Eval returns an evaluated set of flags.