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-topography: working with locations in 2D (sub-)worlds
• 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.Failure: data type and utilities for representing system failures.
• Swarm.Pretty: generic pretty-printing infrastructure.
• Swarm.ResourceLoading: infrastructure for locating and loading data files.
• 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. Unless otherwise noted all module names listed below begin with Swarm.Language.

• Syntax
  • Types: Swarm language types and utilities for working with them.
  • Direction: directions (right, left; north, south; etc.)
  • Syntax: the main module defining the abstract syntax of the Swarm language.
• Parsing
  • Parser: defines top-level function readTerm for parsing an expression of the Swarm language, returning an AST annotated with source locations and comments.
  • 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
  • Key: data type, parsing + pretty printing for keys (i.e. key presses).
• Checking
  • Context: mappings from variables to information about them (types, requirements, ...)
  • Module: a module is a typechecked term together with a context of names defined in that term.
  • Capability: definition of capabilities needed to use certain commands or language features.
  • 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.
  • Typed: values packaged together with their type and requirements.
  • Typecheck: the main type checking + inference algorithm.
  • 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.
• Elaborate: term elaboration that happens after type checking.
• Pipeline: the entire term processing pipeline: parse -> type check -> requirements analysis -> elaborate.
• Pretty: pretty-printing for the Swarm language.
• Value: runtime values.
• LSP.*: implementation of the Language Server Protocol.

swarm-topography

• Location
• Universe
• World.Coords
• Scenario.Topography.*

swarm-scenario

First, some miscellaneous modules.

• Swarm.Constant: miscellaneous constants, e.g. URLs
• Swarm.Util.Content: utilities for extracting content (terrain and entities) from the world map.

All the rest of the modules live under the Swarm.Game namespace.

• Entities + terrain:
  • Display: A Display tracks information needed to render terrain and entities in a single cell.
  • Terrain
  • Entity
  • Entity.Cosmetic
  • Entity.Cosmetic.Assignment
  • Device
  • Ingredients
  • Recipe
  • Land
• State.Config
• State.Landscape
• Robots
  • Robot
  • Robot.Walk
• World DSL
  • World.*
• Achievement.Definitions
• Scenarios
  • Scenario
  • Scenario.*

swarm-engine

swarm-doc

swarm-tui

swarm-web