bgfparser

README

BGFParser

Go package for parsing BGBlitz backgammon files (BGF binary matches, TXT positions).

Features

• TXT Parser: Board positions, evaluations, cube decisions, multilingual (EN/FR/DE/JP)
• BGF Parser: Binary match files with SMILE encoding support
• Web-Ready: Parse from io.Reader (HTTP uploads, memory, streams)
• JSON Export: Database-ready structures with JSON tags

Installation

go get github.com/kevung/bgfparser

Quick Start

// Parse position file
pos, _ := bgfparser.ParseTXT("position.txt")
fmt.Printf("%s vs %s, Score: %d-%d\n", 
    pos.PlayerX, pos.PlayerO, pos.ScoreX, pos.ScoreO)

// Parse from HTTP upload
match, _ := bgfparser.ParseBGFFromReader(uploadedFile)

// Export to JSON
jsonData, _ := pos.ToJSON()

CLI Tools

Build and run command-line tools:

# Build tools
go build -o bin/parse_txt ./examples/parse_txt/
go build -o bin/web_server ./examples/web_server/

# Parse TXT file
./bin/parse_txt position.txt

# Start web server (http://localhost:8080)
./bin/web_server

# Or run directly
go run examples/parse_txt/main.go position.txt

Data Structures

type Position struct {
    Board       [26]int          // Checker positions (1-24=points, 25=bar)
    PlayerX, PlayerO string       // Player names
    ScoreX, ScoreO   int         // Scores
    MatchLength int              // Match length
    XGID        string           // Position ID
    OnRoll      string           // "X" or "O"
    Dice        [2]int           // Dice roll
    CubeValue   int              // Cube value
    Evaluations []Evaluation     // Move analysis
    CubeDecisions []CubeDecision // Cube analysis (all actions)
    CubelessEquity float64       // Cubeless equity
    CubefulEquity  float64       // Cubeful equity
}

type Evaluation struct {
    Rank   int     // 1 = best move
    Move   string  // Move notation
    Equity float64 // Equity value
    Win, WinG, WinBG float64 // Win probabilities
}

type CubeDecision struct {
    Action  string  // "No Double", "Double/Take", "Double/Pass"
    MWC     float64 // Match winning chances
    EMG     float64 // Effective match gammons
}

Examples

See examples/ directory:

• parse_txt/ - Parse TXT positions
• parse_bgf/ - Parse BGF matches
• batch_parse/ - Process multiple files
• web_server/ - HTTP upload interface

Documentation

• API Reference - Complete API docs
• Quick Reference - Common patterns
• Extracted Information - All parsed fields
• Multilingual Support - Language support details

License

MIT License - see LICENSE file.

Acknowledgments

• Frank Berger - BGBlitz creator
• LeLuxNet - SMILE decoder

Documentation

Overview

Package bgfparser provides parsers for BGBlitz backgammon data files.

BGBlitz is a backgammon analysis software that stores data in two formats:

• TXT: Human-readable position files showing board state and analysis
• BGF: Binary match files using JSON with gzip compression and SMILE encoding

This package can parse both formats and extract position data, evaluations, match information, and move analysis.

Index

• type CubeDecision
• type Evaluation
• type Match
  • func ParseBGF(filename string) (*Match, error)
  • func ParseBGFFromReader(reader io.Reader) (*Match, error)
  • func (m *Match) GetMatchInfo() map[string]interface{}
  • func (m *Match) String() string
  • func (m *Match) ToJSON() ([]byte, error)
• type ParseError
  • func (e *ParseError) Error() string
• type Position
  • func ParseTXT(filename string) (*Position, error)
  • func ParseTXTFromReader(reader io.Reader) (*Position, error)
  • func (p *Position) ToJSON() ([]byte, error)

Types

type CubeDecision

type CubeDecision struct {
	Action  string  `json:"action"` // "Double/Take", "Double/Pass", "No Double"
	MWC     float64 `json:"mwc"`    // Match Winning Chances
	MWCDiff float64 `json:"mwc_diff"`
	EMG     float64 `json:"emg"` // EMG (Normalized equity)
	EMGDiff float64 `json:"emg_diff"`
	IsBest  bool    `json:"is_best"`
}

CubeDecision represents a cube decision analysis

type Evaluation

type Evaluation struct {
	Rank   int     `json:"rank"`
	Move   string  `json:"move"`
	Equity float64 `json:"equity"`
	Diff   float64 `json:"diff"`
	Win    float64 `json:"win"`
	WinG   float64 `json:"win_g"`
	WinBG  float64 `json:"win_bg"`
	LoseG  float64 `json:"lose_g"`
	LoseBG float64 `json:"lose_bg"`
	IsBest bool    `json:"is_best"`
}

Evaluation represents a move evaluation

type Match

type Match struct {
	Format   string `json:"format"`
	Version  string `json:"version"`
	Compress bool   `json:"compress"`
	UseSmile bool   `json:"useSmile"`

	// Match data will be populated from the JSON structure
	Data map[string]interface{} `json:"data,omitempty"`
}

Match represents a complete backgammon match from a BGF file

func ParseBGF

func ParseBGF(filename string) (*Match, error)

ParseBGF parses a BGBlitz BGF (binary match) file from disk This is a convenience wrapper around ParseBGFFromReader that handles file reading.

BGF files consist of: 1. A JSON header line with format info (uncompressed) 2. The rest of the file is gzipped JSON data (optionally SMILE encoded)

func ParseBGFFromReader

func ParseBGFFromReader(reader io.Reader) (*Match, error)

ParseBGFFromReader parses a BGBlitz BGF file from an io.Reader This allows parsing BGF files from network streams, memory buffers, HTTP uploads, or any io.Reader source.

Example usage with HTTP upload:

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    file, _, _ := r.FormFile("bgffile")
    defer file.Close()

    match, err := bgfparser.ParseBGFFromReader(file)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(match)
}

func (*Match) GetMatchInfo

func (m *Match) GetMatchInfo() map[string]interface{}

GetMatchInfo extracts basic match information from a parsed BGF file

func (*Match) String

func (m *Match) String() string

String returns a human-readable representation of the match

func (*Match) ToJSON

func (m *Match) ToJSON() ([]byte, error)

ToJSON serializes the Match to JSON

type ParseError

type ParseError struct {
	File    string
	Line    int
	Message string
}

ParseError represents an error during parsing

func (*ParseError) Error

func (e *ParseError) Error() string

type Position

type Position struct {
	// Board represents the checkers on each point (1-24), bar, and off
	// Points 1-24 for both players, positive for X, negative for O
	Board [26]int `json:"board"`

	// Player information
	PlayerX string `json:"player_x"`
	PlayerO string `json:"player_o"`
	ScoreX  int    `json:"score_x"`
	ScoreO  int    `json:"score_o"`

	// Match information
	MatchLength int  `json:"match_length"`
	Crawford    bool `json:"crawford"`

	// Position identifiers
	PositionID string `json:"position_id"` // BGBlitz Position-ID
	MatchID    string `json:"match_id"`    // BGBlitz Match-ID
	XGID       string `json:"xgid"`        // XG format ID

	// Current state
	OnRoll    string         `json:"on_roll"` // "X" or "O"
	Dice      [2]int         `json:"dice"`
	CubeValue int            `json:"cube_value"`
	CubeOwner string         `json:"cube_owner"` // "", "X", "O"
	OnBar     map[string]int `json:"on_bar"`
	PipCount  map[string]int `json:"pip_count"`

	// Evaluation data
	Evaluations   []Evaluation   `json:"evaluations,omitempty"`
	CubeDecisions []CubeDecision `json:"cube_decisions,omitempty"`

	// Cube analysis summary (when present)
	CubelessEquity float64 `json:"cubeless_equity,omitempty"`
	CubefulEquity  float64 `json:"cubeful_equity,omitempty"`
	EquityStdDev   float64 `json:"equity_std_dev,omitempty"`
}

Position represents a backgammon position

func ParseTXT

func ParseTXT(filename string) (*Position, error)

ParseTXT parses a BGBlitz position text file from disk This is a convenience wrapper around ParseTXTFromReader that handles file reading.

func ParseTXTFromReader

func ParseTXTFromReader(reader io.Reader) (*Position, error)

ParseTXTFromReader parses a BGBlitz TXT position file from an io.Reader This allows parsing TXT files from network streams, memory buffers, HTTP uploads, or any io.Reader source.

Example usage with in-memory data:

data := []byte("... TXT content ...")
pos, err := bgfparser.ParseTXTFromReader(bytes.NewReader(data))

func (*Position) ToJSON

func (p *Position) ToJSON() ([]byte, error)

ToJSON serializes the Position to JSON