sexp

Documentation

Overview

Package sexp is the bounded reader for a restricted-Lisp file: docs/roadmap.sexp and docs/fixes.sexp (through pkg/roadmap), and nova-work's tree file in nova-sprint (its SPEC-WORKLANG.md). It is the one copy of the reader: nova-sprint's worklang package was the same code under another name, and imports this package instead.

A file is data the reader returns, never a program it evaluates. The grammar is a sequence of s-expressions made only of lists, keywords, strings, integers and bare symbols, with every evaluation form refused at the boundary and three bounds enforced as the reader runs -- bytes, nesting depth and node count. Nothing read here is ever evaluated: there is no eval, and a dispatch macro is a refusal with the byte offset that owes it, not a form the reader will run.

Every refusal is a *Refusal carrying exit code 2, so the command that opens a file can print one line and stop, never a partial parse.

Index

• type Form
  • func Read(file string, data []byte, limits Limits) (Form, error)
• type Kind
• type Limits
• type Refusal
  • func (r *Refusal) Error() string
  • func (r *Refusal) ExitCode() int

Types

type Form

type Form struct {
	Kind   Kind
	Offset int
	End    int
	List   []Form
	Value  string // keyword name (no colon) or decoded string
	Int    int64
}

Form is one restricted s-expression. Offset is the form's first byte and End the byte just past its last, so a refusal can name where in the file it happened.

func Read

func Read(file string, data []byte, limits Limits) (Form, error)

Read reads exactly one restricted form from data, holding it to limits and refusing anything else. The file name is carried into every refusal.

type Kind

type Kind int

Kind is the type of one restricted form.

const (
	// List is a parenthesized form, possibly empty.
	List Kind = iota
	// Keyword is a `:name` token, stored without the leading colon.
	Keyword
	// String is a double-quoted string, stored decoded.
	String
	// Integer is a decimal integer.
	Integer
	// Symbol is a bare token such as go-fix or false, stored verbatim. The
	// plan language uses symbols for values that are not text (kind names,
	// booleans), and they are data: nothing here is ever evaluated.
	Symbol
)

type Limits

type Limits struct {
	MaxBytes int
	MaxDepth int
	MaxNodes int
}

Limits is the three bounds every read is held to. A zero value is not usable; set all three. The names are the flag names a caller may expose: --max-bytes, --max-depth, --max-nodes.

type Refusal

type Refusal struct {
	File   string
	Reason string
}

Refusal is a plan this reader would not read. It is always exit 2: the tool could not run, and the input is refused whole rather than truncated.

func (*Refusal) Error

func (r *Refusal) Error() string

func (*Refusal) ExitCode

func (r *Refusal) ExitCode() int

ExitCode is 2 for every refusal, the code the self repository's lessons file nova-lessons.md fixes for a plan that could not be read.