std

README

gopherbuzz/std - the Buzz standard library

This package implements the standard library of the Buzz language for the gopherbuzz VM: the modules a Buzz program reaches with a bare import - std, math, fs, os, crypto, gc, debug, io, serialize, buffer, and ffi.

sess := buzz.NewSession(ctx)
buzzstd.Register(sess) // makes every module above importable

The constraint: match upstream Buzz

These modules are the language's standard library, not gopherbuzz's own invention. gopherbuzz is a pure-Go VM for Buzz; it targets 0.6.0-dev, tracking upstream buzz-language/buzz main at the commit pinned in ../version.go (UpstreamRef), and this package must track the upstream stdlib's names, signatures, and observable semantics so a Buzz program runs the same here as on the reference implementation. The latest published reference is 0.5.0; 0.6.0 is unreleased.

The project-wide rule (see the top-level README) is "match capabilities, diverge only where a concrete reason forces it." Concretely, for this package:

• Do not add upstream-shaped modules or methods here that upstream Buzz does not have. A capability magus wants - running a subprocess, querying git, hashing a file - is a host concern and belongs in magus/std, layered on top (see below). Keeping the upstream-faithful surface upstream-shaped is what lets a standalone .buzz program (and cmd/buzz) stay portable. The one sanctioned exception is gopherbuzz's own test surface (assertcore/assert/suite/testing), which has no upstream counterpart; those register through std.Modules carrying the buzz.LabelGopherbuzz label, so a caller can filter to the upstream-only surface, and conformance fixtures never import them.
• Match signatures and return shapes to the upstream reference. When in doubt, the reference at buzz-lang.dev is the source of truth.
• Document any deliberate divergence. Where gopherbuzz intentionally differs (e.g. test is a soft keyword, not hard-reserved), the divergence is called out in the top-level README's compatibility notes. A new divergence needs the same treatment - a comment explaining why, not a silent behavior change.

Relationship to magus/std

magus uses this package as the base layer and then exposes a superset:

import "os"  in a magusfile
  ├── os.sleep / os.time / os.env / os.execute / …   ← gopherbuzz/std (this package)
  └── proc.exec / proc.which / os.retry / os.with_env / …← magus/std (host methods)

magus registers this package first, then layers its host methods onto the same bare module names and adds modules Buzz has no concept of (vcs, archive, http, env, time, charm, …). The union is what a magusfile sees. The cross-reference of which magus method has a native Buzz equivalent lives in host/overlap.go; the superset itself is described in std/README.md.

The split is deliberate: edit this package only to track upstream Buzz; put anything magus-specific in magus/std.

Documentation

Overview

Package std provides Buzz's standard library modules as native modules for the magus/buzz interpreter.

Call Register once after creating a session to make all modules available for import:

import "std"       // assert, print, parseInt, toInt, char, random, panic, …
import "math"      // sin, cos, sqrt, pi, abs, …
import "fs"        // currentDirectory, makeDirectory, delete, move, list, exists
import "os"        // sleep, time, env, tmpDir, tmpFilename, exit, execute, Socket, TcpServer
import "crypto"    // HashAlgorithm enum + hash()
import "gc"        // allocated, collect
import "debug"     // dump, ast
import "io"        // File, FileMode, stdin, stdout, stderr, runFile
import "serialize" // Boxed, serialize, jsonEncode, jsonDecode
import "buffer"    // Buffer

ffi is C-ABI native (see ffi.go): zdef() binds C functions, and the ffi module offers cstr, sizeOf/alignOf, sizeOfStruct/alignOfStruct, structLayout, and a pinned alloc/free/read/write memory API for out-parameters and by-reference structs. Type arguments are C type-name strings, not Zig types.

Index

• Variables
• func CwdFromContext(ctx context.Context) (string, bool)
• func Register(sess *buzz.Session)
• func RegisterWithOutput(sess *buzz.Session, out io.Writer)
• func SkipMessage(err error) (string, bool)
• func WithCwd(ctx context.Context, dir string) context.Context

Variables

var Modules = []buzz.Module{
	{Name: "std", Labels: []string{buzz.LabelUpstream}, Bind: func(s *buzz.Session, env buzz.ModuleEnv) error {
		s.SetNativeModule("std", coreModule(env.Out))
		return nil
	}},
	{Name: "math", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("math", mathModule)},
	{Name: "fs", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("fs", fsModule)},
	{Name: "os", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("os", osModule)},

	{Name: "cryptocore", Labels: []string{buzz.LabelGopherbuzz}, Bind: synthetic("cryptocore", cryptoCoreModule)},
	{Name: "crypto", Labels: []string{buzz.LabelUpstream}, Bind: func(s *buzz.Session, _ buzz.ModuleEnv) error {
		s.SetNativeModule("crypto", cryptoCoreModule())
		s.SetModuleDecls("crypto", cryptoSource)
		return nil
	}},
	{Name: "gc", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("gc", gcModule)},
	{Name: "debug", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("debug", debugModule)},
	{Name: "iocore", Labels: []string{buzz.LabelGopherbuzz}, Bind: func(s *buzz.Session, _ buzz.ModuleEnv) error {
		s.SetNativeModule("iocore", ioCoreModule(s))
		return nil
	}},
	{Name: "io", Labels: []string{buzz.LabelUpstream}, Bind: func(s *buzz.Session, _ buzz.ModuleEnv) error {
		s.SetNativeModule("io", ioCoreModule(s))
		s.SetModuleDecls("io", ioSource)
		s.SetModuleDecls("os", osSource)
		return nil
	}},
	{Name: "serialize", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("serialize", serializeModule)},
	{Name: "buffer", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("buffer", bufferModule)},
	{Name: "ffi", Labels: []string{buzz.LabelUpstream}, Bind: synthetic("ffi", ffiModule)},
	{Name: "assertcore", Labels: []string{buzz.LabelGopherbuzz}, Bind: synthetic("assertcore", assertCoreModule)},
	{Name: "assert", Labels: []string{buzz.LabelGopherbuzz}, Bind: source("assert", assertSource)},
	{Name: "suite", Labels: []string{buzz.LabelGopherbuzz}, Bind: source("suite", suiteSource)},
	{Name: "testing", Labels: []string{buzz.LabelGopherbuzz}, Bind: source("testing", testingSource)},

	{Name: "test", Labels: []string{buzz.LabelUpstream}, Bind: source("test", testingSource)},
}

Modules is the single source of truth for the modules gopherbuzz bundles: the upstream-faithful stdlib (buzz.LabelUpstream) plus gopherbuzz's own test surface (buzz.LabelGopherbuzz). Register provides every entry; a caller filters by label for a subset. Edit this table to add a module. The registration shape is buzz.Module (see gopherbuzz/module.go), shared with host embedders.

Functions

func CwdFromContext

func CwdFromContext(ctx context.Context) (string, bool)

CwdFromContext returns the working directory set by WithCwd and whether one is set. It is the reader counterpart to WithCwd, so an embedder that layers its own cwd on top (e.g. magus) can confirm the value propagated into this stdlib.

func Register

func Register(sess *buzz.Session)

Register installs every bundled module on sess. std.print writes to os.Stdout; use RegisterWithOutput to redirect it.

func RegisterWithOutput

func RegisterWithOutput(sess *buzz.Session, out io.Writer)

RegisterWithOutput is Register with std.print directed to out. An embedding that captures a program's textual output (e.g. the WebAssembly playground) passes its own writer so print lands in a buffer instead of the host stdout.

func SkipMessage

func SkipMessage(err error) (string, bool)

SkipMessage reports whether err is a test-skip signal (from assert\skip) and, if so, returns the skip reason. Test runners call it to classify a test-block error as skipped rather than failed.

func WithCwd

func WithCwd(ctx context.Context, dir string) context.Context

WithCwd returns ctx carrying dir as the working directory the std builtins (fs.*, io.File/io.runFile, os.execute) resolve relative paths against. An empty dir is a no-op. Exported so an embedder can establish it; the stdlib reads it internally via resolve. Absolute paths and scripts run without a cwd are unaffected, so this extends the standard library's behavior rather than changing it.