Docs
Start with the bookChapters use examples you can run and commands you can try.
Home
What is Musi?
Musi is a programming language where most code gives a value. It has pattern matching, effects, and a small set of commands. Learn the language, install Musi, check the playground, and find project links from one site.
- Most code gives a value, so data is easier to follow.
- Install from source. Use musi for a project and music for one file.
- Learn, install, playground, and project links each have their own page.
Start with one value, one function, and one final result. This matches Musi's beginner path.
Musi reads top to bottom. Bind values with let, define small functions the same way, then end with the result you want.
let base := 21;
let twice (x : Int) : Int := x + x;
let reply := twice(base);
reply;Status
Install
Install from sourceBuild Musi from source. Use musi for a project. Use music for one file.
Playground
Not ready yetThe browser runner is not ready. Install Musi to run code now.
Primary paths · Choose a path
Start hereOpen bookRead Musi BookStart with setup. Then learn syntax, data, types, effects, and commands.I know what I needOpen install pathInstall and CommandsGo straight to needed tools, install commands, and when to use musi or music.Unusual casesOpen project linksSource, issues, and FFIFind project links, unsafe/FFI docs, and GitHub issues.
Learn · Find docs
Search chapters, effects, types, operators, and command questions.
part / StartOpenStartBegin with a small file, a few names, and one result.part / Core expressionsOpenCore expressionsRead values, calls, operators, functions, and small sequence expressions.part / DataOpenDataUse visible data shapes and match them directly.part / OrganizationOpenOrganizationMake names easy to find and reuse.part / TypesOpenTypesUse annotations, callable types, generics, and checks.part / AbstractionsOpenAbstractionsKeep data separate from behavior.part / Effects and runtimeOpenEffects and runtimeMake outside work visible at the call site.part / Advanced formsOpenAdvanced formsReach lower-level features after the core syntax is clear.chapter / StartOpenGetting startedMusi source files end in `.ms`. Start with one small file and run one command.chapter / StartOpenFirst programA Musi file reads from top to bottom. The last expression can be the result for direct file checks.chapter / StartOpenReading Musi codeFirst find names, imports, exports, and final expressions. Then read each body.chapter / StartOpenValues and
let`let` gives a name to a value. `export let` makes the name public.chapter / StartOpenCommentsUse comments for why, doc comments for public names, and names or types for what.chapter / StartOpenBlocks and expressionsUse parenthesized sequence expressions for local steps, and braces for structural forms.chapter / StartOpenMutationMutation is visible. Reassignment writes to an existing mutable place.chapter / Core expressionsOpenLiteralsLiterals create values directly. They do not call another name.chapter / Core expressionsOpenTuples and unitA tuple groups values by position. Unit means no useful value.chapter / Core expressionsOpenOperators`:=` writes, `=` compares, arrows describe callables, and pipelines pass values forward.chapter / Core expressionsOpenAssignment and equality`:=` stores a value. `=` checks equal values. `/=` checks different values.chapter / Core expressionsOpenMath and comparison`+`, `-`, `*`, `/`, and `%` compute numbers. `<`, `<=`, `>`, and `>=` compare them.chapter / Core expressionsOpenLogic and bits`and`, `or`, `xor`, and `not` combine checks. `shl` and `shr` shift integer bits.chapter / Core expressionsOpenPipelines and access`|>` passes a value forward. `.` reads fields. `.[index]` reads an ordered item.chapter / Core expressionsOpenType operators`:` annotates, `:?` tests a runtime type, and `:?>` casts.chapter / Core expressionsOpenCallable arrows`->` describes a callable type. `~>` describes an effectful callable. `=>` starts a lambda body.chapter / Core expressionsOpenRangesA range stores start and end information. Inclusivity belongs to the range value.chapter / Core expressionsOpenFunctionsFunctions are named values. Parameters and result types stay near the name.chapter / Core expressionsOpenLambdasA lambda starts with `\\`. This keeps it separate from tuples and grouped expressions.chapter / Core expressionsOpenCallsA call evaluates a callable value and passes arguments to it.chapter / Core expressionsOpenDot-callsA receiver call keeps the value being acted on at the front.chapter / DataOpenRecordsA record keeps related values together and names each field.chapter / DataOpenArrays and slicesArrays keep values in order. Slices let code talk about part of that order.chapter / DataOpenIndexing and fieldsDot access reads a field. Indexed access reads by position.chapter / DataOpenData definitions`data` creates a type-shaped value. Variants use `|`. Record fields use `;`.chapter / DataOpenPatternsPatterns let `match` read variants, fields, and simple values.chapter / DataOpenOption and resultOption means value or no value. Result means success or error.chapter / OrganizationOpenFilesA file is the first unit a reader opens. Keep it small and focused.chapter / OrganizationOpenPackagesA package gives files a home and declares how the project runs.chapter / OrganizationOpenImports and exports`export` shares a name. `import` brings shared names into a file.chapter / OrganizationOpenStandard libraryStandard library modules hold common data and helper functions.chapter / TypesOpenType annotationsA type annotation says what kind of value a name should hold.chapter / TypesOpenCallable typesCallable types describe functions and effectful calls.chapter / TypesOpenType inferenceMusi can infer many local types from the expression on the right.chapter / TypesOpenGenericsGenerics let code keep one shape while the item type changes.chapter / TypesOpenType tests and castsType tests ask about a type. Casts assert a type.chapter / TypesOpenOptional and fallible typesOptional and fallible types keep missing values and errors visible.chapter / AbstractionsOpenShapesA shape says which behavior a type must provide.chapter / AbstractionsOpenGiven valuesA given value says how a type follows a shape.chapter / AbstractionsOpenLawsA law states an expected rule for a shape or behavior.chapter / AbstractionsOpenContextual capabilitiesA contextual capability lets code ask for behavior without passing it by hand each time.chapter / Effects and runtimeOpenEffectsAn effect names an operation that asks for an answer from outside normal value flow.chapter / Effects and runtimeOpenAsk, answer, handle`ask` performs an effect operation. A handler can answer and resume.chapter / Effects and runtimeOpenRequirementsA requirement makes needed ability visible near the function.chapter / Effects and runtimeOpenRuntime modulesRuntime modules help code read values from the running environment.chapter / Effects and runtimeOpenFoundation and standard librarySome modules provide core names. Standard library modules provide common app tools.chapter / Advanced formsOpenAttributesAttributes add extra information to declarations.chapter / Advanced formsOpenNative and unsafe`native` declares a host edge. `unsafe` marks code that needs extra care.chapter / Advanced formsOpenQuote and syntax`quote` builds syntax. Splices insert known syntax pieces.chapter / Advanced formsOpenTemplates and splicesTemplates build text from fixed parts and values.chapter / Advanced formsOpenTesting and runningUse commands to check one file, check a package, and run tests.No matching docs yet. Try a command, type, effect, or operator.
Learn · Why Musi
Expression-first
Read files from top to bottom with let, match, and code that gives values.
Effects stay clear
Use effects and handlers without extra setup code.
Two commands
Use musi for a project. Use music for one file or one built file.
Clear site pages
Learn, Install, Playground, and Community each have one clear job.
Learn · Parts and ChaptersLearn
7 chaptersOpen sectionStartBegin with a small file, a few names, and one result.14 chaptersOpen sectionCore expressionsRead values, calls, operators, functions, and small sequence expressions.6 chaptersOpen sectionDataUse visible data shapes and match them directly.4 chaptersOpen sectionOrganizationMake names easy to find and reuse.6 chaptersOpen sectionTypesUse annotations, callable types, generics, and checks.4 chaptersOpen sectionAbstractionsKeep data separate from behavior.5 chaptersOpen sectionEffects and runtimeMake outside work visible at the call site.5 chaptersOpen sectionAdvanced formsReach lower-level features after the core syntax is clear.