GitHub repository
Learn

Musi Book

Read Musi in chapter order through small beginner-first language chapters. Learning pages stay close to install steps and current commands.
InstallCommunity
LearnOpen bookMusi BookRead the main Musi book in order, without language-transition guides mixed into the path.GuidesOpen guidesMusi for DevelopersUse these when you already know another language and want a translation map.
Find docs
part / startOpenStartBegin with setup, one file, one binding model, one expression model, then explicit mutation.part / coreOpenCore SyntaxLearn everyday syntax in very small pieces so nothing stacks too early.part / dataOpenDataKeep data-shape learning readable by separating records, sequences, and patterns.part / organizationOpenCode OrganizationGrow from one file to packages without changing the mental model of code flow.part / typesOpenTypesIntroduce types gradually: explicit first, inferred second, generic third.part / abstractionsOpenAbstractionsSeparate behavior shape, concrete implementation, and semantic law into distinct chapters.part / effects-runtimeOpenEffects and RuntimeMake effect flow explicit, then place runtime and stdlib on top of that model.part / developersOpenMusi for DevelopersTranslate familiar habits into Musi without carrying over syntax that does not fit.
Learn · Musi Book

This is the main book. It moves from first file to syntax, data, types, effects, and tooling. Language guides are separate because they answer a different question.

Start
Open section
Begin with setup, one file, one binding model, one expression model, then explicit mutation.
Chapter»Getting StartedInstall tools, install Musi, and learn the two command lanes.Chapter»First ProgramWrite one file, bind one value, and run it end to end.Chapter»Reading Musi CodeRead declarations, imports, final expressions, type notes, and effect requests in the order a beginner sees them.Chapter»Values and LetUse let to name values, define callables, and understand when recursion needs let rec.Chapter»Blocks and ExpressionsTreat a block as one expression with setup at the top and the result at the bottom.Chapter»MutationUse mut only when changing a value helps more than rebuilding it.
Core Syntax
Open section
Learn everyday syntax in very small pieces so nothing stacks too early.
Chapter»LiteralsStart with numbers, strings, booleans, runes, and template text.Chapter»OperatorsRead arithmetic, comparison, and logic in ordinary expressions.Chapter»Tuples and UnitUse tuple expressions for small positional groups and unit when no payload matters.Chapter»RangesRead open, closed, and spread-like range forms without guessing.Chapter»FunctionsFunctions are ordinary let bindings with parameters, result types, and expression bodies.Chapter»CallsCall functions directly and follow argument flow left to right.Chapter»Dot CallsUse dot-callable functions through dot notation without needing an impl block.Chapter»LambdasUse lambda expressions when a short function value reads better in place.
Data
Open section
Keep data-shape learning readable by separating records, sequences, and patterns.
Chapter»RecordsBuild named-field values and access fields directly.Chapter»Arrays and SlicesStore ordered values and learn where slices fit.Chapter»Indexing and FieldsUse .field for named data and .[index] for positional access.Chapter»PatternsUse match and destructuring to branch on data shape.Chapter»Data DefinitionsUse data for named shapes, variant choices, payload fields, and record defaults.Chapter»Option and ResultUse Option for expected absence and Result for work that can explain why it failed.
Code Organization
Open section
Grow from one file to packages without changing the mental model of code flow.
Chapter»FilesKnow what a single file means before building a package.Chapter»PackagesMove from one file to package-managed code without changing mental models.Chapter»Imports and ExportsBring code in explicitly and expose only what other files need.
Types
Open section
Introduce types gradually: explicit first, inferred second, generic third.
Chapter»Type AnnotationsLearn the visible boundary markers for values, constraints, callable types, and data variants.Chapter»Callable TypesUse T -> U for pure callables and T ~> U for effectful callables.Chapter»Type InferenceSee what Musi can infer so you know when to write less.Chapter»GenericsWrite reusable functions over many types without losing clarity.Chapter»Type Tests and CastsUse :? to test a value against a type and :?> for an explicit cast.Chapter»Forall TypesUse forall when a type expression must bind a type variable explicitly.Chapter»Dependent TypesUse value-indexed types, indexed data results, partial, and ~= without turning Musi into a proof assistant.
Abstractions
Open section
Separate behavior shape, concrete implementation, and semantic law into distinct chapters.
Chapter»ClassesDescribe shared behavior with class declarations.Chapter»InstancesAttach concrete behavior to concrete types.Chapter»LawsUse laws to document the meaning of an abstraction, not just its shape.
Effects and Runtime
Open section
Make effect flow explicit, then place runtime and stdlib on top of that model.
Chapter»EffectsUnderstand effects as requests for work, not immediate hidden side effects.Chapter»Errors and RecoveryUse Option for absence, Result for explained failure, and effects for work that needs an outside answer.Chapter»Usingusing tells readers and the compiler which effects a callable may request.Chapter»HandlersResolve requested effects at the boundary where policy belongs.Chapter»FoundationUnderstand what belongs to musi:core before reaching for stdlib modules.Chapter»RuntimeUse musi:runtime for runtime-backed capabilities and host services.Chapter»StdlibReach for @std modules first in ordinary application code.
Advanced and Tooling
Open section
Keep sharp or advanced topics late, after ordinary code already feels natural.
Chapter»AttributesAttributes describe metadata, boundaries, and build-time intent without changing Musi into a macro language.Chapter»ForeignDeclare foreign bindings at the runtime boundary, not inside ordinary domain code.Chapter»Operator FormsUse fixity declarations and parenthesized operator names for advanced operator-heavy code.Chapter»Quote and SyntaxTreat code as data only after ordinary code reading feels natural.Chapter»Unsafe and FFIKeep raw pointer and native-call work behind a visible unsafe boundary.Chapter»ComptimeUse value-position comptime for constants, specialization, and generated syntax.Chapter»TestingWrite small package tests that read like ordinary code.Chapter»Running and ToolingFinish with the everyday command flow for checking, running, and building code.Chapter»Templates and SplicesUse template literals for interpolated text and splice forms when building syntax.
Guides · Musi for Developers

Use these pages only when you want to map C, Rust, Python, JavaScript, or another known language into Musi terms.

Musi for Developers
Open guides
Translate familiar habits into Musi without carrying over syntax that does not fit.
Section · 14»Musi for C DevelopersC99-specific contrasts for functions, structs, arrays, pointers, errors, packages, tests, and native boundaries.Section · 14»Musi for C++ DevelopersC++17-specific contrasts for functions, records, variants, templates, packages, tests, and native boundaries.Section · 14»Musi for C# DevelopersC#-specific contrasts for methods, records, collections, nullability, exceptions, interfaces, packages, tests, and native boundaries.Section · 15»Musi for Go DevelopersGo-specific contrasts for functions, structs, slices, nil, errors, concurrency, interfaces, packages, tests, and native boundaries.Section · 14»Musi for Java DevelopersJava-specific contrasts for methods, records, collections, nullability, exceptions, sealed types, interfaces, packages, tests, and native boundaries.Section · 12»Musi for JavaScript and TypeScript DevelopersSide-by-side contrasts for objects, functions, unions, generics, promises, modules, and tests.Section · 14»Musi for Lua DevelopersLua-specific contrasts for locals, functions, tables, nil, errors, coroutines, metatables, modules, tests, and native boundaries.Section · 13»Musi for Python DevelopersPython-specific contrasts for functions, blocks, objects, collections, errors, protocols, modules, tests, and native boundaries.Section · 11»Musi for Rust DevelopersRust-specific contrasts for mutation, data, traits, effects, and native boundaries.