Module guide

The Swarm codebase has gotten large enough to be quite intimidating at first glance (currently, as of May 2024, 28K SLOC across 224 modules). This page contains a (work-in-progress) guide to help orient developers to the codebase.

To help with organization and enforce modularity, the codebase is first broken into a number of sublibraries, listed below. Click on a sublibrary to jump to the section outlining its contents.

• swarm-util: miscellaneous utilities
• swarm-lang: parsing, typechecking, etc. for the Swarm language
• swarm-scenario: scenario/world descriptions, parsing, & processing
• swarm-engine: game simulation
• swarm-doc: generating documentation
• swarm-tui: textual user interface
• swarm-web: web interface

swarm-util

The swarm-util sublibrary contains various miscellaneous utilities which are used throughout the Swarm codebase.

• Control.Carrier.Accum.FixedStrict: this is a vendored version of Control.Carrier.Accum.Strict from the fused-effects library that works around a bug.
• Data.BoolExpr.Simplify: some additional functionality on top of the boolexpr library.
• Swarm.Util: a collection of useful generic functions which are not specific to Swarm but not found elsewhere.
• Swarm.Util.*: various more specialized utilities.

swarm-lang

The swarm-lang library contains definitions and tools for working with the Swarm programming language.

• Syntax
  • Swarm.Language.Types: Swarm language types and utilities for working with them.
  • Swarm.Language.Direction: directions (right, left; north, south; etc.)
  • Swarm.Language.Syntax: the main module defining the abstract syntax of the Swarm language.
• Parsing
  • Swarm.Language.Parser: defines top-level function readTerm for parsing an expression of the Swarm language, returning an AST annotated with source locations and comments.
  • Swarm.Language.Parser.*: various components of the parser:
    • Util: parsing utilities
    • Core: core parser definitions + utilities
    • Lex: lexing/tokenizing
    • Record: parsing records at both the type and term level
    • Type: parsing Swarm language types
    • Term: parsing Swarm language terms
    • Comment: re-inserting comments into the parsed AST
  • Swarm.Language.Key: data type, parsing + pretty printing for keys (i.e. key presses).
• Checking
  • Swarm.Language.Context: mappings from variables to information about them (types, requirements, ...)
  • Swarm.Language.Module: a module is a typechecked term together with a context of names defined in that term.
  • Swarm.Language.Capability: definition of capabilities needed to use certain commands or language features.
  • Swarm.Language.Requirement: type and functions for dealing with requirements, i.e. what is needed to be able to build a robot executing a certain program. Includes capabilities as well as inventory.
  • Swarm.Language.Typed: values packaged together with their type and requirements.
  • Swarm.Language.Typecheck: the main type checking + inference algorithm.
  • Swarm.Effect.Unify: unification, i.e. solving equations between types.
    • Swarm.Effect.Unify: definition of a unification effect and some operations it supports.
    • Swarm.Effect.Unify.Common: common definitions (mostly re: substitution) used in implementations of unification.
    • Swarm.Effect.Unify.Naive: a slow-but-obviously-correct implementation of unification.
    • Swarm.Effect.Unify.Fast: a faster implementation of unification.
• Swarm.Language.Elaborate: term elaboration that happens after type checking.
• Swarm.Language.Pipeline: the entire term processing pipeline: parse -> type check -> requirements analysis -> elaborate.
• Swarm.Language.Pretty: pretty-printing for the Swarm language.
• Swarm.Language.Value: runtime values.
• Swarm.Language.LSP.*: implementation of the Language Server Protocol.

swarm-scenario

• Swarm.Constant
• Swarm.Util.Content
• Swarm.Util.Effect

swarm-engine

swarm-doc

swarm-tui

swarm-web