path

type Builder ¶

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

Builder for normalized pathname strings.

Instead of providing its own API for constructing paths, every Builder is created with an associated decorator for ScopeWalker. This means that Builder can, for example, be used to record the path traversed by Resolve(), similar to Go's filepath.EvalSymlinks() and libc's realpath().

If there is no need to take the state of the file system into account, it's possible to let the Builder decorate VoidScopeWalker. This allows the construction of paths that don't exist (yet). In that case, unnecessary ".." components are retained, as preceding pathname components may refer to symlinks when applied against an actual file system.

func (b *Builder) GetUNIXString() string

func (b *Builder) Join(scopeWalker ScopeWalker) (*Builder, ScopeWalker)

func (b *Builder) ParseScope(scopeWalker ScopeWalker) (next ComponentWalker, remainder RelativeParser, err error)

type Component ¶

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

Component of a pathname. This type is nothing more than a string that is guaranteed to be a valid Unix filename.

func MustNewComponent(name string) Component

func NewComponent(name string) (Component, bool)

func (c Component) String() string

type ComponentWalker ¶

type ComponentWalker interface {
	// OnDirectory is called for every pathname component that must
	// resolve to a directory or a symbolic link to a directory.
	//
	// If the pathname component refers to a directory, this function
	// will return a GotDirectory containing a new ComponentWalker
	// against which successive pathname components can be resolved.
	//
	// If the pathname component refers to a symbolic link, this
	// function will return a GotSymlink containing a ScopeWalker, which
	// can be used to perform expansion of the symbolic link. The
	// Resolve() function will call into OnAbsolute() or OnRelative() to
	// signal whether resolution should continue at the root directory
	// or at the directory that contained the symbolic link.
	OnDirectory(name Component) (GotDirectoryOrSymlink, error)

	// OnTerminal is called for the potentially last pathname
	// component that needs to be resolved. It may resolve to any
	// kind of file.
	//
	// If the pathname component does not refer to a symbolic link,
	// the function will return nil. This causes Resolve() to assume
	// that pathname resolution has completed.
	//
	// If the pathname component refers to a symbolic link, this
	// function will return a GotSymlink, just like OnDirectory()
	// does. This causes Resolve() to continue the resolution
	// process.
	OnTerminal(name Component) (*GotSymlink, error)

	// OnUp is called if a ".." pathname component is observed.
	OnUp() (ComponentWalker, error)
}

ComponentWalker is an interface that is called into by Resolve(). An implementation can use it to capture the path that is resolved. ComponentWalker is called into after determining whether the path is absolute or relative (see ScopeWalker). It is called into once for every pathname component that is processed.

Each of ComponentWalker's methods invalidate the object on which it is called. Additional calls must be directed against the ScopeWalkers and ComponentWalkers yielded by these methods.

var VoidComponentWalker ComponentWalker = voidComponentWalker{}

type ComponentsList ¶

type ComponentsList []Component

ComponentsList is a sortable list of filenames in a directory.

func (l ComponentsList) Len() int

func (l ComponentsList) Less(i, j int) bool

func (l ComponentsList) Swap(i, j int)

type GotDirectory ¶

type GotDirectory struct {
	// Child directory against which resolution should continue.
	Child ComponentWalker

	// Whether Child.OnUp() is guaranteed to refer to the same
	// directory. This information can be used by Builder to remove
	// unnecessary ".." pathname components. This should be set to
	// false if paths are not resolved against a concrete file
	// system to ensure ".." components remain present.
	IsReversible bool
}

GotDirectory is returned by ComponentWalker.OnDirectory(), in case the name corresponds to a directory stored in the current directory.

type GotDirectoryOrSymlink ¶

type GotDirectoryOrSymlink interface {
	// contains filtered or unexported methods
}

GotDirectoryOrSymlink is a union type of GotDirectory and GotSymlink. It is returned by ComponentWalker.OnDirectory(), as that function may return either a directory or symbolic link.

type GotSymlink ¶

type GotSymlink struct {
	// The parent directory of the symbolic link, which is relative
	// to where symlink expansion needs to be performed.
	Parent ScopeWalker

	// The contents of the symbolic link.
	Target Parser
}

GotSymlink is returned by ComponentWalker.OnDirectory() and OnTerminal(), in case the name corresponds to a symbolic link stored in the current directory.

func OnTerminalViaOnDirectory(cw ComponentWalker, name Component) (*GotSymlink, error)

type Parser ¶

type Parser interface {
	ParseScope(scopeWalker ScopeWalker) (next ComponentWalker, remainder RelativeParser, err error)
}

Parser is used by Resolve to parse paths in the resolution. Implementations of ParseScope() should return a new copy of Parser and leave the current instance unmodified. It is permitted to call ParseScope() multiple times.

func MustNewUNIXParser(path string) Parser

func NewLocalParser(path string) (Parser, error)

func NewUNIXParser(path string) (Parser, error)

type RelativeParser ¶

type RelativeParser interface {
	ParseFirstComponent(componentWalker ComponentWalker, mustBeDirectory bool) (next GotDirectoryOrSymlink, remainder RelativeParser, err error)
}

RelativeParser is used by Resolve to parse relative paths in the resolution. Implementations of ParseFirstComponent() should return a new copy of Parser and leave the current instance unmodified. It is permitted to call ParseFirstComponent() multiple times.

type ScopeWalker ¶

type ScopeWalker interface {
	// One of these functions is called right before processing the
	// first component in the path (if any). Based on the
	// characteristics of the path. Absolute paths are handled through
	// OnAbsolute(), and relative paths require OnRelative().
	//
	// These functions can be used by the implementation to determine
	// whether path resolution needs to be relative to the current
	// directory (e.g., working directory or parent directory of the
	// previous symlink encountered) or the root directory.
	//
	// For every instance of ScopeWalker, one of OnAbsolute() or
	// OnRelative() may be called at most once. Resolve() will always
	// call into one of the interface functions for every ScopeWalker
	// presented, though decorators such as
	// VirtualRootScopeWalkerFactory may only call it when the path is
	// known to be valid. Absence of calls to OnAbsolute() or
	// OnRelative() are used to indicate that the provided path does not
	// resolve to a location inside the file
	// system.
	OnAbsolute() (ComponentWalker, error)
	OnRelative() (ComponentWalker, error)
}

ScopeWalker is an interface that is called into by Resolve(). An implementation can use it to capture the path that is resolved. ScopeWalker is called into once for every path that is processed.

var VoidScopeWalker ScopeWalker = voidScopeWalker{}

func NewAbsoluteScopeWalker(componentWalker ComponentWalker) ScopeWalker

func NewLoopDetectingScopeWalker(base ScopeWalker) ScopeWalker

func NewRelativeScopeWalker(componentWalker ComponentWalker) ScopeWalker

type Stringer ¶

type Stringer interface {
	GetUNIXString() string
}

Stringer is implemented by path types in this package that can be converted to string representations.

type TerminalNameTrackingComponentWalker ¶

type TerminalNameTrackingComponentWalker struct {
	TerminalName *Component
}

TerminalNameTrackingComponentWalker can be embedded into an implementation of ComponentWalker to provide a default implementation of the OnTerminal() method. OnTerminal() is implemented in such a way that it simply tracks the name.

This implementation is useful for ComponentWalkers that are used to create new files or directories.

func (cw *TerminalNameTrackingComponentWalker) OnTerminal(name Component) (*GotSymlink, error)

type Trace ¶

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

Trace of a path.

This type can be used to construct normalized relative pathnames. Traces are immutable, though it is possible to append pathname components to them.

A nil pointer corresponds to path ".".

func (t *Trace) Append(component Component) *Trace

func (t *Trace) GetUNIXString() string

type VirtualRootScopeWalkerFactory ¶

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

VirtualRootScopeWalkerFactory is a factory for decorators for ScopeWalker that place them at a path inside of a virtual file system hierarchy, potentially consisting of one or more symlinks pointing to it.

This type can be used to ensure symlink expansion works properly in case the root of the directory hierarchy that is walked is in reality not the root directory of the system. In this hierarchy there may be symlinks that contain absolute target paths. These can only be resolved properly by trimming one or more leading pathname components.

The underlying implementation of ScopeWalker has the ability to detect whether the resolved path lies inside or outside of the nested directory hierarchy by monitoring whether a ScopeWalker interface method has been called. If this function is called on the wrapped ScopeWalker, but not called on the underlying instance (either initially or after returning a GotSymlink response), the resolved path lies outside the nested root directory.

func NewVirtualRootScopeWalkerFactory(rootPath Parser, aliases map[string]string) (*VirtualRootScopeWalkerFactory, error)

"hello"        -> "hello"
"/root"        -> "/"
"/root/hello"  -> "/hello"
"/alias"       -> "/target"
"/alias/hello" -> "/target/hello"
"/"            -> Nothing
"/hello"       -> Nothing

func (wf *VirtualRootScopeWalkerFactory) New(base ScopeWalker) ScopeWalker