scid::core::pgn Namespace Reference

PGN import, export and movetext traversal helpers. More...

Classes
struct	EncodeOptions
	Options controlling which PGN content is emitted. More...
struct	ParseLog
	Aggregated parse progress and diagnostics. More...

Functions
bool	parseGame (const char *input, size_t inputLen, scid::core::Game &game, ParseLog &log)
	Parses PGN text into game.
bool	parseGame (const char *input, size_t inputLen, scid::core::Game &game, scid::core::MovetextLocation &location, ParseLog &log)
	Parses PGN text into game starting at location.
template<int desired_len = 80, char breakpoint_char = '\0', int hard_len = 0, typename Iter >
Iter	break_lines (Iter begin, Iter end)
	Replaces internal token separators with spaces or newlines.
template<typename Iter >
Iter	break_lines (Iter begin, Iter end, unsigned desired_len)
	Runtime-width overload of break_lines().
template<typename TCont >
void	escape_string (TCont &str, typename TCont::size_type pos)
	Escapes quotes and backslashes in a PGN string token.
template<bool unknown_to_question_mark = false, typename TCont >
void	encode_tag_pair (std::string_view tag, std::string_view value, TCont &dest)
	Appends one PGN tag pair to dest.
template<int hard_len = 0, typename TCont >
bool	encode_comment_rest_of_line (std::string_view comment, TCont &dest)
	Attempts to encode comment as a PGN semicolon comment.
template<int hard_len = 0, typename TCont >
void	encode_core_line (MoveSequence const &line, scid::core::Position position, std::vector< long long > &ply, typename TCont::size_type &move_end, TCont &dest, EncodeOptions options={})
	Encodes one move sequence and its child variations.
template<int hard_len = 0, typename TCont >
void	encode_movetext (Game const &game, TCont &dest, EncodeOptions options={})
	Encodes only a game's movetext section.
template<typename TCont >
void	encode_core_tag_pairs (Game const &game, TCont &dest, EncodeOptions options={})
	Encodes the seven tag roster plus selected supplemental tags.
template<int hard_len = 0, typename TCont >
void	encode_game (Game const &game, TCont &dest, EncodeOptions options={})
	Encodes a complete game without final line wrapping.
template<int desired_len = 80, typename TGame , typename TCont >
void	encode (TGame const &game, TCont &dest, EncodeOptions options={})
	Encodes a complete game as final PGN text.
bool	nextLocation (GameCursor &cursor)
	Advances a cursor to the next location in PGN traversal order.
bool	seekLocation (GameCursor &cursor, unsigned location)
	Moves a cursor to a one-based PGN traversal location.
unsigned	locationOf (const GameCursor &cursor)
	Returns the one-based PGN traversal location of a cursor.
unsigned	offsetOf (const GameCursor &cursor)
	Returns the PGN display offset for a cursor.

Detailed Description

PGN import, export and movetext traversal helpers.

PGN is the text import/export mapping around scid::core::Game. Decoding reads tags, comments, NAGs, SAN moves and Recursive Annotation Variations into the editable game model. Encoding walks the same model in the opposite direction, emitting tag pairs, movetext, comments, annotations, variations and the final result.

Parsing is stateful because SAN moves and RAVs are relative to a current position in the game tree. Encoding is position-aware for the same reason: when a move has no cached SAN text, the encoder replays from the current scid::core::Position and generates SAN before writing the move.

Function Documentation

break_lines()

template<int desired_len = 80, char breakpoint_char = '\0', int hard_len = 0, typename Iter >

Iter scid::core::pgn::break_lines	(	Iter	begin,
		Iter	end
	)

Replaces internal token separators with spaces or newlines.

The encoder uses NUL bytes as soft token breakpoints while constructing PGN. This helper turns those breakpoints into spaces, promoting the most recent breakpoint to a newline when the current line would exceed desired_len. Existing newlines are preserved, so comments and tag values are not split unless hard_len requests a secondary pass that may break on spaces.

Most callers should use encode(), which performs this step automatically.

Returns

an iterator to the first character of the final line.

encode()

template<int desired_len = 80, typename TGame , typename TCont >

void scid::core::pgn::encode	(	TGame const &	game,
		TCont &	dest,
		EncodeOptions	options = {}
	)

Encodes a complete game as final PGN text.

The generated game is appended to dest. Internal NUL token separators are converted to spaces or line breaks before the function returns.

std::string pgn;
scid::core::pgn::encode(game, pgn);

encode_comment_rest_of_line()

template<int hard_len = 0, typename TCont >

bool scid::core::pgn::encode_comment_rest_of_line	(	std::string_view	comment,
		TCont &	dest
	)

Attempts to encode comment as a PGN semicolon comment.

Semicolon comments run to the end of the line. Comments containing line breaks, NUL separators, or exceeding hard_len are rejected without modifying dest.

Returns

true when comment was appended.

encode_core_line()

template<int hard_len = 0, typename TCont >

void scid::core::pgn::encode_core_line	(	MoveSequence const &	line,
		scid::core::Position	position,
		std::vector< long long > &	ply,
		typename TCont::size_type &	move_end,
		TCont &	dest,
		EncodeOptions	options = {}
	)

Encodes one move sequence and its child variations.

This is a low-level building block for custom exporters. It expects callers to provide the current position and ply stack that correspond to line. Use encode_movetext() or encode() unless those details are already part of your export pipeline.

encode_core_tag_pairs()

template<typename TCont >

void scid::core::pgn::encode_core_tag_pairs	(	Game const &	game,
		TCont &	dest,
		EncodeOptions	options = {}
	)

Encodes the seven tag roster plus selected supplemental tags.

This writes tag-pair lines only. Use encode_game() when the movetext and result marker should be emitted as well.

encode_game()

template<int hard_len = 0, typename TCont >

void scid::core::pgn::encode_game	(	Game const &	game,
		TCont &	dest,
		EncodeOptions	options = {}
	)

Encodes a complete game without final line wrapping.

Token separators remain as NUL bytes. This is useful for callers that want to choose their own wrapping policy; use encode() for normal PGN text.

encode_movetext()

template<int hard_len = 0, typename TCont >

void scid::core::pgn::encode_movetext	(	Game const &	game,
		TCont &	dest,
		EncodeOptions	options = {}
	)

Encodes only a game's movetext section.

The destination receives a leading blank line before movetext, matching the separation between PGN tag pairs and movetext in a complete game. Token separators remain as NUL bytes until break_lines() or encode() is called.

encode_tag_pair()

template<bool unknown_to_question_mark = false, typename TCont >

void scid::core::pgn::encode_tag_pair	(	std::string_view	tag,
		std::string_view	value,
		TCont &	dest
	)

Appends one PGN tag pair to dest.

The tag/value separator is written as NUL so that break_lines() can later convert it to a space. Tag values are escaped according to PGN string-token rules.

Template Parameters

unknown_to_question_mark

when true, empty Event, Site, Round, White, and Black values are written as ?.

escape_string()

template<typename TCont >

void scid::core::pgn::escape_string	(	TCont &	str,
		typename TCont::size_type	pos
	)

Escapes quotes and backslashes in a PGN string token.

Only the substring beginning at pos is processed, which lets callers append a tag value and then escape just the newly appended content.

nextLocation()

bool scid::core::pgn::nextLocation

(

GameCursor &

cursor

)

Advances a cursor to the next location in PGN traversal order.

The traversal enters child variations before continuing along the parent line, matching PGN Recursive Annotation Variation order.

Returns

false when the cursor is already at the final traversable location.

offsetOf()

unsigned scid::core::pgn::offsetOf

(

const GameCursor &

cursor

)

Returns the PGN display offset for a cursor.

When the cursor is at the start of a variation, the offset is reported as the nearest parent location that has printable move text before the variation.

parseGame() [1/2]

bool scid::core::pgn::parseGame	(	const char *	input,
		size_t	inputLen,
		scid::core::Game &	game,
		ParseLog &	log
	)

Parses PGN text into game.

The game is not cleared before parsing. This lets callers append movetext to an existing game, but callers that want replacement semantics should clear or construct the Game themselves first. Parsing may succeed while still adding warnings to log.

Parameters

input	memory containing the PGN text.
inputLen	number of bytes available at input.
game	destination game.
log	cumulative parse diagnostics and progress counters.

Returns

true when the input was parsed without discarding a trailing portion after a fatal parse error.

parseGame() [2/2]

bool scid::core::pgn::parseGame	(	const char *	input,
		size_t	inputLen,
		scid::core::Game &	game,
		scid::core::MovetextLocation &	location,
		ParseLog &	log
	)

Parses PGN text into game starting at location.

This overload is used by editors that insert moves, comments, NAGs, and variations at the current cursor location. On success, location is updated to the parser's final movetext location.

Parameters

input	memory containing the PGN text.
inputLen	number of bytes available at input.
game	destination game.
location	movetext location where parsing starts and where the final parser location is stored.
log	cumulative parse diagnostics and progress counters.

Returns

true when the input was parsed without discarding a trailing portion after a fatal parse error.

seekLocation()

bool scid::core::pgn::seekLocation	(	GameCursor &	cursor,
		unsigned	location
	)

Moves a cursor to a one-based PGN traversal location.

Location one is the start of the mainline.

Returns

false when location is beyond the traversal range.