Sashite.Snn

SNN (Style Name Notation) implementation for Elixir.

What is SNN?

SNN (Style Name Notation) provides a human-readable naming system for game styles (Piece Styles) in abstract strategy board games. It uses PascalCase names with optional numeric suffixes to identify movement traditions or game variants.

This library implements the SNN Specification v1.0.0.

Installation

Add sashite_snn to your list of dependencies in mix.exs:

def deps do
  [
    {:sashite_snn, "~> 1.0"}
  ]
end

SNN Format

SNN tokens follow a strict structure: [PascalCaseName][OptionalSuffix]

Component	Rule	Examples
Start	Must start with an Uppercase letter (`A`-`Z`)	`C`, `S`, `X`
Body	Followed by optional letters (`A`-`Z`, `a`-`z`)	`Chess`, `Shogi`
Suffix	Ends with optional digits (`0`-`9`)	`Chess960`, `G5`

Usage

The API is designed to be idiomatic, leveraging pattern matching and protocols.

Parsing

The parse/1 function validates the format and returns a tagged tuple with a struct.

iex> Sashite.Snn.parse("Chess")
{:ok, %Sashite.Snn{name: "Chess"}}

iex> Sashite.Snn.parse("Chess960")
{:ok, %Sashite.Snn{name: "Chess960"}}

# Invalid inputs
iex> Sashite.Snn.parse("chess") # Lowercase start
{:error, :invalid_format}

iex> Sashite.Snn.parse("Chess_960") # Invalid char
{:error, :invalid_format}

Bang functions (Direct access)

Use parse!/1 when you expect the input to be valid (e.g., constants).

iex> snn = Sashite.Snn.parse!("Shogi")
%Sashite.Snn{name: "Shogi"}

Protocol Implementation

The struct implements String.Chars, allowing seamless interpolation.

iex> snn = Sashite.Snn.parse!("Xiangqi")
iex> "Playing #{snn}"
"Playing Xiangqi"

Validation Only

If you only need a boolean check without creating a struct:

iex> Sashite.Snn.valid?("Makruk")
true

iex> Sashite.Snn.valid?("")
false

Regular Expression

The library exposes the compiled regex used for validation, useful for embedding in other validation logic.

iex> Regex.match?(Sashite.Snn.regex(), "Go")
true

Regex pattern: ^[A-Z][a-zA-Z]*[0-9]*$

Use Cases

SNN is designed for identifying game styles in various contexts:

Game variant identification (Chess960, CapablancaChess)
Multi-variant game engines
Hybrid game configurations (e.g., "Player 1 uses Chess style, Player 2 uses Shogi style")

API Reference

Types

%Sashite.Snn{
  name: String.t() # The validated SNN string
}

Functions

valid?/1 - Checks if a string conforms to the SNN format.
parse/1 - Converts a string to an SNN struct (returns {:ok, snn} or {:error, reason}).
parse!/1 - Same as parse but raises ArgumentError on failure.
regex/0 - Returns the Regex used for validation.

Game Protocol – Conceptual foundation
SNN Specification – Official specification
SIN – Style Identifier Notation (compact single-character format)

License

Available as open source under the Apache License 2.0.

Next Page → LICENSE