{"id":28941240,"url":"https://github.com/yashbhalodi/chessnote","last_synced_at":"2026-07-04T04:33:37.856Z","repository":{"id":300424059,"uuid":"1006119024","full_name":"YashBhalodi/chessnote","owner":"YashBhalodi","description":"A production-grade, high-performance Go library for parsing PGN chess files. Built with TDD for rock-solid reliability and a developer-first API.","archived":false,"fork":false,"pushed_at":"2025-06-21T15:32:06.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T16:31:53.018Z","etag":null,"topics":["chess","go","pgn","pgn-parser","tdd"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YashBhalodi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T14:36:16.000Z","updated_at":"2025-06-21T15:32:08.000Z","dependencies_parsed_at":"2025-06-21T16:42:07.368Z","dependency_job_id":null,"html_url":"https://github.com/YashBhalodi/chessnote","commit_stats":null,"previous_names":["yashbhalodi/chessnote"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/YashBhalodi/chessnote","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YashBhalodi%2Fchessnote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YashBhalodi%2Fchessnote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YashBhalodi%2Fchessnote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YashBhalodi%2Fchessnote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YashBhalodi","download_url":"https://codeload.github.com/YashBhalodi/chessnote/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YashBhalodi%2Fchessnote/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261265483,"owners_count":23132634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","go","pgn","pgn-parser","tdd"],"created_at":"2025-06-23T02:09:39.617Z","updated_at":"2025-10-28T12:40:49.489Z","avatar_url":"https://github.com/YashBhalodi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChessNote: High-Performance PGN Parsing in Go\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/YashBhalodi/chessnote)](https://goreportcard.com/report/github.com/YashBhalodi/chessnote)\n[![Go Reference](https://pkg.go.dev/badge/github.com/YashBhalodi/chessnote.svg)](https://pkg.go.dev/github.com/YashBhalodi/chessnote)\n[![CI](https://github.com/YashBhalodi/chessnote/actions/workflows/ci.yml/badge.svg)](https://github.com/YashBhalodi/chessnote/actions/workflows/ci.yml)\n\n**ChessNote is a production-grade, high-performance Go library for parsing Portable Game Notation (PGN).** It's engineered from the ground up to be a foundational component for ambitious chess applications, from powerful analysis tools and database backends to beautiful game renderers.\n\nWe're not just parsing text; we're providing a reliable, rigorously-tested, and developer-friendly toolkit for bringing chess data to life.\n\n## Why ChessNote?\n\nChessNote is engineered for production usecases. It's built on a philosophy of reliability and performance, making it the ideal choice for startups and developers who need a parser that just works.\n\n*   **Rock-Solid Reliability:** Built with a strict **Test-Driven Development (TDD)** methodology, ChessNote boasts comprehensive test coverage. Every feature, from simple pawn moves to complex variations, is verified. The parser is designed to handle real-world, messy PGNs without panicking, returning structured errors that make debugging a breeze.\n\n*   **Blazing-Fast Performance:** Written in pure, idiomatic Go, ChessNote is designed for speed. It minimizes allocations and uses an efficient scanning and parsing model to handle large PGN databases with ease. Its performance is validated by a comprehensive benchmark suite (see the `benchmarks/` directory).\n\n*   **A Developer-First API:** The public API is clean, discoverable, and a joy to use. We believe developers should spend their time building great applications, not fighting with a clunky parser. Our data structures (`Game`, `Move`, `Square`) are intuitive and well-documented.\n\n## Feature-Complete Parser\n\nChessNote implements the complete PGN standard, allowing you to parse virtually any PGN file you encounter.\n\n- [x] **Full Tag Pair Support:** Parses the Seven Tag Roster and any other custom tags.\n- [x] **Complete Movetext Parsing:**\n    - [x] Standard pawn and piece moves (`e4`, `Nf3`)\n    - [x] Captures (`exd5`, `Nxf3`)\n    - [x] Checks (`+`) and Checkmates (`#`)\n    - [x] Disambiguation (`Rdf8`, `N1c3`)\n    - [x] Pawn Promotion (`e8=Q`)\n    - [x] Castling (`O-O`, `O-O-O`)\n- [x] **Advanced PGN Syntax:**\n    - [x] Comments (`{...}` and `;...`)\n    - [x] Recursive Annotation Variations (RAVs) `(...)`\n    - [x] Numeric Annotation Glyphs (NAGs) `($1, $18)`\n- [x] **Game Termination Markers:** Correctly identifies the game result (`1-0`, `0-1`, `1/2-1/2`, `*`).\n- [x] **Robust Error Handling:** Returns detailed, structured errors for invalid syntax.\n\n## Quick Start\n\nGet the library:\n```sh\ngo get github.com/YashBhalodi/chessnote\n```\n\nParse a complete PGN game in just a few lines of code. Here's an example parsing Paul Morphy's famous \"Opera Game\":\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/YashBhalodi/chessnote\"\n)\n\nfunc main() {\n\t// PGN of the \"Opera Game\" (Paul Morphy vs. Duke Karl / Count Isouard, 1858)\n\tpgn := `\n[Event \"A Night at the Opera\"]\n[Site \"Paris, France\"]\n[Date \"1858.??.??\"]\n[White \"Paul Morphy\"]\n[Black \"Duke Karl / Count Isouard\"]\n[Result \"1-0\"]\n\n1. e4 e5 2. Nf3 d6 3. d4 Bg4 4. dxe5 Bxf3 5. Qxf3 dxe5 6. Bc4 Nf6 7. Qb3 Qe7\n8. Nc3 c6 9. Bg5 b5 10. Nxb5 cxb5 11. Bxb5+ Nbd7 12. O-O-O Rd8\n13. Rxd7 Rxd7 14. Rd1 Qe6 15. Bxd7+ Nxd7 16. Qb8+ Nxb8 17. Rd8# 1-0\n`\n\tgame, err := chessnote.ParseString(pgn)\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to parse PGN: %v\", err)\n\t}\n\n\tfmt.Printf(\"Successfully parsed game: %s vs %s\\n\", game.Tags[\"White\"], game.Tags[\"Black\"])\n\tfmt.Printf(\"Result: %s\\n\", game.Result)\n\tfmt.Printf(\"Total moves: %d\\n\", len(game.Moves))\n\n\t// Let's inspect the brilliant final move!\n\tfinalMove := game.Moves[len(game.Moves)-1]\n\tfmt.Printf(\"Final move: Rd8#\\n\")\n\tfmt.Printf(\"  - Piece: Rook\\n\")\n\tfmt.Printf(\"  - Destination: d8\\n\")\n\tfmt.Printf(\"  - Is Checkmate: %t\\n\", finalMove.IsMate)\n}\n```\n\n## Running the Examples\n\nThe `examples/` directory contains standalone, runnable programs to showcase the library's features.\n\nTo run the basic parsing example:\n\n```sh\n# Navigate to the example directory\ncd examples/basic_parser\n\n# Run the program. It will parse the included 'opera_game.pgn' by default.\ngo run .\n\n# You can also point it to your own PGN file\ngo run . --pgn_file=/path/to/your/game.pgn\n```\n\nTo run the advanced iterator example, which demonstrates traversing a game's move tree including variations:\n\n```sh\n# Navigate to the example directory\ncd examples/advanced_iterator\n\n# Run the program.\ngo run .\n```\n\n## Project Philosophy\n\nThis project adheres to a strict set of engineering guidelines focused on creating professional, enterprise-grade software. We practice **Test-Driven Development (TDD)**, maintain a comprehensive test suite, and prioritize a clean, stable, and well-documented public API.\n\n## Technical Documentation\n\nFor a deep dive into the parser's architecture, execution flow, and design decisions, please see our comprehensive **[Technical Documentation](./docs/README.md)**. This is the best resource for developers looking to contribute to the project or understand its inner workings.\n\n## Roadmap \u0026 Contributing\n\nChessNote is currently in stable production release v1.0.0 for parsing PGNs. \n\nThere is no immidiate plan for new features. However, we are open to contributions! Please open an issue to discuss any proposed changes. Pull requests are also welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.\n\n## License\n\nChessNote is released under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyashbhalodi%2Fchessnote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyashbhalodi%2Fchessnote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyashbhalodi%2Fchessnote/lists"}