Moxie Formatting and Style Specification

This document specifies the canonical formatting for .mx source files. The moxiefmt tool enforces these rules mechanically.

1. The 80-Column Single-Line Rule

If the content within a { } block fits under 80 characters wide with ; separating statements, the single-line form is canonical.

This rule applies universally to all brace-delimited constructs:

• if, for, select, switch
• struct, interface
• [] (slice/array literals), map[] (map literals)
• func bodies

Single-line:

if err != nil { return err } struct{ x int32; y int32 } for i := int32(0); i < n; i++ { sum += i } func name() { return 1 }

Multi-line (exceeds 80 chars, or author preference for clarity):

struct{ name string addr string port int32 }

2. Indentation

Tabs, not spaces. One tab per nesting level. Tab width = 4 spaces. No mixed indentation.

3. Multi-Line Break Rules

When a block exceeds the 80-column threshold:

• Opening { stays on the same line as the preamble
• Each statement gets its own line, indented one level
• Closing } on its own line, aligned with the preamble

4. Semicolons

Explicit semicolons separate statements on a single line. In multi-line form, newlines replace semicolons - no trailing semicolons at line ends.

5. Spacing

• No space before { when it attaches to a type keyword or type name:

struct{, interface{, TypeName{, map[K]V{, []T{

• Space before { in control flow where { follows an expression:

if err != nil {, for i < n {

• Space before { when it follows ):

func name() {, if f() {

• Single space after ; in single-line blocks
• Single space around binary operators
• No space between function name and (
• No space inside () or []

Note (language constraint, not purely formatting): all return values must be named. Return signatures take the form (name type, name type) with no spaces between the parens and the list. This applies universally: top-level functions, methods, and method fields within struct/interface definitions.

6. Blank Lines

• One blank line between top-level declarations
• No blank line after opening { or before closing }
• Optional single blank line within a function body to separate logical sections

7. Imports, Requires, Replace

Always multi-line with () wrapping, one statement per line. The single-line form is not valid.

import( "fmt" "os" )

requires( example.com/pkg v1.2.3 )

replace( example.com/pkg => ../local/pkg )

8. Vertical Alignment

Contiguous items within struct{, interface{, and function bodies are vertically aligned by column. A double blank line (two consecutive newlines with no content) breaks an alignment group - items after the break start a new independent alignment.

struct{ name string address string port int32

x int32 y int32 }

Trailing // comments after statements are also vertically aligned within a contiguous block. A single blank line continues the block; a double blank line resets alignment.

x := compute() // first pass y := transform(x) // second pass z := finalize(y) // done

a := other() // new alignment group b := more() // independent of above

9. Line Width

80 columns is the hard threshold for the single-line rule. Lines in multi-line form should also target 80 columns but this is not enforced mechanically - the formatter only uses 80 as the single-line/multi-line decision boundary.

10. Return Value Normalization

The formatter automatically wraps return values in () with named parameters. Even a single return value is wrapped: func f() (err error) not func f() error. This is a language constraint that moxiefmt enforces mechanically.