spork@v0.6.0

Documentation

spork-lang 0.6.0

Install Spork, learn its core language model, use Python libraries directly, and take a project from source to distribution.

Browse documentation

Start

  • Getting startedInstall Spork, run a source file, explore the REPL, and create a project with its own reproducible toolchain.

Guides

  • Language tourA compact tour of Spork's syntax, functions, immutable collections, control flow, destructuring, macros, and async support.
  • Python interoperabilityUse Python modules and objects directly from Spork, and compile Spork packages into ordinary importable Python distributions.
  • Projects and toolingDeclare a reproducible Spork project, synchronize its isolated environment, check and test source, then build or publish it.

Language reference

  • Language referenceComplete semantics for Spork 0.6.0 lexical and reader syntax, forms, functions, types, namespaces, and Python interoperability.
  • Lexical syntaxUnderstand whitespace, comments, delimiters, atomic literals, symbols, and identifier normalization.
  • Reader macrosQuote forms, decorate declarations, create anonymous functions and slices, discard forms, use tagged literals, and evaluate trusted compile-time values.
  • Data structuresUnderstand Spork’s persistent collection literals and sequence model.
  • Forms and control flowDefinitions, bindings, conditionals, eager iteration, and tail recursion.
  • FunctionsAnonymous, named, multi-arity, variadic, keyword, and destructured functions.
  • Type annotationsEmit Python-compatible annotations and describe persistent collection types.
  • Pattern matchingMatch values and define pattern-dispatched functions.
  • Classes and protocolsDefine Python-compatible classes and protocol-based polymorphism.
  • Namespaces and modulesRequire Spork namespaces, import Python modules, and use dotted access.
  • MacrosDefine macros with quasiquoting, unquoting, and hygienic generated symbols.
  • Async and generatorsWrite async functions, eager async iteration, and Python generators.
  • ExceptionsCatch, throw, finalize, and assert with Python exception values.
  • Transient data structuresUse scoped mutable builders without changing persistent originals.
  • Python interoperability referenceCall Python, access attributes, use operators, context managers, and slices.
  • Errors and source mappingUnderstand source-mapped runtime, type, assertion, and syntax errors.

Standard library

  • Standard library referenceBuilt-in values, collection operations, prelude macros, and std.* modules in Spork 0.6.0.
  • Collection typesPersistent vectors, maps, sets, linked lists, sorted collections, keywords, and symbols.
  • Sequence operationsCore sequence access, persistent updates, conversion, and sequence predicates.
  • Transient operationsMutable builders for efficient batches over persistent collections.
  • Lazy sequences and realizationGenerator-backed transformations, finite realization, and effect-only consumption.
  • Reductions and transformationsReduce collections, inspect intermediate values, group, sort, split, and transform.
  • Numeric and bitwise operationsArithmetic helpers, comparisons, shifts, bit operations, and collection aliases.
  • Prelude macrosAutomatically loaded control flow, threading, utility, composition, predicate, and protocol macros.
  • std.stringString joining, splitting, trimming, searching, replacing, padding, and line handling.
  • std.mapPersistent map traversal, nested updates, merging, selection, filtering, and transformation.
  • std.jsonEncode and decode Spork persistent values with Python-compatible JSON behavior.
  • Python builtinsPython constructors, introspection, iteration, numeric functions, and object attributes available to Spork.

Tooling reference

  • Tooling referenceCreate and operate Spork projects with the manifest and package-aware CLI.
  • The spork.it manifestReference for project metadata, tooling settings, package APIs, and provider configuration.
  • Dependencies and environmentsManage requirements, isolated environments, synchronization, and compatible project toolchains.
  • Namespaces and entry pointsMap source paths to namespaces and load project entry points through the reusable runtime.
  • Project commandsReference for project-aware commands and standalone file execution.
  • Checks and testsValidate complete projects and run isolated synchronous or asynchronous test declarations.
  • Builds and distributionsCompile source, generate public APIs, and publish wheels and source distributions.
  • Command providersPublish package-owned top-level commands and understand metadata-only discovery and dispatch.
  • Tooling troubleshootingResolve project discovery, namespace, dependency, and editor integration problems.

Packages

  • PackagesPublished Spork packages, their supported boundaries, and complete public references.

spork-lang

  • spork-langThe Spork compiler, source runner, project manager, command system, REPL, and language server.

spork-runtime

  • spork-runtimeThe compiler-free Python runtime and standard namespaces used by generated Spork programs.

spork-pds

  • spork-pdsFast immutable persistent collections, transient builders, typed vectors, and native free-threading support.
  • Practical guideChoose collections, retain versions, batch updates, use buffers, and cross Python boundaries.
  • spork-pds APIConstructors, operators, protocols, methods, collection families, and transient lifecycle.
  • Design and complexityStructural sharing, trie and tree internals, operation costs, memory, and identity.
  • Native free-threadingThe no-GIL sharing contract, synchronization, validation, performance record, and wheel requirements.
  • Benchmark methodologyRun and interpret persistent collection and free-threading benchmark suites.

spork-state

  • spork-stateThread-safe validated and observable atoms with one Spork implementation and typed Python API.
  • Using atomsCreate, update, validate, watch, and subscribe to state from Python and Spork.
  • spork-state APIAtom construction, reads, updates, compare-and-set, watches, subscriptions, validators, and exports.
  • Atom design and concurrencyCommit linearization, reentrant locking, validation, notification, identity, and free-threaded behavior.

spork-site

  • spork-siteStructural markup, CommonMark content, deterministic static publishing, and full-rebuild development serving.
  • Getting started with spork-siteConfigure a source factory, synchronize the provider, and understand the publishing model.
  • Content and front matterDiscover CommonMark documents with persistent metadata, structural content, and canonical routes.
  • Document collectionsFilter, sort, and limit discovered documents with eager ordinary Spork values.
  • Routing and layoutsBuild components and layouts as ordinary functions and generate conflict-checked clean routes.
  • Builds and commandsConstruct deterministic site plans and use package-owned build, check, routes, serve, clean, and version commands.
  • Development serverServe isolated full-build generations, retain successful output after failures, and reload browsers safely.
  • Feeds and sitemapsGenerate deterministic XML sitemaps, RSS feeds, and Atom feeds from route-bearing document maps.
  • MarkupUse locally scoped $tag forms while components, conditions, data access, and iteration remain ordinary Spork.
  • Markdown, highlighting, and transformsConvert CommonMark into shared immutable nodes, apply structural highlighting, and transform trees post-order.
  • Node APIConstruct immutable elements, fragments, escaped text, and explicit trusted raw HTML.

Editors

  • EditorsMaintained Emacs and Neovim integrations for Spork source, evaluation, diagnostics, and navigation.
  • NeovimInstall and configure syntax, indentation, LSP diagnostics, navigation, completion, and commands.
  • EmacsInstall spork-mode and use nREPL evaluation, documentation, navigation, inspection, and completion.

Examples

  • ExamplesMaintained walkthroughs for first programs, async Python libraries, macros, command providers, and static sites.
  • First programRun a single Spork file using persistent collections, Python interop, matching, annotations, and a macro.
  • Async HTTPUse async functions, async context managers, await, and an ordinary Python dependency.
  • GitHub starsProfile network calls and rank API results with a macro, matching, and sorted-for.
  • Command providerDeclare, validate, build, install, and invoke a package-owned top-level Spork command.
  • Static siteBuild a source-only deterministic website using immutable markup and the package-owned top-level spork site command.

search all documentation →

Spork is a Lisp dialect hosted on CPython. It compiles forms to Python's abstract syntax tree, uses Python objects and exceptions directly, and adds the language features and project workflow expected from a modern Lisp.

What to expect#

Spork keeps its core model compact. Parentheses form calls and special forms, square brackets create persistent vectors, curly braces create persistent maps, and #{...} creates persistent sets. Hyphenated names are idiomatic in Spork and normalize naturally when code crosses into Python.

(defn greet [name]
  (fmt "Hello, {}!" name))

(for [name ["Ada" "Grace" "Edsger"]]
  (greet name))
; => ["Hello, Ada!" "Hello, Grace!" "Hello, Edsger!"]

The guides here focus on the shortest route to useful code. Continue with the complete language reference, standard library reference, and tooling reference.

Spork is young and evolving. Projects declare a compatible :spork-version range so their toolchain remains explicit and reproducible.