pick

Documentation

Overview

Package pick evaluates `pick=` expressions: how a single value or a single contiguous range is taken out of a bound block (docs/SPEC.md §10).

The rule that keeps this from becoming a scripting language: a pick returns exactly one line (a Value) or one contiguous range (a Range). No transforms, no arithmetic, no joins. Display formatting belongs to the cite side.

Tiers implemented here, all stdlib: the text vocabulary (`line`, `regex`, `url`, `after`, `between`), the document vocabulary over markdown (`heading`, `section`, `paragraph`, `link`), the structured vocabulary for formats that need no dependency (`json`, `env`, `ini`, `csv`, and line-mode `yaml` and `toml` for the common flat and nested-map cases), and `file`. `symbol:` needs a grammar and is answered with ErrUnsupported so the syntax tier in ext/treesitter can claim it. A picker plugin (Picker interface in the root package) may override any scheme.

Index

• Constants
• Variables
• func KeyValue(line string) (string, bool)
• func SplitScheme(expr string) (scheme, arg string)
• type Expr
  • func Parse(expr string) (Expr, error)
  • func (e Expr) Apply(content string) (Result, error)
• type Kind
• type Picker
• type Result
  • func Pick(expr, content string) (Result, error)
  • func PickWith(pickers map[string]Picker, expr, content string) (Result, error)

Constants

const (
	SchemeLine      = "line"
	SchemeRegex     = "regex"
	SchemeURL       = "url"
	SchemeAfter     = "after"
	SchemeBetween   = "between"
	SchemeHeading   = "heading"
	SchemeSection   = "section"
	SchemeParagraph = "paragraph"
	SchemeLink      = "link"
	SchemeJSON      = "json"
	SchemeEnv       = "env"
	SchemeINI       = "ini"
	SchemeCSV       = "csv"
	SchemeYAML      = "yaml"
	SchemeTOML      = "toml"
	SchemeFile      = "file"
	SchemeSymbol    = "symbol"
)

Scheme names. Kept as constants so the dispatcher, the docs, and the conformance fixtures agree on spelling.

Variables

var (
	// ErrBadExpr is a malformed expression: unknown scheme, missing argument,
	// bad number, invalid regex.
	ErrBadExpr = errors.New("pick: bad expression")
	// ErrNotFound means the expression is valid but nothing in the content
	// matched. `check` reports this as `pick failed`.
	ErrNotFound = errors.New("pick: nothing matched")
	// ErrMultiLine means a value-producing pick yielded more than one line,
	// which the one-line rule forbids; the caller should use a Range pick or
	// cite with ds:block.
	ErrMultiLine = errors.New("pick: value spans more than one line; use ds:block")
	// ErrUnsupported means the scheme needs an extractor this package does not
	// have (a grammar). Plugins answer it; the root reports it honestly.
	ErrUnsupported = errors.New("pick: scheme not supported without a plugin")
)

Sentinel errors.

var Schemes = []string{SchemeLine, SchemeRegex, SchemeURL, SchemeAfter, SchemeBetween, SchemeHeading, SchemeSection, SchemeParagraph, SchemeLink, SchemeJSON, SchemeEnv, SchemeINI, SchemeCSV, SchemeYAML, SchemeTOML, SchemeFile, SchemeSymbol}

Schemes is the canonical list, in the order the spec table presents them.

Functions

func KeyValue

func KeyValue(line string) (string, bool)

KeyValue returns the value part of a `key: value` or `key = value` line with any inline comment and one layer of quotes removed. It is the default pick for config hosts (§10): the visible value, not the key line, is what a fact means. ok is false when the line has no separator.

func SplitScheme

func SplitScheme(expr string) (scheme, arg string)

SplitScheme separates `scheme:arg`; a bare word is a scheme with no arg.

Types

type Expr

type Expr struct {
	Scheme string
	Arg    string
}

Expr is a parsed expression: scheme plus its raw argument, quotes removed.

func Parse

func Parse(expr string) (Expr, error)

Parse splits `scheme:arg` and strips optional single or double quotes from the argument. `heading`, `url`, and `file` take no argument.

func (Expr) Apply

func (e Expr) Apply(content string) (Result, error)

Apply evaluates a parsed expression.

CRLF is read as LF. The scanner hands over a file's raw bytes, and a Windows checkout with core.autocrlf has \r on every line: `line:2` then failed as spanning two lines and a `$`-anchored regex matched nothing, so one repository resolved differently depending on who checked it out.

type Kind

type Kind string

Kind says whether a Result is a one-line value or a line range.

const (
	// KindValue is a single line, what `ds:cfg` inlines.
	KindValue Kind = "value"
	// KindRange is one or more contiguous lines, what `ds:block` renders.
	KindRange Kind = "range"
)

type Picker

type Picker func(arg, content string) (Result, error)

Picker is a plugin scheme (§37.3): given the argument after the colon and the block content, it returns a value or a range.

type Result

type Result struct {
	Kind  Kind
	Value string
	Text  string
	Start int
	End   int
}

Result is what a pick produced. For KindValue, Value is set and Start==End. For KindRange, Text is the joined lines. Start and End are 1-based line numbers within the content handed to Pick, inclusive, so a caller that knows where the content began in its file can add the offset.

func Pick

func Pick(expr, content string) (Result, error)

Pick evaluates expr against content and applies the one-line rule for value schemes. Line numbers in the Result are relative to content.

func PickWith

func PickWith(pickers map[string]Picker, expr, content string) (Result, error)

PickWith applies a registered Picker when the scheme names one, otherwise the built-in schemes. Plugins never shadow built-ins: a registered scheme with a built-in name is ignored, so `json:` always means the same thing.