preprocessor

Documentation

Overview

Package preprocessor implements the q -toolexec preprocessor.

Run is the single entrypoint. It is called from cmd/q's main with os.Args[1:] and returns a shell-style exit code. Everything below is intentionally private: the preprocessor is distributed as the q binary, not as an importable library.

Shape follows proven (github.com/GiGurra/proven) and rewire (github.com/GiGurra/rewire) closely: dispatch on the tool being wrapped, AST-based scanning of the source files the Go tool received, a minimal set of rewrites emitted to temp files that are appended (or substituted) to the tool's argv, and a final forward to the real tool. Nothing in the original source tree is modified.

Phase 1 (this file plus qstub.go): inject the _q_atCompileTime linker stub when compiling pkg/q. Without that, every program that imports pkg/q fails to link — by design.

Phase 2+ (rewriter.go, future): scan user packages, replace each q.NoErr/NonNil family call site with the inlined error-forwarding statements, hand the rewritten file to the compiler.

Index

• func Run(args []string, stderr io.Writer) int
• type Chain
• type Diagnostic
  • func (d Diagnostic) String() string
• type Plan

Functions

func Run

func Run(args []string, stderr io.Writer) int

Run executes the preprocessor with the toolexec-style arguments (os.Args[1:]): the first element is the path to the underlying Go tool (compile, link, asm, …), and the rest are the tool's own arguments. Run returns the exit code to hand back to the OS.

Types

type Chain

type Chain struct {
	// NextCmd is the argv that should replace the bare tool
	// invocation. Empty when no --and-then was present.
	NextCmd []string
}

Chain captures the optional `--and-then` chain of successor preprocessor invocations. A non-empty NextCmd means q was invoked as one link in a chain like:

q [q-args...] --and-then pre2 [pre2-args...] --and-then pre3 ... /abs/go/tool args...

When the chain fires, q still does its normal rewriting, but instead of exec'ing the real Go tool directly it exec's NextCmd with the tool path (and rewritten tool args) appended. Each link in the chain peels off one --and-then and forwards the remainder, so the last link sees a classic toolexec invocation and needs no --and-then awareness at all.

type Diagnostic

type Diagnostic struct {
	File string
	Line int
	Col  int
	Msg  string
}

Diagnostic is one Go-standard preprocessor message. The String form matches `cmd/compile`'s `file:line:col: message` layout so editors and CI output parsers pick it up without special casing.

func (Diagnostic) String

func (d Diagnostic) String() string

type Plan

type Plan struct {
	NewArgs []string
	Cleanup func()
	Diags   []Diagnostic
}

Plan is the decision made for one toolexec compile invocation.

NewArgs is the argv to forward to the real compile tool, or nil to leave the incoming toolArgs unchanged. Cleanup is deferred after the forwarded compile returns; may be nil. Diags, if non-empty, is printed to stderr by the caller and the preprocessor exits non-zero without forwarding the compile.