moonbit-lang

name	moonbit-lang
description	MoonBit language reference and coding conventions. Use when writing MoonBit code, asking about syntax, or encountering MoonBit-specific errors. Covers error handling, FFI, async, and common pitfalls.

MoonBit Language Reference

@reference/index.md @reference/introduction.md @reference/fundamentals.md @reference/methods.md @reference/derive.md @reference/error-handling.md @reference/packages.md @reference/tests.md @reference/benchmarks.md @reference/docs.md @reference/attributes.md @reference/ffi.md @reference/async-experimental.md @reference/error_codes/index.md @reference/toml-parser-parser.mbt

Official Packages

MoonBit has official packages maintained by the team:

• moonbitlang/x: Utilities including file I/O (moonbitlang/x/fs)
• moonbitlang/async: Asynchronous runtime with TCP, HTTP, async queues, async test, and async main

To use these packages:

1. Add the dependency: moon add moonbitlang/x or moon add moonbitlang/async
2. Import the specific subpackage in moon.pkg.json:

   {"import": ["moonbitlang/x/fs"]}
   

Common Pitfalls

• Use suberror for error types, raise to throw, try! func() |> ignore to ignore errors
• Use func() |> ignore not let _ = func()
• When using inspect(value, content=expected_string), don't declare a separate let expected = ... variable - it causes unused variable warnings. Put the expected string directly in the content= parameter
• Use !condition not not(condition)
• Use f(value) not f!(value) (deprecated)
• Use for i in 0..<n not C-style for i = 0; i < n; i = i + 1
• Use if opt is Pattern(v) { ... } for single-branch matching, not match opt {}
• Use arr.clear() not while arr.length() > 0 { arr.pop() }
• Use s.code_unit_at(i) or for c in s not s[i] (deprecated)
• Struct/enum visibility: priv (hidden) < (none)/abstract (type only) < pub (readonly) < pub(all) (full)
• Default to abstract (no modifier) for internal types; use pub struct when external code reads fields
• Use pub(all) enum for enums that external code pattern-matches on
• Use let mut only for reassignment, not for mutable containers like Array
• Use reinterpret_as_uint() for unsigned ops, to_int() for numeric conversion
• Use Array::length() not Array::size()
• In moon.pkg.json, use "import", "test-import" and "wbtest-import" to manage package importing for ".mbt", "_test.mbt" and "_wbtest.mbt"
• Use Option::unwrap_or not Option::or

Parser Style Reference

When writing a hand-written parser, follow the style in reference/toml-parser-parser.mbt (mirrored from moonbit-community/toml-parser).

• Prefer Parser::parse_* methods that advance a token view (view/update_view)
• Centralize error reporting (e.g. Parser::error) and include token locations
• Keep functions small (parse_value, parse_array, ...) and separate blocks with ///|