Ferrichess Study
ferrichess-study converts compact chess study text into legal,
position-aware move trees and deterministic PGN. It is a library only: it does
not access the network or filesystem, and it does not include study content.
Normal conversion path
Use [convert_single_raw] to build one PgnDocument, then render it with
[PgnWriter]. The input is interpreted from the standard initial chess
position.
use ;
let metadata = SingleRawMetadata ;
let document = convert_single_raw?;
let pgn = render?;
assert!;
# Ok::
PgnWriter::render returns one PGN game without a trailing newline.
PgnWriter::render_file returns the standalone-file form, ending in two
newlines. PgnWriter::render_documents joins multiple documents using that
same separator.
Compact study-text format
The format is line-oriented and deliberately less strict than PGN. A line that starts with a move number is a candidate mainline line; other nonblank lines are prose comments attached at the current position.
Move numbers may use N. for White or N... for Black, with optional space
after the dots. They may be adjacent to SAN moves and to each other, so all of
these are equivalent where legal:
1. e4 e5 2. Nf3 Nc6
1.e4e52.Nf3Nc6
1. e4e5 2.Nf3Nc6
Moves use legal SAN for the current position. The parser accepts O-O and
0-0 spellings for castling, optional check or mate suffixes, and these move
annotations: !, ?, !!, ??, !?, ?!, =, ∞/~, =∞/=~,
⩲/+=, ⩱/=+, ±/+/-, ∓/-/+, +–/+-, –+/-+, and
⇆/<=>. The writer retains move-quality annotations in SAN and renders
position evaluations as PGN NAGs.
The parser does not guess. A numbered line whose number backtracks, contains
no legal move, or leaves unparsed text becomes a normalized comment instead of
partially extending the mainline. Result tokens (1-0, 0-1, 1/2-1/2, and
*) end parsing of that line; output always uses the * result. -- after a
move number is an instructional placeholder and is retained as a comment.
The compact format does not accept FEN setup, PGN header tags, PGN brace or
semicolon comment syntax, explicit recursive-annotation variations, or an
arbitrary starting position. For a variation found in prose, use
RawTreeBuilder::with_comment_variations(true) and provide a compatible,
explicitly numbered move sequence; this is an advanced tree-building option,
not part of the normal conversion path.
An exact-ply comment directive can attach machine-readable PGN annotations or prose without interrupting the mainline move text:
1. e4 e5 2. Nf3 Nc6
@@PlyComment@@1@@[%cal Ge2e4]
@@PlyComment@@2@@[%csl Re4]
Ply zero is the initial position, ply one is the position after White's first
move, and so on. Directives may appear anywhere in the input and must target an
existing mainline ply. They are especially useful for PGN graphical annotation
commands such as [%cal ...] (arrows) and [%csl ...] (colored squares).
Conversion model and API boundary
convert_single_raw is the stable, convenient boundary for a single study:
it parses the text, validates each SAN move against the current position,
constructs a move tree, and supplies deterministic PGN headers from
SingleRawMetadata. It returns PgnError if tree construction or rendering
validation fails.
For control over parsing and tree inspection, use RawTreeBuilder directly;
its build result contains both the MoveTree and per-line classifications.
For assembling a repertoire from several raw lines, use the advanced
generate_course_documents boundary with CourseMetadata and
RawCourseLine. That boundary is pure as well: callers supply all metadata
and text, then choose how to persist rendered output.
The first public metadata contract is intentionally small:
SingleRawMetadatais the required metadata for normal single-study conversion.RepertoireSideandRepertoireRoledescribe how the study is oriented and labelled in its generated headers.CourseMetadata, its nested metadata types, andRawCourseLinesupport advanced multi-document assembly. They remain public in 0.x, but their JSON schema and assembly rules are not the minimal conversion API and may evolve in a minor release before 1.0.
Scope and pre-1.0 stability
The crate currently provides raw study-text parsing, typed annotations and comments, position-aware move-tree construction, course-document assembly, and deterministic PGN rendering.
The crate follows Semantic Versioning with pre-1.0 expectations: patch releases
fix defects without intentional API or output-contract changes; minor releases
may change public APIs, the compact syntax, metadata schema, or deterministic
rendering details. Consumers that need reproducible output should pin a
compatible 0.x.y version and keep regression fixtures for their input.
License
Licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later).