Documentation

Everything you need to know about Mad Sam Notation.

Getting Started

Install the MSN CLI globally:

npm install -g @madsn/cli

Or add the parser to your project:

npm install @madsn/parser

Compile an MSN file to JSON:

msn compile config.msn
msn compile config.msn -o config.json

Basic Syntax

MSN uses dashes to indicate hierarchy depth. One dash - means top level, two dashes -- for the next level, and so on.

Key-value pairs:

- name: my-app
- version: 1.0.0
- private: true

Compiles to:

{
  "name": "my-app",
  "version": "1.0.0",
  "private": true
}

Nesting

Increase the number of dashes to nest objects:

- server
-- host: localhost
-- port: 3000
-- ssl
--- enabled: true
--- key: /path/to/key.pem

Compiles to:

{
  "server": {
    "host": "localhost",
    "port": 3000,
    "ssl": {
      "enabled": true,
      "key": "/path/to/key.pem"
    }
  }
}

There is no limit to nesting depth. Just keep adding dashes.

Arrays

Use an asterisk * to create array items:

- colors
-- * red
-- * green
-- * blue

Compiles to:

{
  "colors": ["red", "green", "blue"]
}

Array objects — items in arrays that have properties:

- users
-- *
--- name: Alice
--- role: admin
-- *
--- name: Bob
--- role: user

Compiles to:

{
  "users": [
    { "name": "Alice", "role": "admin" },
    { "name": "Bob", "role": "user" }
  ]
}

Multiline Values

Use | for literal multiline (preserves newlines) and > for folded multiline (joins with spaces):

Literal block (|):

- description: |
  This is line one.
  This is line two.
  This is line three.

Produces: "This is line one.\nThis is line two.\nThis is line three."

Folded block (>):

- description: >
  This is a long paragraph
  that will be joined into
  a single line with spaces.

Produces: "This is a long paragraph that will be joined into a single line with spaces."

Comments

Lines starting with # are comments and are ignored during compilation:

# Application configuration
- app
-- name: my-app    # inline comments are also supported
-- debug: false

Type Inference

MSN automatically infers types from values:

| Value | Type | JSON Output |

|-------|------|-------------|

| `42` | number | `42` |

| `3.14` | number | `3.14` |

| `true` / `false` | boolean | `true` / `false` |

| `null` | null | `null` |

| `"hello"` | quoted string | `"hello"` |

| `hello` | unquoted string | `"hello"` |

Wrap a numeric value in quotes to force it to be a string: "3000".

CLI Reference

Commands:

| Command | Description |

|---------|-------------|

| `msn compile <file>` | Compile MSN to JSON |

| `msn parse <file>` | Output the AST |

| `msn validate <file>` | Check for syntax errors |

| `msn format <file>` | Auto-format an MSN file |

Flags:

| Flag | Description |

|------|-------------|

| `-o, --output <file>` | Write output to a file |

| `-i, --indent <n>` | JSON indentation (default: 2) |

| `--stdin` | Read from stdin |

| `-h, --help` | Show help |

| `-v, --version` | Show version |

API Reference

Quick start:

import { compile, compileToString } from '@madsn/parser';

// Get a JavaScript object
const obj = compile(`
- name: my-app
- port: 3000
`);

// Get formatted JSON string
const json = compileToString(`
- name: my-app
- port: 3000
`, 2);

Classes:

- Lexer — Tokenizes MSN source into a token stream

- Parser — Builds an AST from tokens

- Compiler — Converts AST to JSON

Validator:

import { validate } from '@madsn/validator';
const errors = validate(source);

Formatter:

import { format } from '@madsn/formatter';
const formatted = format(source);