common

Documentation

Index

• Constants
• Variables
• func CelCompileAndEval(ctx context.Context, scope *Scope, expr model.String, outPtr any) error
• func Copy(ctx context.Context, fs FS, src, dst string) error
• func CopyFile(ctx context.Context, pos *model.ConfigPos, rfs FS, src, dst string, ...) (outErr error)
• func CopyRecursive(ctx context.Context, pos *model.ConfigPos, p *CopyParams) (outErr error)
• func Exists(path string) (bool, error)
• func ExistsFS(fs FS, path string) (bool, error)
• func FirstNonZero[T comparable](s ...T) T
• func HasDotDot(path string) bool
• func IsCELUndeclaredRef(err error) (string, bool)
• func IsNotExistErr(err error) bool
• func IsReservedInDest(relPath string) bool
• func IsReservedStdout(relPath string) bool
• func JoinIfRelative(cwd, path string) string
• func SafeRelPath(pos *model.ConfigPos, p string) (string, error)
• type CopyHint
• type CopyParams
• type CopyVisitor
• type ErrorFS
  • func (e *ErrorFS) MkdirAll(name string, mode fs.FileMode) error
  • func (e *ErrorFS) Open(name string) (fs.File, error)
  • func (e *ErrorFS) OpenFile(name string, flag int, mode os.FileMode) (*os.File, error)
  • func (e *ErrorFS) ReadFile(name string) ([]byte, error)
  • func (e *ErrorFS) RemoveAll(name string) error
  • func (e *ErrorFS) Stat(name string) (fs.FileInfo, error)
  • func (e *ErrorFS) WriteFile(name string, data []byte, perm os.FileMode) error
• type ExitCodeError
  • func (e *ExitCodeError) Error() string
  • func (e *ExitCodeError) Unwrap() error
• type FS
• type RealFS
  • func (r *RealFS) MkdirAll(name string, perm os.FileMode) error
  • func (r *RealFS) MkdirTemp(dir, pattern string) (string, error)
  • func (r *RealFS) Open(name string) (fs.File, error)
  • func (r *RealFS) OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)
  • func (r *RealFS) ReadFile(name string) ([]byte, error)
  • func (r *RealFS) Remove(name string) error
  • func (r *RealFS) RemoveAll(name string) error
  • func (r *RealFS) Rename(from, to string) error
  • func (r *RealFS) Stat(name string) (fs.FileInfo, error)
  • func (r *RealFS) WriteFile(name string, data []byte, perm os.FileMode) error
• type Scope
  • func NewScope(vars map[string]string, goTmplFuncs map[string]any) *Scope
  • func (s *Scope) AllVars() map[string]string
  • func (s *Scope) GoTmplFuncs() map[string]any
  • func (s *Scope) Lookup(name string) (string, bool)
  • func (s *Scope) With(m map[string]string) *Scope
• type SymlinkForbiddenError
  • func (e *SymlinkForbiddenError) Error() string

Constants

const (
	// Permission bits: rwx------ .
	OwnerRWXPerms = 0o700
	// Permission bits: rw------- .
	OwnerRWPerms = 0o600
)

const (
	ABCInternalDir    = ".abc"
	ABCInternalStdout = "stdout"
)

ABCInternalDir is the name for internal directories that have things like manifests and .gitkeep files. These may be destination directories or golden-test data/ directories.

Variables

var DoNotModifyHeader = []byte("# Generated by the \"abc\" command. Do not modify.\n")

Functions

func CelCompileAndEval

func CelCompileAndEval(ctx context.Context, scope *Scope, expr model.String, outPtr any) error

celCompileAndEval parses, compiles, and executes the given CEL expr with the given variables in scope.

The output of CEL execution is written into the location pointed to by outPtr. It must be a pointer. If the output of the CEL expression can't be converted to the given type, then an error will be returned. For example, if the CEL expression is "hello" and outPtr points to an int, an error will returned because CEL cannot treat "hello" as an integer.

func Copy

func Copy(ctx context.Context, fs FS, src, dst string) error

Copy copies the file src to dst. It's a wrapper around CopyFile that hides unneeded arguments.

func CopyFile

func CopyFile(ctx context.Context, pos *model.ConfigPos, rfs FS, src, dst string, dryRun bool, tee io.Writer) (outErr error)

CopyFile copies the contents of src to dst. src and dst are filenames, not directories.

If the target directory doesn't exist, it will be automatically created.

tee is nil-able. If not nil, it will be written to with the file contents.

func CopyRecursive

func CopyRecursive(ctx context.Context, pos *model.ConfigPos, p *CopyParams) (outErr error)

CopyRecursive recursively copies a directory to another directory.

If the source directory contains a symlink, then SymlinkForbiddenError will be returned.

func Exists

func Exists(path string) (bool, error)

Exists returns whether the given path is a file or directory that exists. We wrote this wrapper because it's a little complex and irritating to deal with the way that os.Stat() considers nonexistence to be an error.

func ExistsFS

func ExistsFS(fs FS, path string) (bool, error)

Exists is like Exists, but takes a FS as a parameter for error injection.

func FirstNonZero

func FirstNonZero[T comparable](s ...T) T

FirstNonZero returns the first element of s that is not the zero value for its type. It returns the zero value if all elements of s are zero or if s is empty.

func HasDotDot

func HasDotDot(path string) bool

HasDotDot returns whether the input path contains any ".." parent directory references, so they can be rejected in certain cases.

func IsCELUndeclaredRef

func IsCELUndeclaredRef(err error) (string, bool)

Detects whether the given error, which should come from the CEL Compile() function, is an error indicating a reference to a nonexistent variable. This can happen when, for example, the CEL expr was "x == 5" but x doesn't exist.

func IsNotExistErr

func IsNotExistErr(err error) bool

IsNotExistErr takes an error returned by os.Stat() and returns true if the error means "the path you stat'ed doesn't exist." It otherwise returns false.

func IsReservedInDest

func IsReservedInDest(relPath string) bool

IsReservedInDest returns true if the given path cannot be created in the destination directory because that name is reserved for internal purposes.

The input path must use the local OS separators, since we process it with filepath. This path is relative to the destination directory.

func IsReservedStdout

func IsReservedStdout(relPath string) bool

IsReservedStdout returns true if the given path is the internal stdout path.

The input path must use the local OS separators, since we process it with filepath. This path is relative to the destination directory.

func JoinIfRelative

func JoinIfRelative(cwd, path string) string

JoinIfRelative returns path if it's an absolute path, otherwise filepath.Join(cwd, path).

func SafeRelPath

func SafeRelPath(pos *model.ConfigPos, p string) (string, error)

SafeRelPath returns an error if the path contains a ".." traversal, and converts it to a relative path by removing any leading "/".

Types

type CopyHint

type CopyHint struct {
	// Before overwriting a file in the destination dir, copy the preexisting
	// contents of the file into ~/.abc/$timestamp. Only used if
	// overwrite==true.
	//
	// This has no effect on directories, only files.
	BackupIfExists bool

	// AllowPreexisting prevents CopyRecursive from returning error when copying
	// over an existing file. The default is to conservatively fail.
	//
	// This has no effect on directories, only files.
	AllowPreexisting bool

	// Whether to skip this file or directory (don't write it to the
	// destination). For directories, this will cause all files underneath the
	// directory to be skipped.
	Skip bool
}

type CopyParams

type CopyParams struct {
	// backupDirMaker will be called when we reach the first file that actually
	// needs to be backed up. It should create a directory and return its path,
	// either relative to the cwd or absolute. Use os.MkdirTemp() in real code
	// and something hardcoded in tests.
	BackupDirMaker func(FS) (string, error)

	// DryRun skips actually copying anything, just checks whether the copy
	// would be likely to succeed.
	DryRun bool

	// DstRoot is the output directory. May be absolute or relative.
	DstRoot string

	// SrcRoot is the file or directory from which to copy. May be absolute or
	// relative.
	SrcRoot string

	// FS is the filesytem to use.
	FS FS

	// visitor is an optional function that will be called for each file in the
	// source, to allow customization of the copy operation on a per-file basis.
	Visitor CopyVisitor

	// If Hasher and OutHashes are not nil, then each copied file will be hashed
	// and the hex hash will be saved in OutHashes. If a file is "skipped"
	// (CopyHint.Skip==true) then the hash will not be computed. In dry run
	// mode, the hash will be computed normally.
	Hasher    func() hash.Hash
	OutHashes map[string][]byte
}

CopyParams contains most of the parameters to CopyRecursive(). There were too many of these, so they've been factored out into a struct to avoid having the function parameter list be really long.

type CopyVisitor

type CopyVisitor func(relPath string, de fs.DirEntry) (CopyHint, error)

CopyVisitor is the type for callback functions that are called by CopyRecursive for each file and directory encountered. It gives the caller an opportunity to influence the behavior of the copy operation on a per-file basis, and also informs the of each file and directory being copied.

type ErrorFS

type ErrorFS struct {
	FS

	MkdirAllErr  error
	OpenErr      error
	OpenFileErr  error
	ReadFileErr  error
	RemoveAllErr error
	StatErr      error
	WriteFileErr error
}

A renderFS implementation that can inject errors for testing.

func (*ErrorFS) MkdirAll

func (e *ErrorFS) MkdirAll(name string, mode fs.FileMode) error

func (*ErrorFS) Open

func (e *ErrorFS) Open(name string) (fs.File, error)

func (*ErrorFS) OpenFile

func (e *ErrorFS) OpenFile(name string, flag int, mode os.FileMode) (*os.File, error)

func (*ErrorFS) ReadFile

func (e *ErrorFS) ReadFile(name string) ([]byte, error)

func (*ErrorFS) RemoveAll

func (e *ErrorFS) RemoveAll(name string) error

func (*ErrorFS) Stat

func (e *ErrorFS) Stat(name string) (fs.FileInfo, error)

func (*ErrorFS) WriteFile

func (e *ErrorFS) WriteFile(name string, data []byte, perm os.FileMode) error

type ExitCodeError

type ExitCodeError struct {
	Code int
	Err  error
}

An implementation of error that contains an command exit status. This is intended to be returned from a Run() function when a command wants to return a specific error code to the OS.

func (*ExitCodeError) Error

func (e *ExitCodeError) Error() string

func (*ExitCodeError) Unwrap

func (e *ExitCodeError) Unwrap() error

type FS

type FS interface {
	fs.StatFS

	// These methods correspond to methods in the "os" package of the same name.
	MkdirAll(string, os.FileMode) error
	MkdirTemp(string, string) (string, error)
	OpenFile(string, int, os.FileMode) (*os.File, error)
	ReadFile(string) ([]byte, error)
	Rename(string, string) error
	Remove(string) error
	RemoveAll(string) error
	WriteFile(string, []byte, os.FileMode) error
}

Abstracts filesystem operations.

We can't use os.DirFS or fs.StatFS because they lack some methods we need. So we created our own interface.

type RealFS

type RealFS struct{}

This is the non-test implementation of the filesystem interface.

func (*RealFS) MkdirAll

func (r *RealFS) MkdirAll(name string, perm os.FileMode) error

func (*RealFS) MkdirTemp

func (r *RealFS) MkdirTemp(dir, pattern string) (string, error)

func (*RealFS) Open

func (r *RealFS) Open(name string) (fs.File, error)

func (*RealFS) OpenFile

func (r *RealFS) OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)

func (*RealFS) ReadFile

func (r *RealFS) ReadFile(name string) ([]byte, error)

func (*RealFS) Remove

func (r *RealFS) Remove(name string) error

func (*RealFS) RemoveAll

func (r *RealFS) RemoveAll(name string) error

func (*RealFS) Rename

func (r *RealFS) Rename(from, to string) error

func (*RealFS) Stat

func (r *RealFS) Stat(name string) (fs.FileInfo, error)

func (*RealFS) WriteFile

func (r *RealFS) WriteFile(name string, data []byte, perm os.FileMode) error

type Scope

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

scope binds variable names to values. It has a stack-like structure that allows inner scopes to inherit values from outer scopes. Variable names are looked up in order of innermost-to-outermost.

For example, a for_each action defines a key value that is assigned to each of a list of values. The new variable introduced in this way "shadows" any variable that may previously exist of the same name. When the for_each loop is finished, then the outer scope's variable becomes available again.

func NewScope

func NewScope(vars map[string]string, goTmplFuncs map[string]any) *Scope

func (*Scope) AllVars

func (s *Scope) AllVars() map[string]string

AllVars returns all variable bindings that are in scope. Inner/top-of-stack bindings take priority over outer bindings of the same name.

The returned map is a copy that is owned by the caller; it can be changed safely.

The return value is never nil.

func (*Scope) GoTmplFuncs

func (s *Scope) GoTmplFuncs() map[string]any

GoTmplFuncs returns all the Go-template functions that are in scope. The result is suitable for passing to text/template.Template.Funcs().

func (*Scope) Lookup

func (s *Scope) Lookup(name string) (string, bool)

Lookup returns the current value of a given variable name, or false.

func (*Scope) With

func (s *Scope) With(m map[string]string) *Scope

With returns a new scope containing a new set of variable values. It forwards lookups to the previously existing scope if the lookup key is not found in m.

type SymlinkForbiddenError

type SymlinkForbiddenError struct {
	// The relative path where the symlink was found. Relative to SrcRoot.
	Path string
}

SymlinkForbiddenError is the error returned from CopyRecursive when a symlink is encountered in the source directory.

func (*SymlinkForbiddenError) Error

func (e *SymlinkForbiddenError) Error() string