Skip to content

Cards and hands

A card game starts with cards, so that is where the rules file starts too.

A card

Here is a Snap card, as Games/Snap/Rules.lean defines it:

structure Card where
  /-- 1 = Ace … 11 = Jack, 12 = Queen, 13 = King. -/
  rank : Nat
  /-- 0 = ♠, 1 = ♥, 2 = ♦, 3 = ♣. -/
  suit : Nat
  deriving DecidableEq, Repr, Inhabited

structure defines a new type made of named fields, like a record or a struct in other languages. A Card has two: its rank and its suit, both natural numbers. The comments starting /-- are doc comments: they belong to the field below them, and your editor shows them when you hover over a use of the field.

Why numbers rather than names like "Queen" or "hearts"? Because Snap only ever asks one question of a card: do two cards have the same rank? Numbers answer that directly. The names are only for showing cards to players, and that happens elsewhere, in Game.lean.

The last line, deriving DecidableEq, Repr, Inhabited, asks Lean to write three things for us:

  • DecidableEq: a way to decide whether two cards are equal.
  • Repr: a way to show a card, which #eval uses.
  • Inhabited: a default card, for the rare places Lean needs one.

Making cards

There are two ways to write a card. Name every field, or list the fields in order between angle brackets (type \< and \> in VS Code):

/-- info: { rank := 12, suit := 1 } -/
#guard_msgs in
#eval ({ rank := 12, suit := 1 } : Card)

/-- info: { rank := 12, suit := 1 } -/
#guard_msgs in
#eval (⟨12, 1⟩ : Card)

The (… : Card) tells Lean which type you mean. Angle brackets are short, so the engine uses them everywhere, but they rely on you knowing the order of the fields.

A field is read with a dot:

def queenOfHearts : Card := ⟨12, 1⟩

/-- info: 12 -/
#guard_msgs in
#eval queenOfHearts.rank

Because Card derives DecidableEq, == compares two cards, field by field:

/-- info: true -/
#guard_msgs in
#eval queenOfHearts == ⟨12, 1⟩

/-- info: false -/
#guard_msgs in
#eval queenOfHearts == ⟨12, 2⟩

A hand

Each player has two piles: the face-down stack they flip from, and the face-up pile they flip onto.

def hand (s : State) : Fin 2 → Hand
  | 0 => s.hand0
  | 1 => s.hand1

List Card is a list of cards. [] is the empty list, and := [] gives each field a default, so a Hand can be written without them. The comment says which end of a list is the top of the pile: the first element, called the head. That choice matters later, when cards move from pile to pile.

A function about hands:

def Hand.size (h : Hand) : Nat := h.down.length + h.up.length

Its name is Hand.size, so it lives with Hand, and that lets you call it with a dot on any hand, h.size, as if it were a field. h.down.length is the same idea one level down: length is a function on lists.

def myHand : Hand := { down := [⟨1, 0⟩, ⟨7, 3⟩], up := [queenOfHearts] }

/-- info: 3 -/
#guard_msgs in
#eval myHand.size

/-- info: { down := [], up := [] } -/
#guard_msgs in
#eval ({} : Hand)

{} is a hand with every field at its default: two empty piles.

Exercises

  1. Write Card.isRed, which says whether a card is a heart or a diamond (suits 1 and 2). Use == to compare numbers and || for or.
  2. Write Card.sameColour, which says whether two cards are the same colour.

Where to put them

A dot call like c.isRed looks for isRed among the functions that live with c's type. Snap's Card is really called Games.Snap.Card, so Card.isRed has to be defined inside namespace Games.Snap, or the dot won't find it. Wrap your definitions like this:

import Games.Snap.Rules

namespace Games.Snap
-- your definitions here
end Games.Snap
Solution
namespace Games.Snap

def Card.isRed (c : Card) : Bool := c.suit == 1 || c.suit == 2

/-- info: true -/
#guard_msgs in
#eval (⟨12, 1⟩ : Card).isRed

/-- info: false -/
#guard_msgs in
#eval (⟨1, 0⟩ : Card).isRed

def Card.sameColour (c d : Card) : Bool := c.isRed == d.isRed

/-- info: true -/
#guard_msgs in
#eval (⟨12, 1⟩ : Card).sameColour ⟨3, 2⟩

end Games.Snap

Bool is the type of true and false. You'll meet its bigger sibling, Prop, when the proofs start.