ex_numerlo

# Usage Rules for ExNumerlo

These rules provide guidance for LLM agents and developers when using the `ExNumerlo` library.

## Core Principles

- **Unified Entry Point:** Always use `ExNumerlo.convert/2` for encoding, decoding, and cross-system operations.
- **Strict Error Tuples:** Every public function returns `{:ok, result}` or `{:error, reason}`. There are no throwing variants.
- **Intelligent Auto-Detection:** Use `from: :auto` (default) when the source system is unknown. To decode any supported numeral string to an Elixir integer, use `ExNumerlo.convert(encoded, to: :integer)`.

## System Specifics and Constraints

### Historical Systems
- **Positive Integers Only (> 0):** `:roman`, `:attic`, `:aegean`, `:ethiopic`.
- **Non-Negative Integers (>= 0):** `:mayan`, `:cuneiform`.
- **Roman Range:** `:roman` is strictly limited to the range `1..3999`.

### Specialized Systems
- **Duodecimal:** Use `:duodecimal` for base-12. Auto-detection requires at least one unique digit (↊ or ↋) to distinguish it from Arabic.
- **Mathematical Alphanumeric:** Five positional styles are supported for 0-9: `:math_bold`, `:math_double_struck`, `:math_monospace`, `:math_sans`, and `:math_sans_bold`.

### Formatting Features
- **Separators:** The `:separator` option (e.g., `,`, `.`, ` `) is supported only for positional systems (Arabic variants, Math styles, Fullwidth, and Duodecimal). It is ignored by additive/hybrid systems.
- **Sign Handling:** Positional systems support both `+` and `-` prefixes during decoding.

## Implementation Patterns

### Standard Conversion
```elixir
# Auto-detect and encode to Roman
{:ok, "CXXIII"} = ExNumerlo.convert("१२३", to: :roman)

# Decode to integer
{:ok, 123} = ExNumerlo.convert("MMXXVI", to: :integer)
```

### Separator Usage
```elixir
# Positional systems handle separators robustly
{:ok, "1,234,567"} = ExNumerlo.convert(1234567, to: :arabic, separator: ",")
```

### Error Handling
```elixir
# Range errors return explicit reasons
{:error, :out_of_range} = ExNumerlo.convert(4000, to: :roman)
{:error, :not_positive} = ExNumerlo.convert(0, :ethiopic)
```

## Naming Conventions
- **System Atoms:** Always use lowercase atoms (e.g., `:thai`, `:mayan`).
- **Targeting:** Use `to: :integer` for decoding to raw Elixir integers.