# Getting Started with Notation

Notation validation and parsing are built into `@randsum/roller` — no separate package required. Install roller to get `isDiceNotation`, `validateNotation`, `notationToOptions`, `optionsToNotation`, and the full notation toolkit.

## Quick notation examples

Standard dice, special dice types, and modifiers all work with every notation function:

<CodeExample code={`isDiceNotation('4d6L')                // true — standard notation
isDiceNotation('z6')                  // true — zero-bias die (faces 0-5)
isDiceNotation('d{fire,ice,lightning}') // true — custom faces
isDiceNotation('4d6KM')               // true — keep middle dice, discard highest and lowest
isDiceNotation('4d20ro{<5}')          // true — reroll once any die showing less than 5
isDiceNotation('1d20ms{15}')          // true — margin of success: result minus target (15)
isDiceNotation('6d6sd')               // true — sort descending`} />

## Check if a string is valid notation

Use `isDiceNotation()` as a type guard to check user input before processing it:

<CodeExample code={`isDiceNotation('4d6L')       // true
isDiceNotation('not-valid')  // false

if (isDiceNotation(userInput)) {
  // userInput is now typed as DiceNotation
}`} />

## Validate with detailed feedback

`validateNotation()` returns a result object with either the parsed structure or error details:

<CodeExample code={`const result = validateNotation('4d6L')

if (result.valid) {
  console.log(result.notation)  // ['4d6L']
  console.log(result.options)   // [{ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } }]
} else {
  console.log(result.error)     // { message: '...', argument: '...' }
}`} />

## Parse notation into options

Convert a notation string into structured `ParsedNotationOptions`. Returns an array (one entry per roll group):

<CodeExample code={`const notation = '2d6+3'

if (isDiceNotation(notation)) {
  const [options] = notationToOptions(notation)
  console.log(options.sides)       // 6
  console.log(options.quantity)    // 2
  console.log(options.modifiers)   // { plus: 3 }
}`} />

## Convert options back to notation

<CodeExample code={`const notation = optionsToNotation({
  sides: 6,
  quantity: 4,
  modifiers: { drop: { lowest: 1 } }
})
console.log(notation) // '4d6L'`} />

## What's next

- [Randsum Dice Notation Spec](https://randsum.dev/notation/randsum-dice-notation/) -- full syntax reference for all notation features
- [Validation & Parsing](https://randsum.dev/notation/validation-and-parsing/) -- detailed guide to validation, suggestions, and parsing
- [API Reference](https://randsum.dev/notation/api-reference/) -- complete list of exports from `@randsum/roller`