plan

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package plan decodes plan files (format version 1) into the neutral assembly job tree, strictly and in one pass over the JSON token stream, with provenance and declared resource limits.

Index

Constants

View Source
const (
	// StageRead is I/O, cancellation, and the byte limit.
	StageRead Stage = "read"
	// StageSyntax is the JSON lexical and grammar rules.
	StageSyntax Stage = "syntax"
	// StageShape is member names, types, domains, and item shapes.
	StageShape Stage = "shape"
	// StageLimit is the declared resource bounds.
	StageLimit Stage = "limit"

	// CodeInterrupted means the read was cancelled.
	CodeInterrupted Code = "interrupted"
	// CodeReadFailed means the plan could not be read.
	CodeReadFailed Code = "read_failed"
	// CodeTooLarge means the plan exceeds the byte limit.
	CodeTooLarge Code = "plan_too_large"
	// CodeEmpty means the plan has no JSON value.
	CodeEmpty Code = "json_empty"
	// CodeSyntax means the plan is not well-formed JSON text (a lexical or grammar fault, including invalid UTF-8 and unpaired surrogates).
	CodeSyntax Code = "json_syntax"
	// CodeDuplicateMember means an object has two members with the same name once escapes are decoded.
	CodeDuplicateMember Code = "json_duplicate_member"
	// CodeTrailingData means data other than whitespace follows the plan object.
	CodeTrailingData Code = "json_trailing_data"
	// CodeNotObject means the plan is not a JSON object.
	CodeNotObject Code = "plan_not_object"
	// CodeUnknownMember means a member name is not part of the format, or has the wrong case.
	CodeUnknownMember Code = "plan_unknown_member"
	// CodeNull means a null appears where a value is required (omit the member instead).
	CodeNull Code = "plan_null_not_allowed"
	// CodeWrongType means a value has the wrong JSON type.
	CodeWrongType Code = "plan_wrong_type"
	// CodeOutOfRange means a number is outside its range or not finite.
	CodeOutOfRange Code = "plan_out_of_range"
	// CodeNotInteger means a number must be a whole number and is not.
	CodeNotInteger Code = "plan_not_integer"
	// CodeBadValue means a string or value is not one the format accepts.
	CodeBadValue Code = "plan_bad_value"
	// CodeMissingMember means a required member is absent.
	CodeMissingMember Code = "plan_missing_member"
	// CodeAmbiguousItem means an object item fits neither the blank nor the group shape.
	CodeAmbiguousItem Code = "plan_ambiguous_item"
	// CodeUnsupportedVer means the plan version is not the one this build reads.
	CodeUnsupportedVer Code = "plan_unsupported_version"
	// CodeEmptyItems means an items array has no entries.
	CodeEmptyItems Code = "plan_empty_items"
	// CodeLimitNodes means the plan has more structural nodes than the limit.
	CodeLimitNodes Code = "plan_limit_nodes"
	// CodeLimitDepth means directory groups nest deeper than the limit.
	CodeLimitDepth Code = "plan_limit_depth"
	// CodeLimitContribs means the plan has more PDF and blank entries than the limit.
	CodeLimitContribs Code = "plan_limit_contributions"
	// CodeLimitPages means the plan generates more blank pages than the limit.
	CodeLimitPages Code = "plan_limit_generated_pages"
)
View Source
const (
	// MaxPlanBytes is the plan byte limit, a leading byte order mark included.
	MaxPlanBytes = 64 << 20
)
View Source
const (

	// Version is the plan format version this package reads.
	Version = 1
)

Variables

This section is empty.

Functions

func Decode

func Decode(ctx context.Context, input Input, reader io.Reader) (*assembly.Job, error)

Decode reads exactly one plan object from reader in a single pass over the jsontext token stream. reader may block (standard input); ctx cancels the read. Errors are *Error values; decoding stops at the first fault.

func Schema

func Schema() string

Schema returns the JSON Schema (draft 2020-12) describing plan format version 1. It states the structural rules; duplicate members, Unicode and byte-level rules, and unit-converted length bounds are enforced by Decode only.

Types

type Code

type Code string

Code is a stable snake_case diagnostic identifier. Messages are not stable; codes are.

type Error

type Error struct {
	// Err is the underlying cause, if any (an I/O error, or the context's error on interruption).
	Err error
	// Message states what is wrong and what is expected.
	Message  string
	Code     Code
	Stage    Stage
	Location assembly.Location
}

Error is one located, coded plan diagnostic. Decoding stops at the first structural fault, so an Error is the first problem found, not necessarily the only one.

func (*Error) Error

func (e *Error) Error() string

Error formats the diagnostic as "location: message [code]".

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying cause.

type Input

type Input struct {
	// Name is the source name used in diagnostics: the file path, "<stdin>", or "<inline>".
	Name string
	// BaseDir is the initial base directory: the plan file's directory, or --base-dir for standard input and
	// inline plans, or the working directory. It is not interpreted here; it is recorded as Job.Base
	// and as the base of fonts declared in the defaults.
	BaseDir string
}

Input describes where a plan came from.

type Stage

type Stage string

Stage names the phase that produced a diagnostic.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL