PGN Serialisation & Formatting

Portable Game Notation (PGN) text generation, formatting flags, and export configuration.

Types

	Name
typedef struct scid_game_pgn_options	scid_game_pgn_options Opaque configuration handle for customizing PGN text generation.

Functions

	Name
scid_error	scid_game_to_pgn(const scid_game * game, const scid_game_pgn_options * options, char * out_text, size_t out_text_capacity, size_t * out_text_size) Encodes a game into Portable Game Notation (PGN) text.
scid_error	scid_game_pgn_options_variations_set(scid_game_pgn_options * options, int enabled) Configures whether sub-variations are recursively included in the exported movetext.
scid_error	scid_game_pgn_options_symbolic_nags_set(scid_game_pgn_options * options, int enabled) Configures whether Numeric Annotation Glyphs (NAGs) are rendered symbolically or numerically.
scid_error	scid_game_pgn_options_supplemental_tags_set(scid_game_pgn_options * options, int enabled) Configures whether non-standard supplemental header tags are emitted in the PGN tag roster.
scid_error	scid_game_pgn_options_line_width_set(scid_game_pgn_options * options, unsigned line_width) Sets the maximum line width in characters for movetext line wrapping.
void	scid_game_pgn_options_free(scid_game_pgn_options * options) Releases a PGN options handle and all associated resources.
scid_error	scid_game_pgn_options_create(scid_game_pgn_options ** out_options) Allocates and initialises a new PGN export options handle with default settings.
scid_error	scid_game_pgn_options_comments_set(scid_game_pgn_options * options, int enabled) Configures whether move and position comments are included in the exported movetext.

Types Documentation

typedef scid_game_pgn_options

typedef struct scid_game_pgn_options scid_game_pgn_options;

Opaque configuration handle for customizing PGN text generation.

See:

• scid_game_pgn_options_create()
• scid_game_pgn_options_free()

Holds encoding preferences including symbolic NAG rendering, inclusion of supplemental tags, commentary emission, variation expansion, and line wrapping.

Options handles are created using scid_game_pgn_options_create() with default settings, modified via setter functions, and destroyed via scid_game_pgn_options_free().

Functions Documentation

function scid_game_to_pgn

scid_error scid_game_to_pgn(
    const scid_game * game,
    const scid_game_pgn_options * options,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Encodes a game into Portable Game Notation (PGN) text.

Parameters:

• game Pointer to the game entity to encode. Must not be NULL.
• options Pointer to custom export options, or NULL to use default settings.
• out_text Caller-allocated buffer receiving the null-terminated PGN text. May be NULL if out_text_capacity is 0 to query required capacity.
• out_text_capacity Capacity of out_text in bytes.
• out_text_size Pointer receiving the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

• SCID_OK PGN text encoded successfully.
• SCID_ERROR_BAD_ARG If game or out_text_size is NULL.
• SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient to hold the full PGN output.

See:

• scid_game_create()
• scid_game_pgn_options_create()

Exports the game's tag roster, commentary, NAG annotations, and movetext according to the formatting preferences defined in options (or default settings if options is NULL).

function scid_game_pgn_options_variations_set

scid_error scid_game_pgn_options_variations_set(
    scid_game_pgn_options * options,
    int enabled
)

Configures whether sub-variations are recursively included in the exported movetext.

Parameters:

• options Pointer to the options handle. Must not be NULL.
• enabled Non-zero (1) to include ( variation ) branches; zero (0) for mainline only.

Returns:

• SCID_OK Option set successfully.
• SCID_ERROR_BAD_ARG If options is NULL.

function scid_game_pgn_options_symbolic_nags_set

scid_error scid_game_pgn_options_symbolic_nags_set(
    scid_game_pgn_options * options,
    int enabled
)

Configures whether Numeric Annotation Glyphs (NAGs) are rendered symbolically or numerically.

Parameters:

• options Pointer to the options handle. Must not be NULL.
• enabled Non-zero (1) for symbolic glyphs; zero (0) for numeric $N codes.

Returns:

• SCID_OK Option set successfully.
• SCID_ERROR_BAD_ARG If options is NULL.

When enabled (1), standard glyphs (NAG 1..6) are output as symbols (!, ?, !!, ??, !?, ?!). When disabled (0), all NAGs are output in standard numeric format ($1, $2, etc.).

function scid_game_pgn_options_supplemental_tags_set

scid_error scid_game_pgn_options_supplemental_tags_set(
    scid_game_pgn_options * options,
    int enabled
)

Configures whether non-standard supplemental header tags are emitted in the PGN tag roster.

Parameters:

• options Pointer to the options handle. Must not be NULL.
• enabled Non-zero (1) to include supplemental tags; zero (0) to omit them.

Returns:

• SCID_OK Option set successfully.
• SCID_ERROR_BAD_ARG If options is NULL.

The mandatory Seven Tag Roster (STR) and FEN (for non-standard setups) are always emitted. Non-standard supplemental tags (e.g. WhiteElo, ECO, Annotator, Time) are included when enabled.

function scid_game_pgn_options_line_width_set

scid_error scid_game_pgn_options_line_width_set(
    scid_game_pgn_options * options,
    unsigned line_width
)

Sets the maximum line width in characters for movetext line wrapping.

Parameters:

• options Pointer to the options handle. Must not be NULL.
• line_width Maximum line width in columns, or 0 for unbounded line length.

Returns:

• SCID_OK Option set successfully.
• SCID_ERROR_BAD_ARG If options is NULL.

Standard PGN format recommends a line limit of 80 characters. Setting line_width to 0 disables line wrapping (unbounded single lines for movetext).

function scid_game_pgn_options_free

void scid_game_pgn_options_free(
    scid_game_pgn_options * options
)

Releases a PGN options handle and all associated resources.

Parameters:

• options Pointer to the options handle to release. If NULL, this function performs no action.

Note: Passing NULL is guaranteed to be a safe no-op.

function scid_game_pgn_options_create

scid_error scid_game_pgn_options_create(
    scid_game_pgn_options ** out_options
)

Allocates and initialises a new PGN export options handle with default settings.

Parameters:

• out_options Pointer to a handle pointer receiving the newly allocated options. Must not be NULL.

Returns:

• SCID_OK Options handle created successfully.
• SCID_ERROR_BAD_ARG If out_options is NULL.

See: scid_game_pgn_options_free()

Note: The caller acquires ownership of out_options and must release it with scid_game_pgn_options_free().

Default settings:

• Symbolic NAGs: enabled (1)
• Supplemental tags: enabled (1)
• Comments: enabled (1)
• Variations: enabled (1)
• Line width: 80 characters

function scid_game_pgn_options_comments_set

scid_error scid_game_pgn_options_comments_set(
    scid_game_pgn_options * options,
    int enabled
)

Configures whether move and position comments are included in the exported movetext.

Parameters:

• options Pointer to the options handle. Must not be NULL.
• enabled Non-zero (1) to include { comment } blocks; zero (0) to strip commentary.

Returns:

• SCID_OK Option set successfully.
• SCID_ERROR_BAD_ARG If options is NULL.

---

Updated on 2026-09-02 at 15:26:09 +0000