cgsn.ex

CGSN (Chess Game Status Notation) implementation for Elixir.

Overview

This library implements the CGSN Specification v1.0.0.

Installation

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

def deps do
  [
    {:sashite_cgsn, "~> 1.1"}
  ]
end

Usage

Parsing (String → Atom)

Convert a CGSN string into an atom.

# Standard parsing (returns {:ok, atom} or {:error, reason})
{:ok, :checkmate} = Sashite.Cgsn.parse("checkmate")
{:ok, :resignation} = Sashite.Cgsn.parse("resignation")

# Bang version (raises on error)
:checkmate = Sashite.Cgsn.parse!("checkmate")

# Invalid input
{:error, :invalid_status} = Sashite.Cgsn.parse("invalid")
{:error, :invalid_status} = Sashite.Cgsn.parse("")

Validation

# Boolean check
Sashite.Cgsn.valid?("checkmate")    # => true
Sashite.Cgsn.valid?("resignation")  # => true
Sashite.Cgsn.valid?("invalid")      # => false
Sashite.Cgsn.valid?("")             # => false
Sashite.Cgsn.valid?(nil)            # => false

Classification

# Position-inferable: can be determined from Position + Rule System
Sashite.Cgsn.inferable?(:checkmate)   # => true
Sashite.Cgsn.inferable?(:stalemate)   # => true
Sashite.Cgsn.inferable?(:repetition)  # => false

# Explicit-only: requires external context (history, clocks, declarations)
Sashite.Cgsn.explicit_only?(:resignation)  # => true
Sashite.Cgsn.explicit_only?(:timelimit)    # => true
Sashite.Cgsn.explicit_only?(:checkmate)    # => false

Accessing Statuses

# All statuses (unordered)
Sashite.Cgsn.statuses()
# => MapSet.new([:check, :stale, :checkmate, :stalemate, :nomove, :bareking,
#                :mareking, :insufficient, :resignation, :illegalmove, :timelimit,
#                :movelimit, :repetition, :agreement])

# Position-inferable statuses
Sashite.Cgsn.inferable_statuses()
# => MapSet.new([:check, :stale, :checkmate, :stalemate, :nomove, :bareking,
#                :mareking, :insufficient])

# Explicit-only statuses
Sashite.Cgsn.explicit_only_statuses()
# => MapSet.new([:resignation, :illegalmove, :timelimit, :movelimit, :repetition,
#                :agreement])

API Reference

Constants

Sashite.Cgsn.statuses()               # MapSet of all 14 status atoms
Sashite.Cgsn.inferable_statuses()     # MapSet of 8 position-inferable atoms
Sashite.Cgsn.explicit_only_statuses() # MapSet of 6 explicit-only atoms

Parsing

# Parses a CGSN string into an atom.
# Returns {:ok, atom} or {:error, :invalid_status}.
@spec parse(String.t()) :: {:ok, atom()} | {:error, :invalid_status}

# Parses a CGSN string into an atom.
# Raises ArgumentError if the string is not valid.
@spec parse!(String.t()) :: atom()

Validation

# Reports whether string is a valid CGSN status identifier.
@spec valid?(term()) :: boolean()

Classification

# Reports whether status is position-inferable.
@spec inferable?(atom()) :: boolean()

# Reports whether status is explicit-only.
@spec explicit_only?(atom()) :: boolean()

Errors

Design Principles

• Atom-based: Statuses represented as Elixir atoms for identity semantics
• MapSet-based: Unordered collections reflect vocabulary nature
• Elixir idioms: {:ok, _} / {:error, _} tuples, parse! bang variant
• Strict validation: Only standard v1.0.0 vocabulary accepted
• Rule-agnostic: Records conditions without defining outcomes
• No dependencies: Pure Elixir standard library only

Related Specifications

• Game Protocol — Conceptual foundation
• CGSN Specification — Official specification
• CGSN Examples — Usage examples

License

Available as open source under the Apache License 2.0.