Extended Piece Identifier Notation (EPIN) Specification

Version: 1.0.0
Author: Cyril Kato
Published: January 25, 2025
License: Open Web Foundation Agreement 1.0

1. Status of this document

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirements.

Capitalized terms (Piece, Piece Identity, Piece Name, Piece Side, Piece State, Piece Style, Terminal Piece, etc.) are defined in the Glossary and are not redefined here.

2. Overview

Extended Piece Identifier Notation (EPIN) is a compact, ASCII-only identifier for Pieces in abstract strategy games.

EPIN is a strict superset of PIN: it inherits all PIN attributes (Piece Name, Piece Side, Piece State, Terminal Status) and adds a single optional suffix:

the derivation marker: an apostrophe (')

EPIN tokens are intended to be:

easy to parse,
stable under Mutation of core attributes,
and flexible across Rule Systems.

Crucially: EPIN does not encode a Piece Style. Instead, EPIN only encodes whether the Piece is considered native or derived with respect to Style, via the presence of the derivation marker. The meaning of “native/derived”, and how a concrete Style is obtained, is context-defined.

3. Dependencies

EPIN depends on:

PIN v1.0.0 — for the core token structure and attribute mapping

Every valid PIN token is also a valid EPIN token (with native Style status).

4. Format

An EPIN token has the following structure:

<pin> [ derivation-marker ]

Where:

<pin> is a valid PIN token
derivation-marker is optional and is '

The derivation marker, when present, MUST appear last.

5. Grammar (EBNF)

epin              ::= pin [ derivation-marker ] ;
derivation-marker ::= "'" ;

For the pin production, see the PIN specification.

6. Regular Expression

An EPIN token MUST match the following regular expression, anchored to the whole string:

\A[-+]?[A-Za-z]\^?'?\z

Anchoring requirement (normative):

Implementations MUST ensure the anchors apply to the entire input string, not to individual lines.
Implementations MUST reject any input containing line breaks (\r or \n).

7. Attribute mapping

7.1 Core attributes (inherited from PIN)

EPIN inherits the four core attributes defined by PIN:

Attribute	Encoding
Piece Name	`piece-letter` (case-insensitive identity)
Piece Side	`piece-letter` case (uppercase = `first`, lowercase = `second`)
Piece State	`state-modifier` (`+` enhanced, `-` diminished, absent normal)
Terminal Status	`terminal-marker` (`^` terminal, absent non-terminal)

7.2 Derivation flag (EPIN extension)

EPIN adds a single boolean flag, encoded by the optional derivation marker ('):

If the derivation marker is absent, the EPIN token denotes a Piece whose Style is Native.
If the derivation marker is present, the EPIN token denotes a Piece whose Style is Derived.

This specification defines only the flag and its encoding.

7.3 Style resolution (non-normative)

EPIN does not define how to obtain a concrete Piece Style from an EPIN token.

A context MAY resolve Styles using any mechanism, for example:

a Rule System-defined default Style for the Game,
a Player-defined Style selection,
a catalog lookup table,
a transformation pipeline,
any other external mechanism.

The only requirement EPIN imposes is that producers and consumers agree on what “Native” and “Derived” mean in that context.

8. Mutations and EPIN transformations (informative)

Because EPIN isolates each concept in a specific syntactic location, common Mutations are straightforward:

Piece Side change → flip the case of piece-letter
Piece State change → add/change/remove state-modifier
Terminal Status change → add/remove ^
Style status change (native ↔ derived) → add/remove '

EPIN does not prescribe when such changes occur; they are Rule System-defined.

9. Parsing and conformance requirements

9.1 Validity

A string is a valid EPIN token if and only if it matches §6 (or §5).

Implementations:

MUST reject invalid tokens,
SHOULD provide a non-raising validity predicate (e.g. valid?),
MAY provide a raising/bang parser variant.

9.2 Canonical form

EPIN tokens are canonical by construction. Implementations MUST NOT rewrite tokens by applying context assumptions.

In particular:

An EPIN parser MUST NOT add or remove ' by guessing whether the Piece is native or derived.
If a context chooses to canonicalize (e.g., normalize representations), it MUST do so as a separate, explicit, context-level step.

9.3 Component extraction

Implementations SHOULD provide accessors for each component:

Accessor	Description
`pin`	A valid PIN token
`native?`	Boolean indicating Native Style status
`derived?`	Boolean indicating Derived Style status

Implementations SHOULD also provide transformation methods:

Method	Description
`native`	Returns a copy with Native Style status (derivation marker absent)
`derive`	Returns a copy with Derived Style status (derivation marker present)

These methods are idempotent: applying native to a Native token or derive to a Derived token returns an equivalent copy.

9.4 Invalid token examples

String	Reason
`""`	empty
`K''`	multiple derivation markers
`^K`	wrong order
`K'^`	derivation marker must be last
`++K`	multiple state modifiers
`K^^`	multiple terminal markers
`1`	not a letter
`K`	whitespace
`K\n`	contains a line break

10. Examples

See EPIN Examples for practical modeling patterns and context-driven interpretations.

11. Reference Implementations

The following reference libraries are maintained by Sashité and are intended to be idiomatic, fully tested, and spec-accurate implementations of EPIN v1.0.0.

They generally provide:

strict parsing and validation (valid?, parse, and a raising/bang variant),
round-trip serialization (string ⇄ structured identifier),
component extraction (pin, native?, derived?),
transformation methods (native, derive),
clear error reporting for invalid inputs.

If a library behavior appears to conflict with this document, this specification is normative. Please report issues (or propose clarifications) on the relevant repository.

Elixir — epin.ex
Ruby — epin.rb

12. License

This specification is made available under the terms of the Open Web Foundation Agreement 1.0 (OWFa 1.0).

The authoritative legal text is the OWF “Final Specification Agreement (OWFa 1.0)”.