Implement standard debuggers.

These debug actions are added to all players by default.

cardsim/deck.go

@@ -279,3 +279,145 @@ func (d *Deck[C]) Strip(shouldRemove func(idx int, c Card[C]) bool) int {
 	d.cards = Strip(d.cards, shouldRemove)
 	return origLen - d.Len()
 }
+
+// DeckDebugger is a Card[C], intended for use only as a debug action, that
+// lists the top 10 cards of the deck (without checking if they are drawable)
+// and allows various sorts of deck manipulation for free. It can't be drawn.
+type DeckDebugger[C StatsCollection] struct{}
+
+// Title implements Card[C].
+func (DeckDebugger[C]) Title(p *Player[C]) Message {
+	return MsgStr("Debug Mode Deck Controls")
+}
+
+// Urgent implements Card[C] as used in permanent actions. It's always valid
+// to use the deck debugger. Debug actions do not check urgency flags, but this
+// marks itself as urgent-compatible just in case.
+func (DeckDebugger[C]) Urgent(p *Player[C]) bool {
+	return true
+}
+
+// Drawn implements Card[C]. It can't be drawn.
+func (DeckDebugger[C]) Drawn(p *Player[C]) bool {
+	return false
+}
+
+// EventText implements Card[C]. It lists the top ten cards of the deck and
+// a few deck-related and hand-related stats.
+func (DeckDebugger[C]) EventText(p *Player[C]) (Message, error) {
+	var msgs []Message
+
+	msgs = append(msgs, Msgf("The Deck contains %d cards.", p.Deck.Len()))
+	if p.Deck.Len() > 0 {
+		portion := p.Deck.cards
+		msgs = append(msgs, nil)
+		topness := "All"
+		if p.Deck.Len() > 10 {
+			portion = p.Deck.cards[:10]
+			topness = "Top 10"
+		}
+		msgs = append(msgs, Msgf("%s cards in the Deck:", topness))
+		for i, c := range portion {
+			urgency := " "
+			if c.Urgent(p) {
+				urgency = "!"
+			}
+			msgs = append(msgs, Msgf(" %s %2d) %v", urgency, i+1, c.Title(p)))
+		}
+	}
+	msgs = append(msgs, nil)
+	msgs = append(msgs, Msgf("At the start of each turn, the Player draws to %d cards. The player has %d cards in hand.", p.HandLimit, len(p.Hand)))
+	return MultiMessage(msgs), nil
+}
+
+// Options implements Card[C]. It offers many possible actions.
+func (DeckDebugger[C]) Options(p *Player[C]) ([]CardOption[C], error) {
+	ret := []CardOption[C]{
+		&BasicOption[C]{
+			Text: MsgStr("Draw a card."),
+			Effect: func(p *Player[C]) error {
+				return p.Draw()
+			},
+			Output: MsgStr("Done."),
+		},
+		&BasicOption[C]{
+			Text: MsgStr("Shuffle the deck."),
+			Effect: func(p *Player[C]) error {
+				return p.Deck.Shuffle()
+			},
+			Output: MsgStr("Done."),
+		},
+		&BasicOption[C]{
+			Text: MsgStr("Shuffle top half."),
+			Effect: func(p *Player[C]) error {
+				return p.Deck.ShuffleTop(0.5)
+			},
+			Output: MsgStr("Done."),
+		},
+		&BasicOption[C]{
+			Text: MsgStr("Shuffle bottom half."),
+			Effect: func(p *Player[C]) error {
+				return p.Deck.ShuffleBottom(0.5)
+			},
+			Output: MsgStr("Done."),
+		},
+	}
+	for _, n := range []int{1, 3, 5, 10} {
+		if p.Deck.Len() <= n {
+			break
+		}
+
+		// We don't want the functions we're creating to all share the same "n"
+		// field -- we want to create distinct functions that move distinct
+		// numbers of cards. For more information on what's going on here, see
+		// https://eli.thegreenplace.net/2019/go-internals-capturing-loop-variables-in-closures/
+		//
+		// For the curious, the Go developers don't like the gotcha that
+		// this "shadow variable with itself" workaround patches over either.
+		// Here's the guy who implemented apologizing for it and discussing
+		// changing it: https://github.com/golang/go/discussions/56010
+		//
+		// "Loop variables being per-loop instead of per-iteration is the only
+		//  design decision I know of in Go that makes programs incorrect more
+		//  often than it makes them correct." -- Russ Cox (rsc)
+		n := n
+		invN := p.Deck.Len() - n
+		ret = append(ret,
+			&BasicOption[C]{
+				Text: Msgf("Move the top %d card(s) to the bottom of the deck, in order.", n),
+				Effect: func(p *Player[C]) error {
+					p.Deck.cards = append(p.Deck.cards, p.Deck.cards[:n]...)
+					p.Deck.cards = p.Deck.cards[n:]
+					return nil
+				},
+				Output: MsgStr("Done."),
+			},
+			&BasicOption[C]{
+				Text: Msgf("Move the bottom %d card(s) to the top of the deck, in order.", n),
+				Effect: func(p *Player[C]) error {
+					p.Deck.cards = append(p.Deck.cards, p.Deck.cards[:invN]...)
+					p.Deck.cards = p.Deck.cards[invN:]
+					return nil
+				},
+				Output: MsgStr("Done."),
+			},
+		)
+
+		if n > 1 {
+			ret = append(ret, &BasicOption[C]{
+				Text: Msgf("Shuffle the top %d card(s) of the deck.", n),
+				Effect: func(p *Player[C]) error {
+					return p.Deck.ShufflePart(0, n)
+				},
+				Output: MsgStr("Done."),
+			})
+		}
+	}
+	return ret, nil
+}
+
+// Then implements Card[C]. It refunds the action point.
+func (DeckDebugger[C]) Then(p *Player[C], o CardOption[C]) error {
+	p.ActionsRemaining++
+	return nil
+}