getting-started.md

Getting Started

pokerstove-go is a native Go package for PokerStove-style card parsing, evaluation, comparison, and showdown enumeration. C++ PokerStove remains the behavior oracle through parity tests, but applications import and run Go code directly.

Install

go get github.com/kevinmcmahon/pokerstove-go

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

Parse Cards

Cards use rank then suit, such as Ac for the ace of clubs. A CardSet deduplicates cards and prints in the package's canonical deck order.

cards, err := pokerstove.ParseCardSet("Ac Kd\nQh")
if err != nil {
	panic(err)
}
fmt.Println(cards)        // AcKdQh
fmt.Println(cards.Size()) // 3

Ranks are 2 through 9, T, J, Q, K, A. Suits are c, d, h, and s.

Create an Evaluator

Use NewEvaluator when the game may vary by caller input or configuration.

evaluator, err := pokerstove.NewEvaluator("omaha/8")
if err != nil {
	panic(err)
}

metadata := evaluator.Metadata()
fmt.Println(metadata.Name)           // Omaha high/low
fmt.Println(metadata.HandSize)       // 4
fmt.Println(metadata.BoardSize)      // 5
fmt.Println(metadata.EvaluationSize) // 2

Common identifiers include:

Identifier	Game
h	Hold'em
o, omaha	Omaha high
o8, o/8, omaha/8	Omaha high/low
e	Stud/8
k	Kansas City lowball
l	Ace-to-five lowball
t	Triple draw 2-7
T	Triple draw A-5

Evaluate and Compare

For Hold'em-only code, EvaluateHoldem is the smallest direct entry point.

hand, _ := pokerstove.ParseCardSet("AcKs")
board, _ := pokerstove.ParseCardSet("AhKd2c3d9s")

evaluation, err := pokerstove.EvaluateHoldem(hand, board)
if err != nil {
	panic(err)
}
fmt.Println(evaluation.Type == pokerstove.TwoPair) // true
fmt.Println(evaluation.Major, evaluation.Minor)    // A K

For game-polymorphic code, call methods on Evaluator.

evaluator, _ := pokerstove.NewEvaluator("h")
left, _ := pokerstove.ParseCardSet("AcAs")
right, _ := pokerstove.ParseCardSet("KhQh")
board, _ := pokerstove.ParseCardSet("2c3d4h5s9c")

comparison, err := evaluator.Compare(left, right, board)
if err != nil {
	panic(err)
}
fmt.Println(comparison > 0) // aces beat king-high

Run a Showdown

EvaluateShowdown takes text inputs, parses distributions, completes partial hands and boards when needed, and returns win, tie, and normalized equity shares.

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

fmt.Println(result.Players[0].WinShares) // 1
fmt.Println(result.Players[0].Equity)    // 1

For more task-oriented examples, see API by Workflow and Showdowns and Ranges.