docs: document methods

README.md

@@ -7,3 +7,8 @@ Making a lambda calculus interpreter in Go.
 - Exhaustive sum types.
 - Recursive descent and left-recursion.
 - Observer pattern, event emission.
+
+## Links
+
+<https://zicklag.katharos.group/blog/interaction-nets-combinators-calculus/>
+<https://arxiv.org/pdf/2505.20314>

cmd/lambda/lambda.go

@@ -6,7 +6,7 @@ import (
 
 	"git.maximhutz.com/max/lambda/internal/cli"
 	"git.maximhutz.com/max/lambda/internal/config"
-	"git.maximhutz.com/max/lambda/internal/executer"
+	"git.maximhutz.com/max/lambda/internal/engine"
 	"git.maximhutz.com/max/lambda/internal/explanation"
 	"git.maximhutz.com/max/lambda/internal/performance"
 	"git.maximhutz.com/max/lambda/internal/statistics"
@@ -15,8 +15,8 @@ import (
 	"git.maximhutz.com/max/lambda/pkg/saccharine"
 )
 
-// Run main application.
 func main() {
+	// Parse CLI arguments.
 	options, err := config.FromArgs()
 	cli.HandleError(err)
 
@@ -24,7 +24,8 @@ func main() {
 	logger.Info("using program arguments", "args", os.Args)
 	logger.Info("parsed CLI options", "options", options)
 
-	input, err := options.Source.Pull()
+	// Get input.
+	input, err := options.Source.Extract()
 	cli.HandleError(err)
 
 	// Parse tokens.
@@ -35,33 +36,46 @@ func main() {
 	// Turn tokens into syntax tree.
 	expression, err := saccharine.Parse(tokens)
 	cli.HandleError(err)
-	if options.Verbose {
-		logger.Info("parsed syntax tree", "tree", saccharine.Stringify(expression))
-	}
+	logger.Info("parsed syntax tree", "tree", saccharine.Stringify(expression))
 
+	// Compile expression to lambda calculus.
 	compiled := convert.SaccharineToLambda(expression)
-	if options.Verbose {
-		logger.Info("compiled lambda expression", "tree", lambda.Stringify(compiled))
-	}
+	logger.Info("compiled lambda expression", "tree", lambda.Stringify(compiled))
 
-	process := executer.New(options, &compiled)
+	// Create reduction engine.
+	process := engine.New(options, &compiled)
+
+	// If the user selected to track CPU performance, attach a profiler to the
+	// process.
 	if options.Profile != "" {
 		profiler := performance.Track(options.Profile)
 		process.On("start", profiler.Start)
 		process.On("end", profiler.End)
 	}
 
+	// If the user selected to produce a step-by-step explanation, attach an
+	// observer here.
 	if options.Explanation {
 		explanation.Track(process)
 	}
 
-	statistics := statistics.Track()
-	process.On("start", statistics.Start)
-	process.On("step", statistics.Step)
-	process.On("end", statistics.End)
+	// If the user opted to track statistics, attach a tracker here, too.
+	if options.Statistics {
+		statistics := statistics.Track()
+		process.On("start", statistics.Start)
+		process.On("step", statistics.Step)
+		process.On("end", statistics.End)
+	}
+
+	// If the user selected for verbose debug logs, attach a reduction tracker.
+	if options.Verbose {
+		process.On("step", func() {
+			logger.Info("reduction", "tree", lambda.Stringify(compiled))
+		})
+	}
 
 	process.Run()
 
+	// Return the final reduced result.
 	fmt.Println(lambda.Stringify(compiled))
-	fmt.Fprint(os.Stderr, statistics.Results.String())
 }

internal/cli/exit.go

@@ -1,3 +1,4 @@
+// Package "cli" provides miscellaneous helper functions.
 package cli
 
 import (
@@ -12,6 +13,6 @@ func HandleError(err error) {
 		return
 	}
 
-	fmt.Fprintln(os.Stderr, err)
+	fmt.Fprintln(os.Stderr, "ERROR:", err)
 	os.Exit(1)
 }

internal/config/config.go

@@ -1,9 +1,11 @@
+// Package "config" parses ad handles the user settings given to the program.
 package config
 
-// Arguments given to program.
+// Configuration settings for the program.
 type Config struct {
 	Source      Source // The source code given to the program.
 	Verbose     bool   // Whether or not to print debug logs.
 	Explanation bool   // Whether or not to print an explanation of the reduction.
 	Profile     string // If not nil, print a CPU profile during execution.
+	Statistics  bool   // Whether or not to print statistics.
 }

internal/config/get_logger.go

@@ -5,13 +5,14 @@ import (
 	"os"
 )
 
-// Define the correct logger for the program to use.
+// Returns a structured logger with the appropriate configurations.
 func (c Config) GetLogger() *slog.Logger {
-	var level slog.Level
+	// By default, only print out errors.
+	level := slog.LevelError
+
+	// If the user set the output to be "VERBOSE", return the debug logs.
 	if c.Verbose {
 		level = slog.LevelInfo
-	} else {
-		level = slog.LevelError
 	}
 
 	return slog.New(

internal/config/parse_from_args.go

@@ -7,13 +7,14 @@ import (
 
 // Extract the program configuration from the command-line arguments.
 func FromArgs() (*Config, error) {
-	// Parse flags.
+	// Relevant flags.
 	verbose := flag.Bool("v", false, "Verbosity. If set, the program will print logs.")
 	explanation := flag.Bool("x", false, "Explanation. Whether or not to show all reduction steps.")
-	profile := flag.String("p", "", "CPU profiling. If set, the program will run a performance profile during execution.")
+	statistics := flag.Bool("s", false, "Statistics. If set, the process will print various statistics about the run.")
+	profile := flag.String("p", "", "CPU profiling. If an output file is defined, the program will profile its execution and dump its results into it.")
 	flag.Parse()
 
-	// Parse non-flag arguments.
+	// There must only be one input argument.
 	if flag.NArg() == 0 {
 		return nil, fmt.Errorf("no input given")
 	} else if flag.NArg() > 1 {
@@ -25,7 +26,7 @@ func FromArgs() (*Config, error) {
 	if flag.Arg(0) == "-" {
 		source = StdinSource{}
 	} else {
-		source = StringSource{data: flag.Arg(0)}
+		source = StringSource{Data: flag.Arg(0)}
 	}
 
 	return &Config{
@@ -33,5 +34,6 @@ func FromArgs() (*Config, error) {
 		Verbose:     *verbose,
 		Explanation: *explanation,
 		Profile:     *profile,
+		Statistics:  *statistics,
 	}, nil
 }

internal/config/source.go

@@ -5,21 +5,21 @@ import (
 	"os"
 )
 
-// Defines the consumption of different types of input sources.
+// A method of extracting input from the user.
 type Source interface {
-	// Get the data.
-	Pull() (string, error)
+	// Fetch data from this source.
+	Extract() (string, error)
 }
 
-// A source coming from a string.
-type StringSource struct{ data string }
+// A source defined by a string.
+type StringSource struct{ Data string }
 
-func (s StringSource) Pull() (string, error) { return s.data, nil }
+func (s StringSource) Extract() (string, error) { return s.Data, nil }
 
-// A source coming from standard input.
+// A source pulling from standard input.
 type StdinSource struct{}
 
-func (s StdinSource) Pull() (string, error) {
+func (s StdinSource) Extract() (string, error) {
 	data, err := io.ReadAll(os.Stdin)
 	if err != nil {
 		return "", err

internal/engine/engine.go

@@ -1,31 +1,31 @@
-package executer
+// Package "engine" provides an extensible interface for users to interfact with
+// lambda calculus.
+package engine
 
 import (
-	"log/slog"
-
 	"git.maximhutz.com/max/lambda/internal/config"
 	"git.maximhutz.com/max/lambda/pkg/emitter"
 	"git.maximhutz.com/max/lambda/pkg/lambda"
 )
 
-type Executor struct {
+// A process for reducing one lambda expression.
+type Engine struct {
 	Config     *config.Config
 	Expression *lambda.Expression
 	emitter.Emitter
 }
 
-func New(config *config.Config, expression *lambda.Expression) *Executor {
-	return &Executor{Config: config, Expression: expression}
+// Create a new engine, given an unreduced lambda expression.
+func New(config *config.Config, expression *lambda.Expression) *Engine {
+	return &Engine{Config: config, Expression: expression}
 }
 
-func (e Executor) Run() {
+// Begin the reduction process.
+func (e Engine) Run() {
 	e.Emit("start")
 
 	for lambda.ReduceOnce(e.Expression) {
 		e.Emit("step")
-		if e.Config.Verbose {
-			slog.Info("reduction", "tree", lambda.Stringify(*e.Expression))
-		}
 	}
 
 	e.Emit("end")

internal/explanation/tracker.go

@@ -1,17 +1,21 @@
+// Package "explanation" provides a observer to gather the reasoning during the
+// reduction, and present a thorough explanation to the user for each step.
 package explanation
 
 import (
 	"fmt"
 
-	"git.maximhutz.com/max/lambda/internal/executer"
+	"git.maximhutz.com/max/lambda/internal/engine"
 	"git.maximhutz.com/max/lambda/pkg/lambda"
 )
 
+// Track the reductions made by a reduction proess.
 type Tracker struct {
-	process *executer.Executor
+	process *engine.Engine
 }
 
-func Track(process *executer.Executor) *Tracker {
+// Attaches a new explanation tracker to a process.
+func Track(process *engine.Engine) *Tracker {
 	tracker := &Tracker{process: process}
 	process.On("start", tracker.Start)
 	process.On("step", tracker.Step)

internal/performance/tracker.go

@@ -1,3 +1,5 @@
+// Package "performance" provides a tracker to observer CPU performance during
+// execution.
 package performance
 
 import (
@@ -6,16 +8,20 @@ import (
 	"runtime/pprof"
 )
 
+// Observes a reduction process, and publishes a CPU performance profile on
+// completion.
 type Tracker struct {
 	File        string
 	filePointer *os.File
 	Error       error
 }
 
+// Create a performance tracker that outputs a profile to "file".
 func Track(file string) *Tracker {
 	return &Tracker{File: file}
 }
 
+// Begin profiling.
 func (t *Tracker) Start() {
 	var absPath string
 
@@ -40,6 +46,7 @@ func (t *Tracker) Start() {
 	}
 }
 
+// Stop profiling.
 func (t *Tracker) End() {
 	pprof.StopCPUProfile()
 	t.filePointer.Close()

internal/statistics/statistics.go

@@ -1,3 +1,5 @@
+// Package "statistics" provides a way to observer reduction speed during
+// execution.
 package statistics
 
 import (
@@ -5,15 +7,18 @@ import (
 	"strings"
 )
 
+// Statistics for a specific reduction.
 type Results struct {
 	StepsTaken  uint64 // Number of steps taken during execution.
 	TimeElapsed uint64 // The time (ms) taken for execution to complete.
 }
 
+// Returns the average number of operations per second of the execution.
 func (r Results) OpsPerSecond() float32 {
 	return float32(r.StepsTaken) / (float32(r.TimeElapsed) / 1000)
 }
 
+// Format the results as a string.
 func (r Results) String() string {
 	builder := strings.Builder{}
 	fmt.Fprintln(&builder, "Time Spent:", r.TimeElapsed, "ms")

internal/statistics/tracker.go

@@ -1,15 +1,18 @@
 package statistics
 
 import (
+	"fmt"
+	"os"
 	"time"
 )
 
+// An observer, to track reduction performance.
 type Tracker struct {
-	start   time.Time
-	steps   uint64
-	Results *Results
+	start time.Time
+	steps uint64
 }
 
+// Create a new reduction performance tracker.
 func Track() *Tracker {
 	return &Tracker{}
 }
@@ -17,7 +20,6 @@ func Track() *Tracker {
 func (t *Tracker) Start() {
 	t.start = time.Now()
 	t.steps = 0
-	t.Results = nil
 }
 
 func (t *Tracker) Step() {
@@ -25,8 +27,10 @@ func (t *Tracker) Step() {
 }
 
 func (t *Tracker) End() {
-	t.Results = &Results{
+	results := Results{
 		StepsTaken:  t.steps,
 		TimeElapsed: uint64(time.Since(t.start).Milliseconds()),
 	}
+
+	fmt.Fprint(os.Stderr, results.String())
 }

pkg/saccharine/parser.go

@@ -122,7 +122,7 @@ func parseStatements(i *TokenIterator) ([]ast.Statement, error) {
 	for {
 		if statement, err := parseStatement(i); err != nil {
 			break
-		} else if _, err := parseList(i, parseBreak, 1); err != nil {
+		} else if _, err := parseList(i, parseBreak, 1); err != nil && !i.Done() {
 			break
 		} else {
 			statements = append(statements, statement)
@@ -212,6 +212,7 @@ func parseStatement(i *TokenIterator) (ast.Statement, error) {
 	}
 }
 
+// Given a list of tokens, attempt to parse it into an syntax tree.
 func Parse(tokens []token.Token) (ast.Expression, error) {
 	i := iterator.Of(tokens)
 

pkg/saccharine/stringify.go

@@ -54,6 +54,7 @@ func stringifyClause(n *ast.Clause) string {
 	return "{ " + stmts + Stringify(n.Returns) + " }"
 }
 
+// Convert an expression back into valid source code.
 func Stringify(n ast.Expression) string {
 	switch n := n.(type) {
 	case *ast.Atom:

pkg/saccharine/tokenizer.go

@@ -97,7 +97,7 @@ func getToken(i *iterator.Iterator[rune]) (*token.Token, error) {
 	return nil, fmt.Errorf("unknown character '%v'", string(letter))
 }
 
-// Parses a list of runes into tokens. All error encountered are returned, as well.
+// Parse a string into tokens.
 func GetTokens(input string) ([]token.Token, error) {
 	i := iterator.Of([]rune(input))
 	tokens := []token.Token{}