adddir

Documentation

Overview

Package adddir resolves the additional directories of one session: the repeatable --add-dir flag and the SUGA_ADD_DIRS environment variable, both "<absolute directory>[:ro|:rw]" (default :ro), plus the set a session already carries in its metadata.

Index

• Constants
• func Equal(a, b []Dir) bool
• func Expand(path string) string
• func Has(dirs []Dir, path string) bool
• func IsAbsPath(path string) bool
• func IsSource(value string) bool
• func StripMode(value string) string
• func ToMeta(dirs []Dir) []map[string]any
• type Dir
  • func Effective(dirs []Dir, readOnly bool) []Dir
  • func Entry(value string) (Dir, error)
  • func Find(dirs []Dir, path string) (Dir, bool)
  • func FromMeta(value any) ([]Dir, error)
  • func Merge(stored, added []Dir) []Dir
  • func Parse(values []string) ([]Dir, error)
  • func ParseEnv(value string) ([]Dir, []string)
  • func Resolve(values []string, env string, readOnly bool) ([]Dir, []string, error)
  • func Without(dirs []Dir, path string) []Dir

Constants

const (
	// SourceFlag: the --add-dir values of the invocation.
	SourceFlag = "flag"
	// SourceEnv: the SUGA_ADD_DIRS entries of the invocation.
	SourceEnv = "env"
	// SourceSession: typed in chat (:add-dir).
	SourceSession = "session"
	// SourceAsk: authorized at an outside-directory question in chat.
	SourceAsk = "ask"
)

Sources of an added directory: where it entered the session. The value is stored with the entry (ToMeta) so :dirs can still name the origin after a restart; an entry of an older session has none.

const EnvVar = "SUGA_ADD_DIRS"

EnvVar is the environment variable an outer tool (a job runner) uses instead of the flag: os.PathListSeparator separated entries in the value form of --add-dir.

const MetaKey = "add_dirs"

MetaKey is the session metadata key holding the session's added directories: a list of {path, mode} objects.

Functions

func Equal

func Equal(a, b []Dir) bool

Equal reports whether two sets name the same paths in the same order with the same modes and sources, i.e. whether the session metadata has to be rewritten.

func Expand

func Expand(path string) string

Expand cleans a path and expands a leading "~", like Entry and the file tools do.

func Has

func Has(dirs []Dir, path string) bool

Has reports whether path is one of dirs.

func IsAbsPath

func IsAbsPath(path string) bool

IsAbsPath reports whether path names an absolute location once "~" is expanded.

func IsSource

func IsSource(value string) bool

IsSource reports whether value names where a directory came from (one of the Source* constants).

func StripMode

func StripMode(value string) string

StripMode removes a trailing ":ro"/":rw" mode from a value and trims the spaces around what is left. Only a trailing mode counts, the same rule Entry applies; a command that revokes a directory accepts such a value too, because it is copied from a listing that shows the mode.

func ToMeta

func ToMeta(dirs []Dir) []map[string]any

ToMeta renders the set for the session metadata (MetaKey): {path, mode} and, when known, where the directory came from (source).

Types

type Dir

type Dir struct {
	Path     string
	Writable bool
	Source   string
}

Dir is one additional directory of a session. Path is absolute and cleaned; Writable is the :rw mode (:ro, the default, is readable but not writable). Source is one of the Source* constants ("" when unknown, e.g. a session written by an older version).

func Effective

func Effective(dirs []Dir, readOnly bool) []Dir

Effective applies a run mode to the set: a read-only run has no write tool at all, so every directory is reported read-only (the source is kept: it says where the directory came from, not what may be done with it).

func Entry

func Entry(value string) (Dir, error)

Entry parses one --add-dir value (or one SUGA_ADD_DIRS item): "<absolute directory>[:ro|:rw]", default :ro. Only a trailing ":ro"/":rw" counts as a mode, so a Windows drive letter ("D:\docs") keeps its colon. "~" is expanded like tools.read_roots does, and the directory must exist.

func Find

func Find(dirs []Dir, path string) (Dir, bool)

Find returns the entry of dirs for path; ok is false when path is not in the set.

func FromMeta

func FromMeta(value any) ([]Dir, error)

FromMeta reads the stored set back: the list ToMeta wrote, as the JSON store hands it over ([]any of objects). An absent value is an empty set; a malformed one is an error the caller reports and then ignores.

func Merge

func Merge(stored, added []Dir) []Dir

Merge combines the directories a session already carries with the ones given now: the stored order is kept, a stored path given again takes the new mode, and paths only given now are appended in order.

func Parse

func Parse(values []string) ([]Dir, error)

Parse parses --add-dir values: every entry must be valid, because the user typed it just now.

func ParseEnv

func ParseEnv(value string) ([]Dir, []string)

ParseEnv parses SUGA_ADD_DIRS: entries separated by os.PathListSeparator. A bad entry cannot be fixed by the user of this process, so it is reported as a warning and skipped instead of failing the start.

func Resolve

func Resolve(values []string, env string, readOnly bool) ([]Dir, []string, error)

Resolve parses the --add-dir values and SUGA_ADD_DIRS of this invocation into the directories to record for the session, flag entries first. A bad flag value is an error. The read-only run mode is reported as a warning: the session keeps the requested mode and Effective makes the run read-only.

func Without

func Without(dirs []Dir, path string) []Dir

Without returns dirs without path, keeping the order of the rest. It is how chat's :rm-dir revokes a directory.