pokerstove-go

Native Go PokerStove core for poker applications. This package is a Go port with C++ PokerStove parity tests; it is not a runtime wrapper around the C++ library or command-line tools.

Install

Requires Go 1.22 or newer.

go get github.com/kevinmcmahon/pokerstove-go

import pokerstove "github.com/kevinmcmahon/pokerstove-go"

No separate package publishing step is required for Go modules. Once this repository is public, users can add it with go get; pkg.go.dev will index the module from the public repository.

Tagged releases use Go module semantic versions such as v0.1.0. Until the first tag exists, go get resolves to a pseudo-version from the default branch. For reproducible builds, depend on a tagged version once releases begin. Future v2 and later releases require the Go module path to include the major version suffix, such as /v2.

Quick Start

hand, err := pokerstove.ParseCardSet("AcAs")
if err != nil {
	return err
}
other, err := pokerstove.ParseCardSet("KhQh")
if err != nil {
	return err
}
board, err := pokerstove.ParseCardSet("2c3d4h5s9c")
if err != nil {
	return err
}

evaluator, err := pokerstove.NewEvaluator("h")
if err != nil {
	return err
}
metadata := evaluator.Metadata() // Hold'em: 2-card hands, 5-card boards.

holdem, err := pokerstove.EvaluateHoldem(hand, board)
if err != nil {
	return err
}
evaluation, err := evaluator.Evaluate(hand, board)
if err != nil {
	return err
}
comparison, err := evaluator.Compare(hand, other, board)
if err != nil {
	return err
}
_ = metadata
_ = holdem
_ = evaluation
_ = comparison

result, err := pokerstove.EvaluateShowdown(pokerstove.ShowdownRequest{
	Game:  "h",
	Board: "2c3d4h5s9c",
	Hands: []string{"AcAs", "KhQh"},
})
if err != nil {
	return err
}
_ = result

ParseCardSet accepts two-character card tokens with optional whitespace. NewEvaluator accepts PokerStove game identifiers and common aliases such as h, o, o8, and omaha/8.

Guides

• Getting Started
• API by Workflow
• Showdowns and Ranges
• Errors and Validation
• Compatibility Matrix
• Performance
• Migration from C++ PokerStove

Current Scope

The package supports direct evaluation and comparison for the copied C++ parity rows across Hold'em, Omaha variants, Omaha/8 variants, Stud/8, Stud high/low no qualifier, lowball, three-card poker, razz, draw, and badugi ordering cases. Showdown oracle coverage is documented separately in the compatibility matrix. Showdown evaluation completes partial hands and boards, applies weighted card distributions, handles split pots, and preserves PokerStove's zero-share behavior when no legal disjoint completion exists.

License

pokerstove-go is licensed under the BSD 3-Clause License. See LICENSE.

This project is a native Go port with behavior validated against PokerStove. PokerStove is copyright Andrew C. Prock and is used under its BSD-style license. See THIRD_PARTY_NOTICES.md.