chip

package module
v0.0.0-...-ebd3885 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 14 Imported by: 0

README

chip

CI Go Reference Go Report Card

A toy systems scripting language with Go-like syntax that runs as a demand-driven stream.

func gcd(a int, b int) int {
    if b == 0 {
        return a
    }
    return gcd(b, a % b)
}

func main() {
    print(gcd(252, 105))   // 21
}

Why chip

  • Streaming execution. A program runs as it is read — there is no whole-program gate. A statement can even call a function defined further down the file; chip reads ahead to resolve it (example).
  • Minimal, Go-like syntax. func, :=, if, for, and little else.
  • Strongly typed, incrementally. Type checking is woven into the stream, not run as a separate pass.
  • Packages, Go-style. A package is a directory of .chp files; import it by path and call pkg.Member. Capitalized names are exported; the entry file still streams while imported packages load eagerly (example).
  • Pure Go. No cgo, no codegen backend — embed it as a library or use the CLI.
  • A standard library written in chip. Only print and len are built in; the rest grows in chip — including importable packages like math (import "math", then math.Gcd(252, 105)).

Install

go install github.com/jackspirou/chip/cmd/chip@latest

Usage

chip run examples/hello.chp   # run a program (shorthand: chip examples/hello.chp)
chip repl                     # interactive session
chip fmt  <file.chp>          # canonical formatting
chip lint <file.chp>          # unused names, missing returns, dead code

Learn more

  • ARCHITECTURE.md — how chip streams, and the package layout.
  • examples/ — small, runnable programs, each verified by a test.

Status

A learning project and a labor of love — expect rough edges and breaking changes. chip reimagines SNARL, a MIPS-targeting teaching compiler, in the spirit of Go's lexical simplicity: extreme minimal syntax, idiomatic Go implementation.

License

MIT

Documentation

Overview

Package chip embeds the chip toy language: it parses, type-checks, compiles, and runs chip source from Go.

The command-line tool lives in cmd/chip; this package is the library entry point for embedding chip in other programs. The implementation lives under internal/ and is deliberately not part of the public API.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Format 

func Format(src []byte) ([]byte, error)

Format returns src rewritten in canonical form. Like gofmt, it only requires the source to parse; it does not type-check.

func Run 

func Run(src []byte, out io.Writer) error

Run streams and executes chip source, writing program output to out. Unlike Compile, it runs the program as a demand-driven stream: there is no whole-program gate, and top-level statements run as they arrive. On a parse, type, or runtime error it returns an *Error carrying positioned diagnostics.

Example 
package main

import (
	"os"

	"github.com/jackspirou/chip"
)

func main() {
	src := `package main
func main() { print(2 + 3) }`
	if err := chip.Run([]byte(src), os.Stdout); err != nil {
		panic(err)
	}
}

Output:
5

func RunWith 

func RunWith(ctx context.Context, r io.Reader, w io.Writer, lim Limits) error

RunWith streams and executes chip source from r like Run while enforcing resource caps: ctx cancellation imposes a wall-clock timeout (a cancelled ctx stops the run and is reported as a timeout), and lim bounds interpreter steps, output bytes, and call depth. Program output is written to w; imports resolve against the current directory. On a parse, type, runtime, or resource-cap error it returns an *Error carrying positioned diagnostics.

Types

type CheckReport 

type CheckReport struct {
	Diagnostics        []Diagnostic
	SuppressedCascades int
}

CheckReport is the result of Check: every static error that survived cascade pruning, in source order, plus the number of cascade-derived errors that were suppressed (so the pruning stays auditable). It is empty when src is valid.

func Check 

func Check(src []byte) *CheckReport

Check statically analyzes src without executing it, returning every independent parse and type error at once (collect-all), with cascade-derived follow-on errors pruned: one root error per top-level construct, and the phantom type errors that a broken construct provokes are suppressed (count in SuppressedCascades).

Check is the analysis half of run: it reports what running would report before the first fault, never executing. Its boundary matches the batch checker (D3): imports are opaque (no Loader, so a qualified pkg.Member call is not resolved or rejected) and there is no runtime — so it never reports a runtime fault, only static errors it can know whole-program.

Check is the library's flat view: it down-converts the shared analysis (which carries phases, byte offsets, and fix suggestions) to the public position-and-message Diagnostic. The CLI's `chip check` consumes the rich form directly for codes and "did you mean".

func (*CheckReport) OK 

func (r *CheckReport) OK() bool

OK reports whether src passed the check with no surviving diagnostics.

type Diagnostic 

type Diagnostic struct {
	Line int
	Col  int
	Msg  string
}

Diagnostic is a positioned message produced while processing chip source.

func Lint 

func Lint(src []byte) ([]Diagnostic, error)

Lint type-checks src and returns any style and correctness issues.

func (Diagnostic) String 

func (d Diagnostic) String() string

String formats the diagnostic as "line:col: message".

type Error 

type Error struct {
	Diagnostics []Diagnostic
}

Error reports one or more diagnostics from compiling or running chip source.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

type Limits 

type Limits struct {
	Steps    int64 // max interpreter steps; 0 = unlimited
	OutBytes int64 // max bytes written to w; 0 = unlimited
	Depth    int   // max call depth; 0 = default
}

Limits bounds a run's resource use for RunWith (plan §4.1). A zero field imposes no limit on that dimension; a zero Depth uses chip's default call-depth limit. The caps are enforced cooperatively, so Steps is deterministic for a given program and input.

type Program 

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

Program is a compiled chip program, ready to run.

func Compile 

func Compile(src []byte) (*Program, error)

Compile parses, type-checks, and compiles chip source into a Program. On failure it returns an *Error carrying positioned diagnostics.

func (*Program) Run 

func (p *Program) Run(out io.Writer) error

Run executes the program, writing its output to out.

Source Files

View all Source files

Directories

Path Synopsis
cmd
chip command
Command chip runs, formats, and inspects chip source files.
 Command chip runs, formats, and inspects chip source files.
internal
analyze
Package analyze runs chip's batch static analysis — parse plus local type checking — and returns cascade-pruned structured diagnostics.
 Package analyze runs chip's batch static analysis — parse plus local type checking — and returns cascade-pruned structured diagnostics.
ast
Package ast declares the types used to represent syntax trees for chip source files.
 Package ast declares the types used to represent syntax trees for chip source files.
check
Package check performs name resolution and type checking on a chip syntax tree, producing the type information consumed by later compilation.
 Package check performs name resolution and type checking on a chip syntax tree, producing the type information consumed by later compilation.
code
Package code defines chip's bytecode: opcodes, instructions, and the compiled program structures the VM executes.
 Package code defines chip's bytecode: opcodes, instructions, and the compiled program structures the VM executes.
compiler
Package compiler translates a type-checked chip syntax tree into bytecode.
 Package compiler translates a type-checked chip syntax tree into bytecode.
diag
Package diag turns chip's line/column source positions into byte offsets.
 Package diag turns chip's line/column source positions into byte offsets.
eval
Package eval is chip's mini harness: a deterministic integration rig that drives the chip CLI end to end, and an evaluation rig that loops a model over a corpus of broken→fixed programs to measure how an agent's repair loop converges (plan §5.3).
 Package eval is chip's mini harness: a deterministic integration rig that drives the chip CLI end to end, and an evaluation rig that loops a model over a corpus of broken→fixed programs to measure how an agent's repair loop converges (plan §5.3).
fix
Package fix turns the repair suggestions a diagnostic carries into applied source edits — the engine behind `chip fix`.
 Package fix turns the repair suggestions a diagnostic carries into applied source edits — the engine behind `chip fix`.
format
Package format pretty-prints chip syntax trees as canonical source.
 Package format pretty-prints chip syntax trees as canonical source.
lint
Package lint reports style and correctness issues that the type checker does not treat as hard errors: unused variables and functions, unused imports, functions used before definition, and unreachable code.
 Package lint reports style and correctness issues that the type checker does not treat as hard errors: unused variables and functions, unused imports, functions used before definition, and unreachable code.
parser
Package parser builds an abstract syntax tree from chip source.
 Package parser builds an abstract syntax tree from chip source.
reader
Package reader reads characters from a UTF-8 io.Reader.
 Package reader reads characters from a UTF-8 io.Reader.
scanner
Package scanner scans tokens from a UTF-8 io.Reader.
 Package scanner scans tokens from a UTF-8 io.Reader.
scope
Package scope implements lexical scopes that map names to symbols.
 Package scope implements lexical scopes that map names to symbols.
std
Package std provides chip's standard library: helpers written in chip itself and loaded into the engine before every program runs.
 Package std provides chip's standard library: helpers written in chip itself and loaded into the engine before every program runs.
stream
Package stream implements chip's demand-driven streaming evaluator: source flows reader → scanner → parser → executor with no whole-program gate.
 Package stream implements chip's demand-driven streaming evaluator: source flows reader → scanner → parser → executor with no whole-program gate.
token
Package token defines lexical tokens.
 Package token defines lexical tokens.
typerules
Package typerules is the single source of truth for chip's leaf type rules: the operand/result rules of every operator, the type predicates those rules rest on, the control-flow "does this body always return" analysis, and the main-signature rule.
 Package typerules is the single source of truth for chip's leaf type rules: the operand/result rules of every operator, the type predicates those rules rest on, the control-flow "does this body always return" analysis, and the main-signature rule.
types
Package types defines chip's static type system.
 Package types defines chip's static type system.
value
Package value defines the runtime values manipulated by the chip VM.
 Package value defines the runtime values manipulated by the chip VM.
vm
Package vm executes compiled chip bytecode on a stack machine.
 Package vm executes compiled chip bytecode on a stack machine.

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.