name

Documentation

Overview

Package name is dstow's pure naming grammar: parse and format fully qualified names (FQNs), percent-encode and -decode coordinate segments, resolve segment-boundary suffix matches, force package-kind with a leading "::", and classify an operand as a path or a name expression.

The grammar is scheme:coordinate::package (DESIGN.md §1). A repo drops the "::package" tail. ":" separates only the scheme; "::" separates only the package; every reserved byte percent-encodes (§1.2) so every path is spellable. The package is pure (A7): zero I/O, zero dependencies, stdlib only, and nothing OS-dependent — just string and byte functions.

Index

• func Decode(segment string) (string, error)
• func Encode(segment string) string
• func IsPathOperand(s string) bool
• func ShortestUnique(fqns []FQN) []string
• type Expr
  • func ParseExpr(s string) (Expr, error)
  • func (e Expr) Matches(f FQN) bool
• type FQN
  • func ParseFQN(s string) (FQN, error)
  • func (f FQN) IsPackage() bool
  • func (f FQN) Repo() FQN
  • func (f FQN) String() string
• type ParseError
  • func (e *ParseError) Error() string

Functions

func Decode

func Decode(segment string) (string, error)

Decode reverses Encode. It accepts "%XX" with hex of either case (and accepts sequences that did not need encoding, e.g. "%41"), and errors on a "%" not followed by two hex digits.

func Encode

func Encode(segment string) string

Encode percent-encodes one decoded segment into canonical form. It is byte-oriented over the UTF-8 string: each reserved byte becomes "%XX" with uppercase hex; every other byte (including UTF-8 multibyte sequences) passes through untouched.

func IsPathOperand

func IsPathOperand(s string) bool

IsPathOperand reports whether s is a path operand per §1.3: it starts with "/", "~/", "./", or "../". Everything else is a name expression. Exactly those four prefixes — no more, no less (so ".", "..", "~", and ".bashrc" are name expressions).

func ShortestUnique

func ShortestUnique(fqns []FQN) []string

ShortestUnique returns, for each FQN in fqns, the shortest name-expression spelling that resolves uniquely to that FQN within the set — the O9 display rule (DESIGN.md §1.5: "shortest-unique suffix everywhere by default; full FQN whenever showing a tie"). The result is parallel to the input.

Each FQN's candidate spellings are walked shortest-first along the segment-boundary suffix ladder the naming grammar accepts (§1.1): a package climbs bare-name → coordinate-tail::package → … → full FQN; a repo climbs coordinate-tail → … → full FQN. The first candidate that, read as a name expression, matches exactly one FQN in the set is chosen. The full FQN is always the last rung and is always unique, so every FQN gets a spelling.

Uniqueness is decided with Expr.Matches — the same resolution the CLI uses — so a displayed short name always resolves back to the entity it names. A tie (two identical FQNs) degenerates to the full FQN for both.

This is pure display over the grammar (A7): the local-coordinate "~" abbreviation of §1.5 is a presentation concern that needs the home directory (an OS fact) and is deliberately left to the rendering layer.

Types

type Expr

type Expr struct {
	Scheme     string   // "" when absent
	Segments   []string // decoded coordinate-suffix segments; may be empty only when HasPackage (leading ::)
	HasPackage bool     // a :: tail was present
	Package    string   // decoded; set iff HasPackage
	AtSuffix   string   // reserved @-suffix, opaque, "" when absent
}

Expr is a parsed name expression (user input; possibly a suffix).

func ParseExpr

func ParseExpr(s string) (Expr, error)

ParseExpr parses a name expression: a full or partial coordinate, with an optional scheme, an optional "::package" tail (a leading "::" forces package-kind), and an optional reserved "@" suffix on the coordinate.

func (Expr) Matches

func (e Expr) Matches(f FQN) bool

Matches reports whether the expression names the entity f denotes (f with empty Package is a repo entity, otherwise a package entity). It never errors and embodies no knowledge of which schemes exist — scheme validity is another package's job. Comparison is on decoded values, aligned from the tail.

type FQN

type FQN struct {
	Scheme string // non-empty
	// Coordinate holds decoded /-segments, len >= 1. A LEADING empty segment
	// is legal and represents an absolute-path coordinate
	// (local:/home/x -> ["", "home", "x"]); any other empty segment is invalid.
	Coordinate []string
	Package    string // decoded; "" means this is a repo FQN
}

FQN is a fully qualified name: scheme:coordinate::package. Fields hold DECODED text; String re-encodes canonically.

func ParseFQN

func ParseFQN(s string) (FQN, error)

ParseFQN parses a full canonical FQN (scheme mandatory).

func (FQN) IsPackage

func (f FQN) IsPackage() bool

IsPackage reports whether the FQN names a package (as opposed to a repo).

func (FQN) Repo

func (f FQN) Repo() FQN

Repo returns the same FQN with the ::package tail dropped.

func (FQN) String

func (f FQN) String() string

String returns the canonical percent-encoded form: scheme + ":" + Encode(segments) joined by "/" + ("::" + Encode(package) when Package != "").

type ParseError

type ParseError struct {
	Input  string
	Reason string
}

ParseError is the package's typed error. Every error returned by this package is a *ParseError. Reason is complete prose: what rule the input violates and, where the spec names one, the remedy.

func (*ParseError) Error

func (e *ParseError) Error() string