parser

package
v0.32.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 9, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const HelpText = `` /* 2213-byte string literal not displayed */

HelpText is the per-verb grammar reference printed by the `help` verb (#436). Single source of truth for the Go REPL; the TypeScript port keeps a byte-equivalent copy at `admin/app/lib/cli/verbs.ts` `HELP_TEXT`, and the shared fixture `admin/test/cli-grammar/verbs.json` exercises both parsers against the bare `help` verb.

The kwarg enums and defaults below MUST stay in lockstep with `IlluminateParam`'s `IlluminateAlgorithms` / `IlluminateReductions` / `IlluminateObjectives` / `IlluminateWeightings` sets and the corresponding TS parser.

Variables

View Source 
var (
	Verbs = []string{
		"get",
		"put",
		"add",
		"delete",
		"scan",
		"count",
		"delete-prefix",
		"keys",
		"bfs",
		"pagerank",
		"community",
		"help",
		"exit",
	}

	Objectives = []string{
		"vertex",
		"edge",
	}

	// ScanObjectives are the plural-form objectives accepted by the
	// `scan` verb. They intentionally do NOT overlap with `Objectives`
	// (singular vertex/edge), which the get/put/delete/add verbs use, so
	// `get vertices` and `scan vertex` are both clean parse errors.
	ScanObjectives = []string{
		"vertices",
		"edges",
	}

	// AddObjectives are the objectives accepted by the `add` verb. Unlike
	// the shared Objectives (vertex/edge, used by get/put/delete), `add`
	// takes only edge forms: the plain additive edge and the client-expanded
	// decaying edge (#952). A dedicated set keeps `add vertex` a clean parse
	// error and stops the decay sugar leaking into get/put/delete grammar.
	AddObjectives = []string{
		"edge",
		"decaying-edge",
	}

	// TraversalReductions / TraversalObjectives / TraversalWeightings are the
	// canonical closed sets the family verbs (bfs / pagerank / community) accept
	// for their keyword arguments (#975). The traversal FAMILY is now the verb
	// itself, not an algorithm= kwarg; the reduction is a per-family knob on
	// bfs/community (never pagerank, whose relevance star is already a tree),
	// mirroring the wire oneof (#846).
	TraversalReductions = []string{"none", "mst", "spt"}
	TraversalObjectives = []string{"min", "max"}
	TraversalWeightings = []string{"raw", "tfidf", "bm25"}

	ErrNotFound = errors.New("not found")
	ErrNotEOF   = errors.New("not EOF")
)
View Source 
var (
	ErrOutOfIndex = errors.New("out of index")
	// ErrUnterminatedString is returned by NewSource when the input
	// contains an unmatched single- or double-quote opener. See #438.
	ErrUnterminatedString = errors.New("unterminated string literal")
)
View Source 
var ErrParse = errors.New("parse error")

Functions

func AddObjective added in v0.30.0 

func AddObjective(s *Source) (string, error)

func AnyOf 

func AnyOf(s *Source, choices []string) (string, error)

AnyOf returns the canonical lowercase choice that matches the next token case-insensitively, or ErrNotFound. The returned value is always one of the entries in `choices` (not the raw token), so downstream switches can compare against the canonical form. This mirrors the Go REPL's existing ToLower-on-dispatch convention and keeps argument tokens (vertex keys, edge endpoints, illuminate seeds) free of case mangling \u2014 see #437.

func Bool 

func Bool(s *Source) (bool, error)

func CoerceValue added in v0.18.0 

func CoerceValue(raw, typ string) (any, error)

CoerceValue converts a raw CLI value token into a Go value for PutVertex, honouring the optional `type=` override (migrated from the noun-first `vertex put --value-type`). "" / "auto" auto-detects (int→float→bool→RFC3339→string); otherwise the named type is forced and a mismatch is an error. `json` parses the token and re-encodes objects / arrays as a compact JSON string (the wire has no nested value variant); json scalars pass through as their natural Go type.

func Datetime 

func Datetime(s *Source) (time.Time, error)

func Duration 

func Duration(s *Source) (time.Duration, error)

func EOF 

func EOF(s *Source) error

func Float 

func Float(s *Source) (float64, error)

func Float32 

func Float32(s *Source) (float32, error)

func Integer 

func Integer(s *Source) (int, error)

func Objective 

func Objective(s *Source) (string, error)

func ScanObjective added in v0.9.0 

func ScanObjective(s *Source) (string, error)

func String 

func String(s *Source) (string, error)

func Validate 

func Validate(input string) error

func Value 

func Value(s *Source) (any, error)

func Verb 

func Verb(s *Source) (string, error)

Types

type AddDecayingEdge added in v0.30.0 

type AddDecayingEdge struct {
	Tail          string
	Head          string
	InitialWeight float32
	Ratio         float32
	Steps         int
	Interval      time.Duration
}

AddDecayingEdge backs `add decaying-edge <tail> <head> <initial_weight> <ratio> <steps> <interval_seconds>`. The fields map 1:1 onto client.DecayOpts: the edge's contributed live weight starts at InitialWeight and is multiplied by Ratio every Interval, reaching zero after Steps intervals. The dispatcher expands it client-side into an AddEdges batch of staggered-TTL contributions — no server support required (#952). Numeric-range validation (Ratio in (0,1), Steps in [1, client.MaxDecaySteps], Interval > 0) is deferred to the SDK, which owns the DecayOpts contract.

func AddDecayingEdgeParam added in v0.30.0 

func AddDecayingEdgeParam(s *Source) (*AddDecayingEdge, error)

AddDecayingEdgeParam parses `add decaying-edge <tail> <head> <initial_weight> <ratio> <steps> <interval_seconds>`. All six positional arguments are required (unlike AddEdgeParam's optional trailing ttl_seconds) because the decay curve is meaningless without every parameter. Numeric-range checks are the SDK's job — this only enforces shape and token types, then EOF so a stray trailing token is a usage error (mirrors AddEdgeParam's #932 trailing-token guard).

type AddEdge 

type AddEdge struct {
	Tail   string
	Head   string
	Weight float32
	TTL    time.Duration
}

func AddEdgeParam 

func AddEdgeParam(s *Source) (*AddEdge, error)

type Bfs added in v0.32.0 

type Bfs struct {
	Seed      string
	Step      int    // walk depth (default 5)
	FanOut    int    // per-hop top-k prune (default 3)
	Reduction string // "none" | "mst" | "spt" (default: "none")
	Objective string // "min" | "max"          (default: "max")
	Weighting string // "raw" | "tfidf" | "bm25" (default: "raw")
	Prefix    string // vertex-key prefix filter; "" (default) = no filter (#604)
}

Bfs backs the bfs family verb (#975): `bfs <seed> [step] [fan_out] [reduction=…] [objective=…] [weighting=…] [prefix=…]`. Step/FanOut are optional positional ints (defaults 5/3) and may also be given as step=/fan_out= kwargs. bfs is the only family with step and reduction knobs.

func BfsParam added in v0.32.0 

func BfsParam(s *Source) (*Bfs, error)

BfsParam parses the bfs family verb (#975): 

bfs <seed> [step] [fan_out] [reduction=none|mst|spt] [objective=min|max] [weighting=raw|tfidf|bm25] [prefix=<string>]

Only <seed> is required. step and fan_out are optional positional integers (defaults 5 and 3) that may also be supplied as step=/fan_out= kwargs; a bare integer fills the next positional slot (step then fan_out). The closed-set kwargs default to reduction=none, objective=max, weighting=raw, and prefix is free-text (empty = no frontier filter, #604). objective steers both the per-hop top-k pruning and the reduction direction (#560). Unknown keywords, a non-integer step/fan_out, out-of-set closed values, an empty prefix=, or a third bare positional are rejected with a descriptive usage hint.

type Community added in v0.32.0 

type Community struct {
	Seed        string
	MaxSize     int     // size upper bound (default 0 = sweep decides)
	RestartProb float32 // restart prob α; 0 (default) = server default 0.15 (#845)
	Epsilon     float32 // residual threshold ε; 0 (default) = server default 1e-4 (#845)
	Reduction   string  // "none" | "mst" | "spt" (default: "none")
	Objective   string  // "min" | "max"          (default: "max")
	Weighting   string  // "raw" | "tfidf" | "bm25" (default: "raw")
	Prefix      string  // vertex-key prefix filter; "" (default) = no filter (#604)
}

Community backs the community family verb (#975): `community <seed> [max_size] [restart_prob=…] [epsilon=…] [reduction=…] [objective=…] [weighting=…] [prefix=…]`. MaxSize is an optional positional int (default 0 = the conductance sweep alone decides the size). RestartProb/Epsilon share PPR's semantics/defaults; reduction/objective render an optional tree view of the community (#845).

func CommunityParam added in v0.32.0 

func CommunityParam(s *Source) (*Community, error)

CommunityParam parses the community family verb (#975): 

community <seed> [max_size] [restart_prob=<float>] [epsilon=<float>] [reduction=none|mst|spt] [objective=min|max] [weighting=raw|tfidf|bm25] [prefix=<string>]

Only <seed> is required. max_size is an optional positional integer (default 0 = the conductance sweep alone decides the size) that may also be supplied as max_size=. restart_prob (α) and epsilon (ε) share PPR's semantics and defaults (0 → server α=0.15 / ε=1e-4). reduction/objective render an optional tree view of the community (default reduction=none, objective=max). weighting defaults to raw; prefix is free-text (empty = no filter).

type CountVertices added in v0.18.0 

type CountVertices struct {
	Prefix string
}

CountVertices backs `count vertices <prefix>` — the prefix-cardinality verb migrated from the former `vertex count` subcommand.

func CountVerticesParam added in v0.18.0 

func CountVerticesParam(s *Source) (*CountVertices, error)

CountVerticesParam parses `count vertices <prefix>` — exactly one prefix (migrated from the `vertex count` subcommand). The objective token ("vertices") has already been consumed by the caller.

type DeleteEdge 

type DeleteEdge struct {
	Pairs []EdgePair
}

DeleteEdge backs `delete edge <tail> <head> [<tail> <head> …]`. Pairs holds one or more (tail, head) pairs (the token count must be even).

func DeleteEdgeParam 

func DeleteEdgeParam(s *Source) (*DeleteEdge, error)

DeleteEdgeParam parses `delete edge <tail> <head> [<tail> <head> …]` — one or more (tail, head) pairs (an even, non-zero token count). A single pair deletes one edge; more than one routes to DeleteEdges.

type DeletePrefixVertices added in v0.18.0 

type DeletePrefixVertices struct {
	Prefix  string
	Limit   int
	DryRun  bool
	Confirm bool
}

DeletePrefixVertices backs `delete-prefix vertices <prefix> [limit=<n>] [confirm=yes|dry_run=true]` — the destructive prefix delete migrated from `vertex delete-prefix`. Exactly one of Confirm / DryRun must be set (the safety gate); a bare `delete-prefix vertices p` is a usage error.

func DeletePrefixVerticesParam added in v0.18.0 

func DeletePrefixVerticesParam(s *Source) (*DeletePrefixVertices, error)

DeletePrefixVerticesParam parses `delete-prefix vertices <prefix> [limit=<int>] [confirm=yes|dry_run=true]`. Exactly one of confirm=yes or dry_run=true is REQUIRED — the destructive-op safety gate; a bare `delete-prefix vertices p` is a usage error. The objective token ("vertices") has already been consumed by the caller.

type DeleteVertex 

type DeleteVertex struct {
	Keys []string
}

DeleteVertex backs `delete vertex <key> [<key> …]`. Keys holds one or more keys; the dispatcher forwards a one-element batch to DeleteVertex and a multi-element batch to DeleteVertices.

func DeleteVertexParam 

func DeleteVertexParam(s *Source) (*DeleteVertex, error)

keys. A one-element batch deletes a single vertex; more than one routes to DeleteVertices in the dispatcher.

type EdgePair added in v0.18.0 

type EdgePair struct {
	Tail string
	Head string
}

EdgePair is one (tail, head) pair in a batch edge delete.

type GetEdge 

type GetEdge struct {
	Tail string
	Head string
}

func GetEdgeParam 

func GetEdgeParam(s *Source) (*GetEdge, error)

type GetVertex 

type GetVertex struct {
	Key string
}

func GetVertexParam 

func GetVertexParam(s *Source) (*GetVertex, error)

type Keys added in v0.17.0 

type Keys struct {
	Prefix string
	Limit  int
}

Keys backs the `keys <prefix> [limit]` verb — the Redis-familiar key lister that lists vertex keys under a prefix (keys-only output). Lantern is a prefix-indexed store, so Prefix is a key PREFIX, not a glob. Limit is optional (0 = server default), mirroring ScanVertices.

func KeysParam added in v0.17.0 

func KeysParam(s *Source) (*Keys, error)

KeysParam parses `keys <prefix> [limit]` — the Redis-familiar key lister. Lantern is a prefix-indexed store, so the argument is a key PREFIX (not a glob): `keys user:` lists every vertex key under "user:". A prefix is required; the optional trailing limit caps the page (0 = server default), mirroring ScanVerticesParam.

type Pagerank added in v0.32.0 

type Pagerank struct {
	Seed        string
	TopN        int     // cap the star to the top-N by mass (default 10; 0 = all)
	RestartProb float32 // restart prob α; 0 (default) = server default 0.15 (#801)
	Epsilon     float32 // residual threshold ε; 0 (default) = server default 1e-4 (#801)
	Weighting   string  // "raw" | "tfidf" | "bm25" (default: "raw")
	Prefix      string  // vertex-key prefix filter; "" (default) = no filter (#604)
}

Pagerank backs the pagerank family verb (#975): `pagerank <seed> [top_n] [restart_prob=…] [epsilon=…] [weighting=…] [prefix=…]`. TopN is an optional positional int (default 10; 0 = every positive-mass vertex). RestartProb/Epsilon default to 0, which the server resolves to α=0.15 / ε=1e-4. Personalized PageRank returns a relevance star, so it has no reduction/objective knob.

func PagerankParam added in v0.32.0 

func PagerankParam(s *Source) (*Pagerank, error)

PagerankParam parses the pagerank family verb (#975): 

pagerank <seed> [top_n] [restart_prob=<float>] [epsilon=<float>] [weighting=raw|tfidf|bm25] [prefix=<string>]

Only <seed> is required. top_n is an optional positional integer (default 10; 0 = every positive-mass vertex) that may also be supplied as top_n=. The locality knobs restart_prob (α) and epsilon (ε) default to 0, which the server resolves to α=0.15 / ε=1e-4. Personalized PageRank returns a relevance star, so it has NO reduction or objective knob — passing either is an unknown-key error. weighting defaults to raw; prefix is free-text (empty = no filter).

type PutEdge 

type PutEdge struct {
	Tail   string
	Head   string
	Weight float32
	TTL    time.Duration
}

func PutEdgeParam 

func PutEdgeParam(s *Source) (*PutEdge, error)

type PutVertex 

type PutVertex struct {
	Key   string
	Value any
	TTL   time.Duration
	Type  string
}

PutVertex backs `put vertex <key> <value> [ttl_seconds] [type=…]`. Type is the optional value-type override migrated from `vertex put --value-type`: "" / "auto" auto-detects (int→float→bool→RFC3339→string); otherwise one of string|int|float|bool|datetime|duration|json.

func PutVertexParam 

func PutVertexParam(s *Source) (*PutVertex, error)

type ScanEdges added in v0.9.0 

type ScanEdges struct {
	TailPrefix string
	HeadPrefix string
	Limit      int
	All        bool
}

ScanEdges backs `scan edges <tail-prefix> [limit] [head=<prefix>] [all=true]`. HeadPrefix narrows the head dimension as a server-side index lookup; All iterates every page.

func ScanEdgesParam added in v0.9.0 

func ScanEdgesParam(s *Source) (*ScanEdges, error)

ScanEdgesParam parses `scan edges <tail-prefix> [limit]`. The objective token ("edges") has already been consumed by the caller. An empty tail-prefix is permitted (scans every tail), matching the server's ScanEdges semantics where both prefixes default to empty.

type ScanVertices added in v0.9.0 

type ScanVertices struct {
	Prefix string
	Limit  int
	All    bool
}

ScanVertices backs `scan vertices <prefix> [limit] [all=true]` (#411, extended in #679). Limit is optional (0 = server default); All iterates every page and renders the full result.

func ScanVerticesParam added in v0.9.0 

func ScanVerticesParam(s *Source) (*ScanVertices, error)

ScanVerticesParam parses `scan vertices <prefix> [limit]`. The objective token ("vertices") has already been consumed by the caller; this function only reads the prefix and optional limit. An empty prefix is rejected because an unbounded vertex scan from the REPL is almost never what the operator meant.

type Source 

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

func NewSource 

func NewSource(str string) (*Source, error)

NewSource tokenises the input into a Source. The grammar (#438): 

token         = bareword | double-quoted | single-quoted
bareword      = first char ∉ {whitespace,'"',"'"}, continues until next whitespace.
                Quotes inside a bareword are kept verbatim.
double-quoted = "..." with C-style escapes \", \\, \n, \r, \t.
single-quoted = '...' verbatim (no escapes).

Quoting is only special at the start of a token. Unterminated quotes (or unknown backslash sequences inside a double-quoted token) return ErrUnterminatedString or a parse error. On any error the returned Source is still valid (empty token stream) so callers that ignore the error do not deref a nil pointer.

func NewSourceFromTokens added in v0.16.0 

func NewSourceFromTokens(tokens []string) *Source

NewSourceFromTokens builds a Source directly from already-split tokens, skipping the quote-aware tokeniser entirely. It exists so the one-shot CLI verbs (`lantern-cli get vertex <key>`, etc.) can feed cobra's shell-split argv straight into the same grammar the REPL parses from a raw line — the shell already performed the word/quote splitting, so a second pass through tokenise() would be both redundant and lossy (a value containing spaces would be re-split). The verb token is expected to be the first element, mirroring `Verb(s)` on a NewSource stream.

func (*Source) HasNext 

func (s *Source) HasNext() bool

func (*Source) Len 

func (s *Source) Len() int

func (*Source) Next 

func (s *Source) Next()

func (*Source) Peek 

func (s *Source) Peek() (string, error)

func (*Source) Pos 

func (s *Source) Pos() int

func (*Source) Reset 

func (s *Source) Reset()

func (*Source) SetPos 

func (s *Source) SetPos(pos int)

func (*Source) Slice 

func (s *Source) Slice() []string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.