Skip to main content

20251014 MoonBit Monthly Update Vol.04

· 4 min read

Version v0.6.29​

Language Updates​

  • Asynchronous Programming Enhancements

    Added support for async test and async fn main syntax, enabling asynchronous tests and asynchronous main functions. Both async fn main and async test are based on the moonbitlang/async library and are currently supported on the native backend for Linux and macOS. For more details about async programming in MoonBit, see the documentation and GitHub repository of moonbitlang/async. Async tests declared with async test will run in parallel.

    ///|
async test "http request" {
  let (response, result) = @http.get("https://www.example.org")
  inspect(response.code, content="200")
  assert_true(result.text().has_prefix("<!doctype html>"))
}

  • Experimental Feature: lexmatch Expression

    Added the lexmatch expression (experimental feature), which enables pattern matching on StringView or BytesView using regular expressions.

    The following example matches two to four consecutive 'a' characters followed by a 'b', capturing the consecutive 'a's as variable a. For more detailed usage, refer to lexer.mbt in moonbitlang/parser and the lexmatch proposal in moonbit-evolution.

    lexmatch x with longest {
  (("a{2,4}" as a) "b", _) => Some(a.length())
  _ => None
}

  • Unified Import Syntax with using

    Introduced the using syntax, which unifies fnalias, traitalias, and simple typealias. When importing a type or trait, the corresponding keyword must now be prefixed before the name.

    using @pkg {
  value,
  CONST,
  type Type,
  trait Trait,
}

    In addition, pub using can be used to achieve re-export, allowing definitions from other packages to be re-exported in the current package. In the future, the fnalias, traitalias, and simple typealias syntaxes will be deprecated — the functionality of creating aliases for external definitions will be replaced by using, while creating aliases for definitions within the current package will be handled by the #alias attribute.

  • Methods in a trait now support optional parameters.

    pub(open) trait Reader {
  async read(Self, buf : FixedArray[Byte], offset? : Int, len? : Int) -> Unit
}

    The default value of an optional parameter is determined individually by each impl. Different implementations can define their own default values or choose not to provide one at all — in that case, the optional parameter’s type within the impl will be T?, where None indicates that the user did not supply the argument.

  • Operator Overloading via #alias

    Added support for using #alias to overload operators such as op_get, providing better readability compared to the op_xxx naming convention.

    // Previously `op_get`
#alias("_[_]")
fn[X] Array::get(self : Array[X], index : Int) -> X { ... }

// Previously `op_set`
#alias("_[_]=_")
fn[X] Array::set(self : Array[X], index : Int, elem : X) -> Unit { ... }

// Previously `op_as_view`
#alias("_[_:_]")
fn[X] Array::view(
  self : Array[X],
  start? : Int = 0,
  end? : Int = self.length(),
) -> ArrayView[X] { ... }

    Currently, the following operators are supported. The actual implementation names (e.g., get, set, view) can be freely chosen — simply attach the corresponding #alias to enable operator overloading. It is recommended to use #alias instead of op_xxx for method-based operator overloading. (Note: Operators like + are overloaded through traits and are not affected by this change.)

  • Removal of Long-Deprecated Syntax and Behaviors

    Several language features that had been deprecated for a long time have now been officially removed:

    Previously, methods defined in the form fn meth(self : T, ..) were both methods and regular functions, allowing them to be called directly as standalone functions. This behavior had long been deprecated (with compiler warnings) and is now removed. The declaration fn meth(self : T, ..) is now equivalent to fn T::meth(self : T, ..). In the future, the self-form method definition itself may also be deprecated.

    The direct_use field in moon.pkg.json has been officially removed and replaced by using.

Toolchain Updates​

  • Wasm Toolchain Released — The Wasm version of the MoonBit toolchain is now available for x86 Darwin and ARM Linux users. 🔗 Read more

  • Experimental Build System (RR) — A new experimental version of the build system, codenamed RR, has been introduced. It offers higher performance and better maintainability, and will eventually replace the current internal implementation of moon. You can enable it using the environment variable NEW_MOON=1 or the command-line flag -Z rupes_recta. If you encounter any issues, please report them on GitHub Issues.

  • moon fmt Enhancements — Now supports formatting of .mbt.md files.

  • moon info --no-alias Option — Added a new option to hide type aliases when generating the pkg.generated.mbti file.

Standard Library Updates​

  • Improved Hash Security — To mitigate potential HashDoS attacks, hash computation is now randomized per process. This change has already been implemented in the JS backend.

  • Immutable ArrayView — ArrayView has been changed to an immutable data structure, providing a unified slicing interface for Array, FixedArray, and ImmutArray.

20250908 MoonBit Monthly Update Vol.03

· 4 min read

Language Updates​

  1. Support for Bitstring Patterns

  • Added support for Bitstring patterns, enabling matching of specific-width bits when pattern matching on Bytes or @bytes.View, for example:

    pub fn parse_ipv4(ipv4 : @bytes.View) -> Ipv4  {
  match ipv4 {
    [ // version (4) + ihl (4)
      u4(4), u4(ihl),
      // DSCP (6) + ECN (2)
      u6(dscp), u2(ecn),
      // Total length
      u16(total_len),
      // Identification
      u16(ident),
      // Flags (1 reserved, DF, MF) + Fragment offset (13)
      u1(0), u1(df), u1(mf), u13(frag_off),
      // TTL + Protocol
      u8(ttl), u8(proto),
      // Checksum (store; we'll validate later)
      u16(hdr_checksum),
      // Source + Destination
      u8(src0), u8(src1), u8(src2), u8(src3),
      u8(dst0), u8(dst1), u8(dst2), u8(dst3),
      // Options (if any) and the rest of the packet
      .. ] => ...
    ...
  }
}

    You can use u<width>be or u<width>le to match bits of the specified width in big-endian or little-endian order. If neither be nor le is specified, big-endian is used by default. The valid width range is [1, 64].

  1. Direct use of constructors in pattern matching
  • Allowed direct use of constructors in pattern matching to match only the tag of an enum, for example: 
    fn is_some(x: Int?) -> Unit {
  guard x is Some
}
    Previously, using a constructor with a payload as if it had none would result in a compiler error. This has now been changed to a warning, allowing users to disable such warnings via the warn-list parameter.

  1. Added #callsite(migration) attribute for code migration of optional arguments.

    For example, if the author wants to change the default value of parameter y in the next version, they can use migration(fill=true, ...) to prompt downstream users to explicitly provide a value. Similarly, if the optional parameter z is planned to be removed in the next version, migration(fill=false, ...) can be used to notify users that they no longer need to explicitly provide z.

    #callsite(migration(y, fill=true, msg="must fill y for migration"), migration(z, fill=false, msg="cannot fill z for migration"))
fn f(x~ : Int, y~ : Int = 42, z? : Int) -> Unit {
  ...
}

  2. Added #skip attribute to skip tests, for example:

    #skip("Reason for skipping")
test "will not run" {
  ...
}

    However, the compiler will still perform type checking on the code inside the test block.

  3. Added #as_free_fn attribute as a replacement for the fnaIias Type::f functionality, for example:

    #as_free_fn // allow MyType::f to be called as f
#as_free_fn(f0) // allow MyType::f to be called as f0
#as_free_fn(f1, deprecated) // allow MyType::f to be called as f1, but with deprecated message
fn MyType::f(self : MyType) -> Unit {
  ...
}

    This allows MyType::f to be called directly as a regular function f or f0.

  4. Added visibility control to #alias and #as_free_fn, for example:

    #as_free_fn(visibility="pub")
fn MyType::f(self : MyType) -> Unit {
  ...
}

    In this case, the MyType::f method is private, but its free function f is public. The same applies to #alias in the following example.

    #alias(pub_alias, visibility="pub")
fn priv_func() -> Unit {
  println("priv func")
}

  5. Async functions now implicitly raise.

  • Functions marked with async no longer need an explicit raise, making the code more concise. If you want type checking to ensure that an async function does not throw errors, you can mark it with noraise.
  1. FFI parameter ownership annotations required.

  • In the C/LLVM/Wasm backends, parameters declared as pointers in FFI must now be annotated with either #borrow or #owned; otherwise, the compiler will emit a warning. #borrow means the called FFI function will only read or write the parameter locally and will not store or return it, so no special handling is required. #owned means ownership of the parameter is transferred to the called function.

    For details, see the documentation on external function calls. The motivation for this change is that in the future we plan to switch the default calling convention for FFI parameters from #owned to #borrow, and explicit annotations help users migrate progressively.

  1. Changed calling convention of FuncRef[_].
  • Previously, FuncRef[_] treated parameter ownership as #owned. It has now been changed to #borrow. This change is breaking: users who use FuncRef[_] in FFI and have pointer-type parameters must update their code accordingly.

Toolchain Updates​

  • IDE now supports hover and go-to-definition features for .mbti files.

20250811 MoonBit Monthly Update Vol.02

· 5 min read

Language updates​

  1. New conditional compilation attribute cfg.
  • You can now compile specific sections of code based on conditions such as the target backend. 
    #cfg(any(target="js", target="wasm-gc"))
let current_target = "js | wasm-gc"
  1. New #alias attribute.
  • You can now create aliases for methods or functions and attach annotation information. More scenarios will be supported in the future.。 
    #alias(combine, deprecated="use add instead")
fn Int::add(x : Int, y : Int) -> Int {
  x + y
}

test {
  let _ = Int::add(1, 2)
  let _ = Int::combine(1, 2)
}
  1. New defer statement.
  • Provides a scope-based resource cleanup feature. When any form of defer expr; body appears in the body of a block, the expr will always be executed when the body ends. 
    fn main {
  defer println("End of main")
  {
    defer println("End of block1")
    println("block1")
  }
  for i in 0..<3 {
    defer println("End of loop \{i}")
    if i == 2 {
      break // `break` and similar statements can also trigger `defer`
    }
    println("Looping \{i}")
  }
  return
}
    block1
End of block1
Looping 0
End of loop 0
Looping 1
End of loop 1
End of loop 2
End of main
    Currently, the expr in a defer expr cannot contain expressions or calls to async functions, and expr cannot use control flow constructs such as return / break / continue.
  1. Native Backend Bytes Terminator Update
  • In the Native backend, the Bytes representation used to always have an extra trailing '\0' character. Now, Bytes can be directly used to pass C strings in FFI calls without this extra trailing '\0' character being counted in the Bytes length, so the current code behavior will remain unchanged.
  1. Optional Parameter Syntax Enhancement and Unification
  • Adjusted the syntax for optional parameters: default arguments can now depend on preceding parameters (this behavior was previously removed due to incompatibility with virtual packages, but we have now found a way to support such complex defaults while remaining compatible).We have also unified optional parameters with default values (label: T = ...) and those without (label?: T). From the caller’s perspective, there is no longer any difference between them, and both now support the following call styles:
    • Omit the argument to use the default value.
    • Pass explicitly using label=value.
    • Use label?=opt, meaning: if opt is Some(value), it is equivalent to label=value; if opt is None, it is equivalent to omitting the argument.
  1. Use #callsite(autofill(...)) as a shorthand for default arguments.

  • When calling functions with default arguments, the #callsite(autofill(...)) attribute can be used as a shorthand:

      // Original code
  pub fn[T] fail(msg : String, loc~ : SourceLoc = _) -> T raise Failure { ... }
  // new code
  #callsite(autofill(loc))
  pub fn[T] fail(msg : String, loc~ : SourceLoc) -> T raise Failure { ... }
  1. Removed newtype

  • added support for tuple struct.

      // Old syntax, accessing the wrapped Int
  type A Int
  fn get(a : A) -> Int {
    a.inner()
  }

  // New syntax, accessing the wrapped Int
  struct A(Int)
  fn get(a : A) -> Int {
    a.0
  }

  struct Multiple(Int, String, Char)
  fn use_multiple(x: Multiple) -> Unit {
    println(x.0)
    println(x.1)
    println(x.2)
  }
  fn make_multiple(a: Int, b: String, c: Char) -> Multiple {
    Multiple(a, b, c)
  }

  • For a tuple struct with one field, it is equivalent to the original newtype. If the underlying type is not a tuple, the formatter will auto-migrate old access syntax. In this case, an .inner() method is provided for migration and will be deprecated later.

  • For a tuple struct with multiple fields, differences from the original tuple newtype are:

    • Cannot be constructed directly with tuple syntax.
    • No .inner() method to retrieve the tuple.

    For tuple structs that support conversion to a tuple, you can use:

    struct T((Int, Int))

fn make_t(x: Int, y: Int) -> T {
  (x, y)
}

fn use_t(t: T) -> (Int, Int) {
  t.0
}

  • In this case, to access specific elements, you need to use t.0.0 or t.0.1.

  1. Since the primary purpose is for data storage and functions such as @json.inspect, derive(FromJson, ToJson) will no longer provide advanced format adjustment parameters.
  • The currently retained format parameters are: rename for each field, batch renaming, and the style option for enum format selection; all other parameters will be removed.
    • The optional values for style are legacy and flat. The latter simplifies representation and is suitable for scenarios such as @json.inspect. All enums must currently choose one of these styles.
    • If you need to customize the JSON format, please implement the FromJson and ToJson traits yourself.
    ///| Flat
test {
  @json.inspect(Cons(1, Cons(2, Nil)), content=["Cons", 1, ["Cons", 2, "Nil"]])
}

///| Legacy
test {
  @json.inspect(Cons(1, Cons(2, Nil)), content={
    "$tag": "Cons",
    "0": 1,
    "1": { "$tag": "Cons", "0": 2, "1": { "$tag": "Nil" } },
  })
}

Toolchain update​

  1. Added moon coverage analyze for clearer coverage reports.
Total: 1 uncovered line(s) in 2 file(s)

1 uncovered line(s) in src/top.mbt:

   | fn incr2(x : Int, step? : Int = 1) -> Int {
12 |   x + step
   |   ^^^^^^^^         <-- UNCOVERED
   | }
   …

Total: 1 uncovered line(s) in 2 file(s)
  1. moon test --target js now shows original source locations on panic via sourcemap.
test username/hello/lib/hello_test.mbt::hello failed: Error
    at $panic ($ROOT/target/js/debug/test/lib/lib.blackbox_test.js:3:9)
    at username$hello$lib_blackbox_test$$__test_68656c6c6f5f746573742e6d6274_0 ($ROOT/src/lib/hello_test.mbt:3:5)
    at username$hello$lib_blackbox_test$$moonbit_test_driver_internal_execute ($ROOT/src/lib/__generated_driver_for_blackbox_test.mbt:41:9)

20250714 MoonBit Monthly Update Vol.01

· 2 min read

After the beta release on June 18, 2025, Moonbit's syntax will be more stable, and our focus will gradually shift towards performance improvements and ecosystem development. Starting with this announcement, Moonbit updates will be released monthly, with the primary content still centered on language, standard library, and toolchain enhancements.

Language Updates​

  • Support for !expr syntax. Boolean expressions can now be directly negated using the ! symbol, without needing the not function.
fn true_or_false(cond: Bool) -> Unit {
  if !cond {
    println("false branch")
  } else {
    println("true branch")
  }
}

fn main {
  true_or_false(true)  // true branch
  true_or_false(false) // false branch
}
  • The else keyword in try .. catch .. else .. syntax has been replaced with noraise. This change was made because the else in try .. catch .. else .. is followed by pattern matching rather than a code block, which is inconsistent with else elsewhere. The old syntax will be deprecated, and the compiler will issue a warning.
  • Functions can now be marked noraise in their return type. This provides clearer documentation in type signatures and can prevent the compiler from automatically inserting a raise mark in certain situations. For example:
fn h(f: () -> Int raise) -> Int { ... }

fn init {
  let _ = h(fn () { 42 }) // ok
  let _ = h(fn () noraise { 42 }) // not ok
}
  • Ellipsis (...) is now allowed to omit code in pattern matching. For example:
fn f(x: Int) -> Unit {
  match x {
    ...
  }
}

Toolchain Updates​

  • More powerful code coverage testing. You can now use the moon coverage analyze command to directly identify unused lines of code. For example:
fn coverage_test(i : Int) -> String {
  match i {
    0 => "zero"
    1 => "one"
    2 => "two"
    3 => "three"
    4 => "four"
    _ => "other"
  }
}

test "coverage test" {
  assert_eq(coverage_test(0), "zero")
  assert_eq(coverage_test(1), "one")
  assert_eq(coverage_test(2), "two")
  // assert_eq(coverage_test(3), "three")
  assert_eq(coverage_test(4), "four")
  assert_eq(coverage_test(5), "other")
}
  • Running moon coverage analyze on the code above will first execute the tests and then print the lines not covered during test execution, as shown below:
  ❯ moon coverage analyze
Total tests: 1, passed: 1, failed: 0.

warning: this line has no test coverage
 --> main/main.mbt:6
4 |     1 => "one"
5 |     2 => "two"
6 |     3 => "three"
  |     ^^^^^^^^^^^^
7 |     4 => "four"
8 |     _ => "other"
  • This tool will be a great help in guiding your testing efforts.

Standard Library Updates​

  • Reminder: JSON data definitions will change in the next version. Please do not directly use constructors; instead, use functions like Json::number to construct JSON values.

2025-06-16

· 6 min read

Language Updates​

  1. Error Function Syntax Updated to raise

  • The ! syntax for representing errors has been replaced with the keyword raise. The specific mappings are as follows:

    • (..) -> T ! SomeErr => (..) -> T raise SomeErr

    • (..) -> T ! => (..) -> T raise

    • (..) -> T ? Error => (..) -> T raise? (This is a recently added error polymorphism syntax; it can be ignored if unfamiliar.)

    • fn f!(..) { .. } => fn f(..) raise { .. }

    • fn!( ..) { .. } => fn (..) raise { .. }

    The above changes can be auto-migrated using code formatting.

  1. Error Type Declaration Syntax Changed
  • The syntax for defining error types, type! T .., has been changed to suberror T ... This change can also be automatically migrated using code formatting.
  1. Deprecation of f!(..) and f?(..)
  • The f!(..) and f?(..) syntaxes have been deprecated. Continued use of them will trigger compiler warnings. Code formatting can automatically remove ! for migration, but f?(..) requires manual migration to try?. This is because for cases like f?(g!(..)), a simple change to try? f(g(..)) would alter the semantics, causing errors in g to also be caught. Special attention is needed during manual migration of f?(..).
  1. Function Type Parameter Syntax Aligned with impl
  • Several weeks ago, the position of type parameters in function definitions was moved from fn f[..](..) to fn[..] f(..) to align with impl. Now, the old syntax is deprecated and will trigger compiler warnings. This change can be automatically migrated using code formatting.
  1. Simplified Syntax for typealias and traitalias

  • Use typealias B as A and traitalias B as A instead of typealias A = B and traitalias A = B. Example:

    Old: typealias Matrix[X] = Array[Array[X]]

    New: typealias Array[Array[X]] as Matrix[X]

    This change can be auto-migrated.

  1. Multi-parameter loop syntax deprecated
  • The multi-parameter loop syntax has been deprecated and should be replaced with a loop that takes a tuple as its parameter. This change aligns loop with match more consistently. The MoonBit compiler can optimize away the overhead of tuples in loop in release mode, so there is no need to worry about performance impacts.
  1. Trait Method Implementation Now Explicit
  • For traits where "every method has a default implementation," previously all types would automatically implement them. Now, even if all methods of a trait have default implementations, explicit implementation is still required. If no custom implementation is needed, impl Trait for Type can be used to indicate "implement Trait for Type using all default methods." impl Trait for Type can also serve as documentation or a TODO. MoonBit will automatically check whether Type implements Trait and report an error if it does not.
  1. Cannot Use Dot Syntax Call Implementation Method for External Types

  • Previously, impl for external types could be called within the current package using .. However, this feature was not refactoring-safe: upstream additions of methods could alter the behavior of downstream code. Therefore, this behavior has been deprecated. As an alternative, MoonBit now supports locally defining new methods for external types, with syntax identical to regular method definitions. Methods defined for external types have the following characteristics:

    • They cannot be pub. This ensures no conflicts arise during cross-package collaboration.

    • If the upstream package (where the type is defined) already has a method with the same name, the compiler will issue a warning.

    • Local methods have the highest priority during method resolution.

    After this change, the resolution rules for x.f(..) are as follows (in order of priority):

    1. Local methods
    2. Methods from the package where x's type is defined
    3. impl from the package where x's type is defined
  1. Auto Insertion of to_json for JSON Literals
  • Within JSON literals, the compiler now automatically inserts ToJson::to_json calls for non-literal expressions, making JSON literals more convenient to write:
let x = 42
// Previously
let _ : Json = { "x": x.to_json() }
// Now
let _ : Json = { "x": x }
  1. Virtual Package Support for Abstract Types
  • The virtual package feature now supports abstract types. Abstract types can be declared in .mbti interfaces, and different implementations can use different concrete types to fulfill the interface's abstract types.
  1. Simplified Syntax for Error Handling
  • For handling errors in simple expressions, try can be omitted, and f(..) catch { .. } can be written directly.
  1. Reserved Words Warning Mechanism
  • A new set of reserved words has been added. These are not currently keywords but may become keywords in the future. Using these names in code will trigger compiler warnings.

Upcoming Changes to Be Released Before the MoonBit Beta on June 18​

  1. New Arrow Function Syntax (..) => expr

    This syntax simplifies defining single-parameter inline functions. Example:

test {
  let arr = [ 1, 2, 3 ]
  arr
    .map(x => x + 1) // Parentheses can be omitted for single parameters
    .iter2()
    .each((i, x) => println("\{i}: \{x}"))
}

  1. Matrix Function Syntax Simplified

    Matrix functions have been deprecated to simplify the syntax. Matrix functions of the form fn { .. => expr } can be replaced with arrow functions, while other matrix functions should be replaced with explicit fn and match.

  2. Deprecation of xx._ Syntax in new type Definitions

    Previously, the xx._ syntax could be used to convert a newtype into its underlying representation. However, this syntax was visually ambiguous with partial application syntax (_.f(..)). Therefore, the xx._ syntax has been deprecated. Instead, the compiler will automatically generate an .inner() method for each newtype to replace ._. This change can be automatically migrated using code formatting.

  3. Warnings on Ambiguous Precedence

    For ambiguous or less widely known operator precedence combinations, such as << and +, MoonBit will now issue warnings. Adding parentheses manually or via code formatting will resolve the warnings.

  4. Introduction of letrec and and for Local Mutual Recursion

    The letrec and and keywords have been introduced for declaring locally mutually recursive functions, e.g.:

fn main {
  letrec even = fn (x: Int) { ... } // Anonymous function
  and odd = x => ... // Arrow function
}
  • The right-hand side of the equals sign must be a function-like value, such as an anonymous function or arrow function. The previous implicit mutual recursion syntax using fn will be deprecated, though self-recursive functions can still be declared with fn.*

  1. fnalias Cannot Be Used to Define Non-Function values

    The fnalias keyword is now restricted to function definitions only. Use let to define other types of values.

Standard Library Updates​

  • Leveraging the new error polymorphism feature, many higher-order functions in the standard library, such as Array::each, can now accept callback functions that may raise errors.

Toolchain Updates​

  • Tests can now be written in the main package. moon test will run tests in the main package, while moon run will execute the main function.
  • The IDE's codelens now supports running tests in documentation.
  • moon test and moon check now include tests in documentation by default.

MoonBit Beta Launch on June 18 — Developer Updates Transition to Monthly Reports​

After extensive refinement and continuous improvement based on community feedback, the MoonBit Beta version will be officially released on June 18, marking the transition to a more stable stage of the language.

Starting from this milestone, the MoonBit biweekly report will shift to a monthly cadence. Please stay tuned to this column for future updates.

We also welcome community feedback and discussion — feel free to share your thoughts and suggestions with us!

2025-06-03

· 4 min read

Language Updates​

1. Omission of ! for Effectful Calls​

Calling effectful functions (those that may throw errors or are asynchronous) no longer requires explicitly appending !. The IDE will automatically underline functions that may throw and render asynchronous functions in italics using semantic highlighting.

2. f?(..) Replaced by try? f(..) Expression​

try? expr is equivalent to try Ok(expr) catch { err => Err(err) }, allowing errors to be converted into the Result type. Compared to the original f?(..), try? is more flexible and can handle multiple function calls with potential errors at once, for example:

try? {
  f(..)
  g(..)
}

When migrating, special attention should be paid to the following case: f?(g!(..)) cannot be simply rewritten as try? f(g(..)), because this would redirect the error from g into the Result. In this case, the result of g should first be extracted with let, and then passed into try?.

3. Add Support for Error Polymorphism in Higher-Order Functions​

fn[X] Array::each(arr: Array[X], f: (X) -> Unit?Error) -> Unit?Error {
  for x in arr {
    f(x)
  }
}

fn main {
  let arr = ["a", "b", "c"]
  arr.each(println) // no error
  println(try? arr.each(fail)) // outputs Err(Failure)
}

The syntax for error polymorphism is (..) -> T?Error. At the call site, ?Error can be replaced with an actual error type, or it can be elided to represent a case where no error may occur.

Specifically, in the example above,

  • If the argument f does not throw, ?Error will be replaced with "no error", and the entire each call will not throw either.
  • If f throws an error, then ?Error will be replaced with the actual error type of f, and the entire each call will throw the same type of error.

4. Deprecation of fn meth(self: T) as Both Method and Function​

Previously, methods defined in the form fn meth(self: T) acted as both methods and regular functions, and could be invoked using either meth(..) or @pkg.meth(..). This behavior treating methods as regular functionsis now deprecated. The compiler will issue a warning when such usage is detected.

As a result of this change, the recommended API design is:

  • Always define methods using the form fn T::meth(..). Avoid using fn meth(self: T) in new code. (This syntax itself may be removed in the future.)

    • Any API that is associated with a specific type should be defined as a method, unless there is a compelling reason not to.

5. The dot syntax now supports anonymous functions using _, written as _.meth(..).​

At the same time, the right-hand side of the pipe operator |> also supports this form of anonymous method calls.

When using this syntax, it's important to ensure that the type of _ can be determined from the context; otherwise, the method cannot be resolved.

Example:

fn main {
  let array_of_array = [ [], [ 1 ], [ 1, 2 ] ]
  let lens = array_of_array.map(_.length())
  lens |> _.each(println)
}

Compared with writing x.meth(..) directly, the advantage of x |> _.meth(..) is that it allows method calls to be embedded into an existing pipeline. For example: x |> regular_func(..) |> _.meth(..).

6. In method declarations using the fn TypeName::meth(..)​

you can use Self to refer to TypeName, which helps shorten the type signature.

type MyLongTypeName Int

fn MyLongTypeName::to_string(x : Self) -> String {
  x._.to_string()
}

If TypeName has parameters, using Self will also require those parameters to be provided.

7. The behavior of implementing trait via method definitions has been officially removed.​

8. The position of type parameters in function declarations has been changed from fn f[..] to fn[..] f, making it consistent with impl.​

This change can be automatically migrated using the formatting tool.

9. The format of methods in .mbti files generated by moon info has changed.​

Previously, all methods were merged into a single large impl block. Now, each method is listed individually in .mbti, consistent with MoonBit's own syntax.

10. The syntax for asynchronous functions has been adjusted back to async(..) -> T, and !Async syntax (used for error handling and async) has been removed due to incompatibility.​

This change can also be automatically migrated using the formatting tool.

11. The literal suffix for Float types now supports .314f.​

Standard Library Updates​

  • The Show::output implementation for Char has changed. Now, all non-printable characters will be escaped, including: Control, Format, Surrogate, Private Use, Unassigned, and Separator (except space).

Toolchain Updates​

  • A single .mbt.md file now supports external dependencies.

Usage example:

---
moonbit:
  deps:
    moonbitlang/x: 0.4.23
    # moonbitlang/x:
    #   path: "/Users/flash/projects/x"  # local deps
  backend:
    js
---

2025-05-19

· 2 min read

Language Updates​

The syntax of x..f(..) will be updated. In the case of .. chaining, the last return value will automatically be discarded if it’s not used. For example, the following code:​

impl[X : Show, Y : Show] Show for (X, Y) with output(self, logger) {
  logger
  ..write_string("(")
  ..write_object(self.0)
  ..write_string(", ")
  ..write_object(self.1)
  // Previously, omitting the final `..` could result in a type mismatch,
  // expecting `&Logger` but returning `unit`
  .write_string(")")
}

Can now be simplified as:

impl[X : Show, Y : Show] Show for (X, Y) with output(self, logger) {
  logger
  ..write_string("(")
  ..write_object(self.0)
  ..write_string(", ")
  ..write_object(self.1)
  // You can now write the full chain all the way to the end
  ..write_string(")")

However, if you're directly using the return value of x..f(..), this behavior will be removed. You must now explicitly save the value. For example:

let arr = []..push(1)..push(2)

Must now be rewritten as:

let arr = []
arr..push(1)..push(2)

Structs and enums now support field-level documentation comments, which will be displayed accordingly during doc generation:​

///| Location enum
struct Location {
  /// X coordinate
  x : Int
  /// y coordinate
  y : Int
}

///| Variant enum
enum Variant {
  /// Stirng constructor
  String(String)
  /// Number constructor
  Number(Double)
}

@bytes.View and @string.View will now be compiled as value types in the C and wasm1 backends.​

This means that these two types will no longer involve heap allocation, leading to significantly improved memory layout and performance.

Toolchain Updates​

  • vscode now supports semantic token highlighting, which distinguishes between effectful functions (such as those that throw exceptions) and normal ones, as well as async functions. This gives each usage a different visual style.

  • The build system now supports the virtual package feature. By defining a package as virtual, you can specify a set of interfaces and allow users to choose actual implementations. If no implementation is provided, the system uses a default. This helps achieve clean decoupling and flexible substitution. Note: This feature is still under development. For more details, please refer to: Introducing virtual package in MoonBit

  • Now supports running test and debugging codelen directly on individual .mbt and .mbt.md files.

2025-05-06

· 2 min read

Language Updates​

  • [Breaking Change] The way traits are implemented will change. In the future, traits must be explicitly implemented for a type A using impl T for A { ... }. Simply defining methods on A with the same signature as those in trait T will no longer be considered as implementing the trait T for A. This change was previously accompanied by a compiler warning and will soon take effect officially.

  • A new syntactic sugar has been introduced to allow the use of _ as a placeholder for omitted parameters when creating anonymous functions, simplifying their syntax. For example, f(a, _, c, _) is equivalent to fn(b, d) { f(a, b, c, d) }. Supported usage scenarios include:

    • Constructor(args, _), lhs |> Constructor(args, _)
    • function(args, _), lhs |> function(args, _)
    • object.method(args, _) (Note: _.method(args) is not supported yet)

  • fnalias now supports creating aliases for types and trait methods:

    trait Floating {
  sin(Self) -> Self
  cos(Self) -> Self
}

// You can now use `sin` and `cos` directly without qualifying with `Floating::`
pub fnalias Floating::(sin, cos)

  • All pragmas have been removed and will be completely replaced by attributes going forward.

  • The #internal attribute has been implemented to provide warnings for external users of a public API:

    /// in moonbitlang/core
#internal(unsafe, "message")
pub fn unsafe_get(args){...}

/// in user/module
fn main {
  unsafe_get(...) // warning!
}

    Users can disable these warnings by setting the alert option in moon.pkg.json.

  • A new warning has been added for potentially ambiguous use of loop arguments inside a loop block:

    fn main {
  let a = "asdf"
  loop a {
    [k, .. b] => continue a // warning
    [k, .. b] as a => continue a // suggested
    [] => ()
  }
}

  • Implicit type conversions are now supported from Array to ArrayView, and from Bytes to @bytes.View.

Toolchain Updates​

  • The moon CLI now supports the bench subcommand for running performance benchmarks.

    Use a test block with a b : @bench.T parameter to define a benchmark. You can use b.keep() to prevent the compiler from optimizing away side-effect-free computations:

    fn fib(n : Int) -> Int {
  if n < 2 {
    return n
  }
  return fib(n - 1) + fib(n - 2)
}

test (b : @bench.T) {
  b.bench(fn() { b.keep(fib(20)) })
}

    Run benchmarks using:

    $ moon bench
[..]
time (mean ± σ)         range (min … max)
  21.67 µs ±   0.54 µs    21.28 µs …  23.14 µs  in 10 ×   4619 runs

    For more detailed usage instructions, refer to https://docs.moonbitlang.com/en/latest/language/benchmarks.html.

2025-04-21

· 4 min read

Language Updates​

  • Async function syntax: The call syntax for async functions has changed to match the error style: f!(...). The old f!!(...) syntax will now trigger a warning.

  • Operator overloading migration to traits: Operator overloading is moving from method-based to trait-based. Going forward, to overload an operator, you must impl the corresponding trait from @moonbitlang/core/builtin. You can find the list of operator-related traits in the language docs and operators.mbt.

    Migration details:

    • Old method-based operator overloading still works, but will raise a compiler warning.

    • Migrate by replacing op_xxx methods with the appropriate impl of the trait.

      • Operator traits enforce stricter type signatures—for example, the - operator requires the return type to be the same as the input type. If an operator doesn’t match the expected signature, it must be rewritten as a regular method instead of using operator syntax.

    • If a trait defines op_xxx methods, they can be removed and replaced by adding the operator trait to the super trait list. For example:

      // Old version
trait Number {
  from_int(Int) -> Self
  op_add(Self, Self) -> Self
  op_sub(Self, Self) -> Self
}

// Migrated version
trait Number : Add + Sub {
  from_int(Int) -> Self
}

  • New = _ syntax for traits: You can now mark whether a method in a trait has a default implementation using = _:

    trait Hash {
  hash_combine(Self, Hasher) -> Unit
  hash(Self) -> Int = _ // indicates that `hash` has a default implementation
}

    a. If a method is marked with = _, a matching default impl Trait with some_method(..) must exist. If a method has a default impl but is not marked with = _, the compiler will warn you.

    b. This is mainly for readability: now you can see from the trait definition which methods have defaults. Why not include the default code directly in the trait? To keep the trait definition short and focused on method signatures.

  • Implicit conversion from String to @string.View is now supported. Also, slicing with [:] now returns a full view again. General slicing like [i:j] is still under design.

    fn f(v : @string.View) -> Unit {
  ignore(v)
}

fn main {
  f("hello")
  f("world"[:])
}

  • Pattern matching on @string.View/@bytes.View now supports directly matching against string/byte literals:

    test {
  let s = "String"
  inspect!(s.view(end_offset=3) is "Str", content="true")
  let s : Bytes = "String"
  inspect!(s[:3] is "Str", content="true")
}

  • [Breaking Change] Updates to the @string core package:

    • Many APIs now use @string.View instead of String for parameters.
    • Some return types also changed from String to View.

    Notable changes:

    Old SignatureNew Signature
    self.replace(old~: String, new~: String) -> Stringself.replace(old~: View, new~: View) -> String
    self.trim(charset: String) -> Stringself.trim(charset: View) -> View
    self.split(substr: String) -> Iter[String]self.split(substr: View) -> Iter[View]
    self.index_of(substr: String, from~: Int) -> Intself.find(substr: View) -> Option[Int]
    self.last_index_of(substr: String, from~: Int) -> Intself.rev_find(substr: View) -> Option[Int]
    self.starts_with(substr: String) -> Boolself.has_prefix(substr: View) -> Bool
    self.ends_with(substr: String) -> Boolself.has_suffix(substr: View) -> Bool

  • Core Json type will become read-only: In the future, enum constructors for Json will no longer be available. Instead, helper functions are provided as replacements:

    test {
  let num = Json::number(3.14)
  let str = Json::string("Hello")
  let obj = Json::object({ "hello": num, "world": str })
}

Toolchain Updates​

  • IDE drops support for moonbit: true front matter in Markdown:

    • Now, only files with the .mbt.md extension will be treated as MoonBit Markdown files in the IDE.

  • IDE supports setting debug breakpoints in .mbt.md directly:

    • You no longer need to enable Debug: Allow Breakpoint Everywhere in VSCode settings.

  • New scripts field in moon.mod.json for build scripts:

    • Currently supports a postadd script: if a module contains a postadd field, it will be automatically executed after moon add.
      • To skip execution, set the MOON_IGNORE_POSTADD environment variable.

    Example:

    {
  "scripts": {
    "postadd": "python3 build.py"
  }
}

  • Improvements to .mbt.md Markdown support in the moon CLI:

    • moon check now includes Markdown checking automatically.
    • moon test now includes Markdown tests by default. (The --md flag will be removed in the future.)

2025-04-07

· 2 min read

Language Updates​

Wasm Backend: extern type T Now Storable in Arrays and Data Structures​

The wasm backend now supports storing values of extern type T in arrays and other data structures. At FFI boundaries (import/export function signatures), extern type T is still compiled to WebAssembly's externref type.

C FFI Supports borrow​

C FFI now supports the borrow attribute. You can use #borrow(args, ...) above an extern "c" function to customize how MoonBit manages the lifetime of certain arguments, where args is a subset of the C FFI function’s parameter names.

By default, MoonBit assumes C FFI functions are responsible for releasing the passed arguments. This often requires writing helper functions to manually release values.

fn open(path: Bytes, flags: Int, mode: Int) -> Int = "open"
int open_wrapper(moonbit_bytes_t path, int flags, int mode) {
  int rc = open(path, flags, mode);
  moonbit_decref(path);
  return rc;
}

With the borrow attribute, you can instruct MoonBit not to generate reference counting instructions for the specified arguments, allowing direct binding to C library functions without the need for extra helper functions.

#borrow(path)
fn open(path: Bytes, flags: Int, mode: Int) -> Int = "open"

Thanks to #borrow, MoonBit will automatically release path after calling open.

type & trait Support the #deprecated Attribute​

type and trait now support the #deprecated attribute. In the next release, the old pragma-based mechanism will be removed. It's recommended to use the attribute instead:

/// the @alert pragma is deprecated
/// @alert deprecated "message"
fn f() -> Unit { ... }

/// use the #deprecated attribute instead
#deprecated("message")
fn f() -> Unit { ... }

Backend Consistency Checks for Declarations of FFI extern Functions​

Backend consistency checks have been added to declarations of FFI extern functions. For example, the following function will raise an error when building with non-Native backends:

extern "c" fn open(path: Bytes, flags: Int, mode: Int) -> Int = "open"

Toolchain Updates​

  1. Starting this week, toolchain releases will move from Monday to Thursday.

  2. Fixed a bug in the test explorer and added support for testing and debugging .mbt.md files:

md.png

You can enable the following setting to allow setting breakpoints inside Markdown files: Settings > Debug: Allow Breakpoint Everywhere

setting.png

  1. moon info --package now supports fuzzy matching for package names.