store

Documentation

Overview

Package store holds scenario variables and performs ${name} expansion. Expansion is deliberately simple substitution — atago is not a programming language.

Index

• func Escape(s string) string
• type Store
  • func New() *Store
  • func (s *Store) Expand(in string) string
  • func (s *Store) ExpandDetectingLeaks(in string) (string, []string)
  • func (s *Store) ExpandMap(m map[string]string) map[string]string
  • func (s *Store) Get(name string) (string, bool)
  • func (s *Store) Set(name, value string)
  • func (s *Store) Unresolved(in string) []string

Functions

func Escape

func Escape(s string) string

Escape rewrites text so that Expand returns it verbatim: it prefixes an extra `$` onto exactly the references Expand acts on — a live `${name}` becomes the literal `$${name}`, and an already-escaped `$${name}` becomes `$$${name}` — while a `${` that Expand ignores (one not followed by a valid name, e.g. `${1}` or `${}`) is left untouched, because Expand would already pass it through. It is the exact inverse Expand relies on, so raw observed text (a recorded command, output anchor, or typed pty input) can be embedded in a spec without being re-expanded at replay. A blind `${`→`$${` rewrite is wrong: the expander only unescapes `$${<valid-name>}`, so `$${1}` would never round-trip back to the observed `${1}`.

Types

type Store

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

Store is a per-scenario variable map.

func New

func New() *Store

New returns an empty Store.

func (*Store) Expand

func (s *Store) Expand(in string) string

Expand replaces ${name} references with stored values and ${env:NAME} references with host environment variables. Unknown references are left verbatim so they surface as obvious failures rather than empty strings.

func (*Store) ExpandDetectingLeaks

func (s *Store) ExpandDetectingLeaks(in string) (string, []string)

ExpandDetectingLeaks expands in like Expand, and additionally reports the names of any ${...} references that a *substituted value* carries into the output. Expansion is deliberately single-pass (see Expand): a reference that a store/matrix value contains is never re-examined, so it survives verbatim into the result — and, for a no-shell run.command, into argv, where nothing will ever expand it. Reporting these lets the run guard refuse the garbled command instead of leaking the literal text (#249).

Only references introduced by a substituted value are reported. A reference the author wrote directly in in is not (an unresolved one is already the pre-expansion guard's job, and a resolved one expands normally), and an escaped $${name} — in the input or inside a substituted value — is a deliberate literal, never a leak.

func (*Store) ExpandMap

func (s *Store) ExpandMap(m map[string]string) map[string]string

ExpandMap returns a copy of m with all values expanded.

func (*Store) Get

func (s *Store) Get(name string) (string, bool)

Get returns a variable and whether it was set.

func (*Store) Set

func (s *Store) Set(name, value string)

Set assigns a variable.

func (*Store) Unresolved

func (s *Store) Unresolved(in string) []string

Unresolved returns the names of ${name} references in in that no stored variable resolves, and of ${env:NAME} references whose environment variable is not set. Escaped $${name} literals are not reported — the author explicitly asked for literal text. Callers use this to turn a reference that nothing could ever expand into an explained failure instead of passing the literal text on.