tulam User Guide — Table of Contents

This is the chapter order and editorial map for the tulam User Guide. The guide teaches the language progressively; it does not replace or override the normative Language Reference. The current implementation status is owned by the Implementation Plan, with executable detail in the conformance catalog.

Why tulam exists

tulam aims to combine three qualities that are usually split across different languages: a high-level programming model, a dependent type system approaching the expressive territory of the Calculus of Constructions, and compilation to very different execution platforms without giving up their native ecosystems. The long-term goal is one language that can produce native code, integrate seamlessly with .NET and JavaScript, grow toward further targets, and still support aggressive optimization for numerical work.

That is intentionally ambitious—informally, “one language to rule them all.” The fact that the whole combination has not been achieved before is a reason to approach it carefully, not a reason to avoid trying. LLVM native is today’s reference implementation; the other target providers remain future work over the same checked, backend-neutral program.

The Markdown sources below are authoritative for the guide. Every chapter title links to its source, and their order is the HTML navigation order.

How chapters are written

Each chapter should normally contain:

1. the idea and why it is useful;
2. a smallest useful example;
3. a gentle explanation of the underlying concepts;
4. several worked examples, including composition with earlier material;
5. common mistakes and relevant diagnostics;
6. an implementation-status note where support is partial or planned;
7. a short recap and suggestions for further exploration; and
8. links to the corresponding normative reference sections.

Examples must use the canonical surface language. Features that are normative but not complete on the LLVM reference target must be clearly identified; the guide must never silently substitute an implementation quirk for the language contract.

Part I — Your first tulam programs

1. Welcome to tulam

What tulam is, the problems it explores, and its two central building blocks: n-ary tuples/telescopes and lambdas. Introduces the distinction between the language specification and what the current LLVM reference implementation can execute.

2. Installing tulam and editor support

Building with Stack, finding the compiler, installing syntax highlighting, and verifying the installation without assuming prior Haskell experience.

3. Your first program

A complete source file, a main entry point, checking it, compiling it for the native target, and running the resulting program. Explains declarations and separators only as far as the example needs them.

4. Check, run, build, and test

The everyday command-line workflow, the role of tulam.project.tl, products and profiles, and the canonical compiled shell.

5. A guided tour of the language

One small program that introduces values, functions, algebraic data types, pattern matching, structures, and effects. This is orientation rather than a compressed reference manual.

Part II — Everyday expressions and data

6. Source files, names, and modules

Module headers, imports and exports, qualified names, comments, identifiers, reserved versus contextual words, and declaration separators.

7. Values, literals, and basic types

Integers, floating-point values, strings, characters, booleans, unit, numeric negation, and how values acquire types.

8. Functions and lambdas

Named functions, anonymous fn expressions, parameter and result annotations, application, higher-order functions, implicit parameters, and functions as ordinary values.

9. Local definitions and decisions

Single and block let, sequential scope, local functions, if, and the basic shape of match expressions.

10. Algebraic data types and pattern matching

Empty and sum types, constructor fields, recursive types, construction, destructuring, nested patterns, exhaustiveness, and branch result types.

11. Tuples, records, and telescopes

Positional tuples, named records, structural and nominal records, field access, updates, spreads, open rows, and dependent fields. Explains why n-ary telescopes are fundamental rather than an encoding detail.

12. Operators, fixity, and annotations

Operator declarations and precedence, prefix and infix use, expression type annotations, and how parentheses remove ambiguity.

Part III — Understanding tulam’s type system

13. How to read a tulam type

Type application, function arrows, product and sum operators, associativity, and a practical method for reading larger type expressions.

14. Polymorphism and universes

Type parameters, forall, explicit universe levels, cumulativity, and the difference between a value type and a type constructor.

15. Dependent functions: Pi types

Functions whose result types depend on arguments, named Pi binders, substitution, relevance and erasure, and examples that go beyond ordinary parametric polymorphism.

16. Dependent products: Sigma types

Tuples whose later field types depend on earlier values, projections, dependent record-like data, and the relationship between Sigma types and general telescopes.

17. Existentials and GADTs

Packing information behind an interface, exists, unpack, constructor-local information, refinement through pattern matching, and where annotations are needed.

18. Equality, subtyping, and static guarantees

Definitional equality, controlled conversion, nominal subtyping, universe lifting, type annotations, positivity, termination, coverage, row constraints, and the meaning of compile-time rejection.

Part IV — Reusable abstractions

19. Structures, algebras, and morphisms

Defining reusable operations and constraints, the relationship between the three declaration forms, inheritance between structures, and single- versus multi-type abstractions.

20. Instances, constraints, and evidence

Declaring instances, requires clauses, implicit evidence at call sites, generic functions, selection, and the programmer-visible coherence rules.

21. Laws and deriving

Writing laws, attaching laws to structures, deriving instances, generated operations, typed semantic reflection, computed data codes, inferred evidence, proof obligations, and the difference between a declared law and a runtime test.

22. The standard library’s abstraction vocabulary

The core data types, numeric and comparison algebras, conversions, categorical structures, collection abstractions, and how to navigate the library without memorizing it.

Part V — Effects, resources, and evaluation

23. Effectful functions and operations

Effect declarations, operations, effect rows, pure versus effectful function types, row variables, and combining multiple capabilities.

24. Actions and sequencing

Action blocks, bindings, expression statements, sequencing, the value returned by a block, and desugaring into the relevant abstraction.

25. Handlers and resumptions

Handler declarations, handle ... with ..., return and finalization clauses, operation clauses, resumptions, effect propagation, deep handling, and lexical scope.

26. State, mutation, and managed resources

State effects, references, mutable arrays, file and console capabilities, resource safety, and the boundary between pure values and controlled mutation.

27. Explicit laziness

Lazy(a), delayed expressions, forcing, memoization, recursive values, and how explicit laziness differs from tulam’s ordinary evaluation strategy. The chapter must track the implementation plan closely while native support is incomplete.

28. Concurrency

The effect-based concurrency model, tasks, structured scopes, cancellation, channels, actors, STM, and parallel combinators. Examples must distinguish the specified language and library model from currently executable support.

Part VI — Objects, representation, and execution targets

29. Classes and objects

Class declarations, fields, construction, instance and static methods, dynamic dispatch, abstract and sealed classes, and when classes are more appropriate than algebraic data types.

30. Inheritance and safe casts

Single inheritance, overrides, final, super, nominal upcasts, checked downcast, and pattern matching on classes.

31. Primitives, intrinsics, and representations

Machine-level primitive types, compiler-provided intrinsic operations, repr mappings, invariants, default representations, and explicit as casts.

32. Targets, placement, and transfer

The abstract target model, the LLVM native reference target, declaration placement, module defaults, target implementations, on clauses, transfer, fallback, and how target availability affects compilation.

33. Foreign interoperability

Foreign types and calls, extern declarations, target-specific provider boundaries, data mapping, null and exception boundaries, and portability. Examples must be labeled according to their actual implementation status.

Part VII — Building and maintaining software

34. Projects, products, and dependencies

Project discovery, the typed manifest, products, source roots, profiles, dependencies, lockfiles, reproducible and offline builds, and project graphs.

35. Designing modules and libraries

Public APIs, export discipline, module organization, abstraction boundaries, instance ownership and coherence, versioning considerations, and documentation conventions.

36. Diagnostics and testing

Reading source-aware diagnostics, stages and stable codes, terminal and structured output, positive and negative tests, native assertions, and the surface-language conformance suite.

37. Native compilation and performance

What happens between checked source and a native artifact, entry points, specialization, runtime representation limits, profiling and benchmarking, and writing predictable code without relying on backend accidents.

Appendices

A. Syntax at a glance

Canonical declaration and expression forms, separators, reserved words, contextual words, and compact examples.

B. Operators and precedence

The built-in precedence table, user-declared fixity, and parenthesization examples.

C. Command-line reference

Compiler, project, product, profile, locking, offline, and diagnostic-output options.

D. Standard library map

Modules, major types, structures, instances, effects, and intended import paths.

E. Grammar map

A navigational grammar summary with direct links to the complete normative grammar, avoiding a second independently maintained grammar specification.

F. Implementation status and known gaps

How to read support callouts and conformance results, with links to the authoritative implementation plan and catalog rather than copied status counts that can become stale.

G. Glossary

Plain-language definitions of telescope, binder, universe, evidence, row, effect, handler, resumption, representation, target, and other recurring terms.

H. Further reading

Pointers from user-facing topics to the language, core, target, project, and focused design documents for readers who want implementation or design depth.

Language Reference coverage map

This matrix is an editorial completeness check. A chapter may explain more than one reference section, but every normative surface topic must have an obvious home in the guide.