rubylabs 0.5.5 → 0.6.2

data/lib/rubylabs.rb

@@ -18,6 +18,7 @@ autoload :IterationLab,   "iterationlab.rb"
 autoload :RecursionLab,   "recursionlab.rb"
 autoload :HashLab, 			  "hashlab.rb"
 autoload :BitLab, 			  "bitlab.rb"
+autoload :MARSLab, 			  "marslab.rb"
 autoload :RandomLab, 		  "randomlab.rb"
 autoload :EncryptionLab, 	"encryptionlab.rb"
 autoload :ELIZALab, 		  "elizalab.rb"
@@ -64,20 +65,20 @@ Log base 2.
     a < b ? a : b
   end
   
-=begin rdoc
-  Return a copy of object x with the elements in a new, scrambled order.  The
-  parameter x can be any object that has an index operator (e.g. strings or
-  arrays).
-=end
-  
-  def permutation(x)
-    res = x.clone
-    for i in 0..res.length-2
-      r = rand(res.length-i) + i
-      res[i], res[r] = res[r], res[i]
-    end
-    return res
-  end
+# =begin rdoc
+#   Return a copy of object x with the elements in a new, scrambled order.  The
+#   parameter x can be any object that has an index operator (e.g. strings or
+#   arrays).
+# =end
+#   
+#   def permutation(x)
+#     res = x.clone
+#     for i in 0..res.length-2
+#       r = rand(res.length-i) + i
+#       res[i], res[r] = res[r], res[i]
+#     end
+#     return res
+#   end
   
 =begin rdoc
   

data/test/mars_test.rb

@@ -0,0 +1,519 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'test_helper'
+
+=begin rdoc
+  This file has tests of the code written for the CoreWar project:  an
+  assembler for "Redcode" programs, and a "MARS" virtual machine emulator.  
+  
+  The should probably be a few more tests of individual components, but the
+  tests here just make sure the whole system operates as expected.  For example,
+  the instruction tests make arrays of strings containing source instructions,
+  pass them to the assembler, and execute the resulting instructions.  The
+  tests don't look too closely at the result, e.g. to make sure all the symbols
+  are in the symbol table, or each instruction has the right components -- the
+  test just makes sure the instructions do what they are expected to do.
+  
+  Tests in this file:
+  * an assembler test looks for syntax errors on ill-formed statements
+  * another assembler test looks at the code for a small, valid program
+  * an address mode test makes sure MOV instructions copy a piece of data
+      to the expected location using each of the four addressing modes
+  * individual instruction tests for each machine instruction
+  
+  NOTE: to test that instructions fetched from memory have the expected value
+  the assertions compare the result of instr.to_s to a string.  Things will
+  break horribly if the to_s method changes the format....
+  
+  NOTE: Be careful when making test programs -- there needs to be a label or 
+  a space before each opcode, e.g. [" DAT #0, <1", " DAT #0, #1"]
+  
+=end
+
+include MARSLab
+
+class TestMARS < Test::Unit::TestCase
+  
+  # Assembling these instructions should lead to one error per line, and
+  # no code generated.
+	
+  def test_01_syntax_errors
+    source = [
+      "@label  mov #0, #1      ; label needs to be alphanumeric",
+      "l@bel   mov #0, #1      ; label needs to be alphanumeric",
+      "mov #0, #1              ; unlabeled line must start with space",
+      "label @bogus #0, #1     ; opcode with non-alphanumeric",
+      "label b@gus #0, #1      ; opcode with non-alphanumeric",
+      "label muv #0, #1        ; unknown opcode",
+      "   mov #b@gus, #1       ; messed up operand",
+      "   mov #0 #1            ; missing comma",
+      "  EQU 3                 ; missing label on pseudo-op",
+      "x EQU 3x                ; arg not an integer",
+      "  END foo               ; undefined label",
+    ]
+    
+    name, code, symbols, errors = MARS.assemble(source)
+    
+    assert_equal source.length, errors.length       # every line generates an error
+    assert_equal 0, code.length                     # should be no instructions generated
+  end
+  
+  # A program from the ICWS archives -- has a wide variety of instructions, each
+  # addressing mode, and a pseudo-op.  Should produce no errors, and one machine
+  # instruction for each operation (inclduing DAT).
+  
+  def test_02_assembly
+    source = [
+      ";redcode",
+      ";name Mice",
+      ";author Chip Wendell",
+      ";strategy 1st place in ICWST'86",
+      ";strategy replicator",
+      ";assert 1",
+      "PTR     DAT             #0",
+      "START   MOV     #12    ,PTR",
+      "LOOP    MOV     @PTR   ,<COPY",
+      "        DJN     LOOP   ,PTR",
+      "        SPL     @COPY  ,0",
+      "        ADD     #653   ,COPY",
+      "        JMZ     START  ,PTR",
+      "COPY    DAT             #833",
+      "        END     START",
+    ]
+    
+    name, code, symbols, errors = MARS.assemble(source)
+    
+    assert_equal "Mice", name
+    assert_equal 0, errors.length
+    assert_equal 8, code.length
+    assert_equal 0, symbols["PTR"]
+    assert_equal 1, symbols["START"]
+    assert_equal 2, symbols["LOOP"]
+    assert_equal 7, symbols["COPY"]
+    
+  end
+  
+  # Assemble and run a synthetic program that has 4 MOV instructions.  Each
+  # instruction uses a different addressing mode to find the data source, and
+  # each copies its data to the same location.
+  
+  def test_03_modes
+    source = [
+      "immed			mov #1, target			  ; moves #1",
+      "direct		  mov dsrc, target		  ; moves #2",
+      "indir			mov @ptr, target	  	; moves #3",
+      "auto		  	mov <ptr2, target		  ; moves #4, decrements ptr2",
+      "target	  	dat #0, #0					  ; place to store data",
+      "dsrc			  dat #2, #2					  ; source for direct mode",
+      "ptr				dat #0, isrc				  ; a pointer to the indirect source",
+      "isrc		  	dat #3, #3            ; source for indirect mode",
+      "ptr2		  	dat #0, dummy				  ; this pointer should be decremented",
+      "					  dat #4, #4					  ; source for auto-decrement",
+      "dummy			dat #0, #0					  ; not used",
+    ]
+    
+    s = source.find { |line| line =~ /^target/ }
+    target = source.index(s)    
+    
+    s = source.find { |line| line =~ /^ptr2/ }
+    ptr2 = source.index(s)    
+    
+    mem, pc = make_machine(source)
+    
+    # value before first MOV:
+    assert_equal "DAT #0 #0", mem.fetch(target).to_s
+    
+    # value after MOV with immediate mode -- note only B field is copied
+    instr = mem.fetch(pc.next)
+    instr.execute(pc, mem)
+    assert_equal "DAT #0 #1", mem.fetch(target).to_s
+    
+    # value after MOV with direct mode -- note both A and B are moved
+    instr = mem.fetch(pc.next)
+    instr.execute(pc, mem)
+    assert_equal "DAT #2 #2", mem.fetch(target).to_s
+    
+    # value after MOV with indirect mode -- both A and B moved
+    instr = mem.fetch(pc.next)
+    instr.execute(pc, mem)
+    assert_equal "DAT #3 #3", mem.fetch(target).to_s
+    
+    # value of the pointer before the auto-decrement:
+    assert_equal "DAT #0 2", mem.fetch(ptr2).to_s
+    
+    # value after MOV with auto-decrement mode -- both A and B moved
+    instr = mem.fetch(pc.next)
+    instr.execute(pc, mem)
+    assert_equal "DAT #4 #4", mem.fetch(target).to_s
+    
+    # value of the pointer after the auto-decrement:
+    assert_equal "DAT #0 1", mem.fetch(ptr2).to_s
+    
+  end
+  
+  # A DAT instruction is effectively a halt instruction.  Note that the
+  # addressing modes are dereferenced, so the auto-decrement mode should
+  # cause the pointer to decrement.
+
+  def test_04_DAT
+    mem, pc = make_machine([" DAT #0, <1", " DAT #0, #1"])
+    
+    # pointer before executing the DAT:
+    assert_equal "DAT #0 #1", mem.fetch(1).to_s
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :halt, instr.execute(pc, mem)
+    
+    # pointer after executing the DAT -- value changed, mode did not
+    assert_equal "DAT #0 #0", mem.fetch(1).to_s
+    
+  end	
+  
+  # Simple MOV test just executes the instruction in the IMP program.
+  # A second test verifies a runtime error if the B field is immediate.
+
+  def test_05_MOV
+    mem, pc = make_machine([" MOV 0, 1"], 2)
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal mem.fetch(0).to_s, mem.fetch(1).to_s
+    
+    mem, pc = make_machine([" MOV 0, #1"])
+    instr = mem.fetch(pc.next)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+  end	
+  
+  # ADD tests
+  #   "ADD #A, dest" adds the constant A to the B field of dest
+  #   "ADD src, dest" adds the A and B fields to src to the A and B of dest
+  #   "ADD src, #B" is a runtime error (B can't be immediate)
+
+  def test_06_ADD
+    source = [
+      "     ADD #3,  sum",
+      "     ADD  x,  y",
+      "     ADD  x, #0",
+      "sum  DAT #1, #2",
+      "x    DAT #3, #4",
+      "y    DAT #5, #6",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal "DAT #1 #5", mem.fetch(3).to_s
+
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal "DAT #8 #10", mem.fetch(5).to_s
+
+    instr = mem.fetch(pc.next)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+  
+  # SUB tests -- same as ADD, but subtracting A from B
+
+  def test_07_SUB
+    source = [
+      "     SUB #3,  sum",
+      "     SUB  x,  y",
+      "     SUB  x, #0",
+      "sum  DAT #1, #10",
+      "x    DAT #3, #4",
+      "y    DAT #5, #6",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal "DAT #1 #7", mem.fetch(3).to_s
+
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal "DAT #2 #2", mem.fetch(5).to_s
+
+    instr = mem.fetch(pc.next)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+  
+  # JMP tests
+  #     JMP x should set the program counter to x
+  #     JMP #x is an error -- the operand can't be immediate
+  
+  def test_08_JMP
+    source = [
+      "     JMP   x",
+      "     JMP  #0",
+      "x    DAT #0, #0",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal 2, pc.next
+
+    instr = mem.fetch(1)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+  
+  # JMZ tests
+  #     JMZ x y should set the program counter to x if y is 0
+  #     JMP #x y is an error -- the operand can't be immediate
+  
+  def test_09_JMZ
+    source = [
+      "     JMZ   x, #1",
+      "     JMZ   x, #0",
+      "     JMZ  #0, #0",
+      "x    DAT  #0, #0",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 1, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 3, loc     # branch taken
+
+    instr = mem.fetch(2)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+
+  # JMN tests -- same as JMZ, but branch on non-zero
+  
+  def test_10_JMN
+    source = [
+      "     JMN   x, #0",
+      "     JMN   x, #1",
+      "     JMN  #0, #0",
+      "x    DAT  #0, #0",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 1, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 3, loc     # branch taken
+
+    instr = mem.fetch(2)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+
+  # DJN combines auto-decrement processing with a branch instruction.  As with
+  # other branches, immediate mode is not allowed for the A operand.
+  
+  def test_11_DJN
+    source = [
+      "     DJN   y, x",    # first won't branch
+      "     DJN   y, x",    # ...but second one will
+      "     DJN  #0, #0",
+      "x    DAT  #0, #1",
+      "y    MOV   0,  1",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 1, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 4, loc     # branch taken
+
+    instr = mem.fetch(2)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+
+  # CMP fetches the two operands and compares them; if they're the same
+  # the next instruction is skipped.
+  
+  def test_12_CMP
+    source = [
+      "     CMP   #1, x",    # don't skip
+      "     CMP   #0, x",    # skip
+      "     DAT   #0, #0",
+      "     CMP   x,  y",    # don't skip
+      "     CMP   x,  x",    # skip
+      "     DAT   #0, #0",
+      "     CMP   x,  #0",   # illegal
+      "x    DAT  #0,  #0",
+      "y    DAT  #0,  #1",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 1, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 3, loc     # branch taken
+
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 4, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 6, loc     # branch taken
+
+    instr = mem.fetch(loc)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+
+  # In our implementation SLT only works for immediate A operands.  Skip the
+  # next instruction if A is less than the A-field of the dereferenced B operand.
+  
+  def test_13_SLT
+    source = [
+      "     SLT   #3, x",    # don't skip
+      "     SLT   #1, x",    # skip
+      "     SLT   #0, #0",   # illegal B operand
+      "     SLT   #0, z",    # don't skip when operands equal
+      "x    DAT   #2",       # expect to stop here
+      "z    DAT   #0",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 1, loc     # branch not taken
+    
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 3, loc     # branch taken
+
+    instr = mem.fetch(loc)
+    assert_equal :continue, instr.execute(pc, mem)
+    loc = pc.next
+    assert_equal 4, loc     # branch not taken
+
+    instr = mem.fetch(2)
+    assert_raise(MARSRuntimeException) { instr.execute(pc, mem) }
+    
+  end	
+
+  # SPL forks a new thread that starts execution at the address specified by A.
+  # The pc object maintains a list of locations, with one location per thread.
+  # After the split in this test, the location list should have 2 items, one the
+  # continuation of the original thread and the other the first instruction in
+  # the new thread.
+  
+  def test_14_SPL
+    source = [
+      "     SPL   x",
+      "     DAT   #0, #0",    # space filler
+      "     DAT   #0, #0",
+      "x    MOV   0,  1",
+    ]
+    
+    mem, pc = make_machine(source)
+    
+    instr = mem.fetch(pc.next)
+    assert_equal :continue, instr.execute(pc, mem)
+    assert_equal [1,3], pc.addrs
+    
+  end	
+  
+  # The program counter object should have a history of memory references for each
+  # thread.  pc.history[i] is the history vector for thread i
+  
+  def test_15_threads
+    source = [
+      "     MOV   x, y",      # should log source and target references
+      "     SPL   z",         # start new thread
+      "     ADD   x, y",      # first thread logs two memory references
+      "     DAT   #0",        # first thread halts
+      "z    SUB   x, y",      # second thread logs two memory references
+      "     DAT   #0",        # second thread halts
+      "x    DAT   #1",
+      "y    DAT   #0",
+    ]
+    
+    mem, pc = make_machine(source)
+    assert_equal 1, pc.history.length
+    assert_equal [], pc.history[0]
+    
+    mem.fetch(pc.next).execute(pc, mem)
+    assert_equal [0,6,7], pc.history[0]     # log has instr and both operands
+    
+    mem.fetch(pc.next).execute(pc, mem)
+    assert_equal 2, pc.history.length       # SPL instruction makes new thread and history vector
+    assert_equal [0,6,7,1], pc.history[0]
+    
+    mem.fetch(pc.next).execute(pc, mem)
+    assert_equal [0,6,7,1,2,6,7], pc.history[0]     # staying with thread 0, add also logs both operands
+
+    mem.fetch(pc.next).execute(pc, mem)
+    assert_equal [4,6,7], pc.history[1]             # next instr comes from thread 1, sub logs both operands
+
+    assert_equal :halt, mem.fetch(pc.next).execute(pc, mem)   # back to thread 0, DAT halts the thread
+    assert_equal [0,6,7,1,2,6,7,3], pc.history[0]             # DAT is logged
+    assert_equal 1, pc.kill_thread                            # zap this thread, expect other one still there
+    assert_equal [4,6,7], pc.history[0]                       # other thread is now thread 0
+    
+    assert_equal :halt, mem.fetch(pc.next).execute(pc, mem)   # it also executes a DAT
+    assert_equal [4,6,7,5], pc.history[0]
+    assert_equal 0, pc.kill_thread
+    
+    assert_equal "DAT #0 #1", mem.fetch(7).to_s     # y set to 1, inc to 2 by thread 0, set back to 1 by thread 1
+  end
+  
+  # The Warrior class constructor takes a file name or a symbol corresponding to one
+  # of the built-in test programs.  The program is assembled, and all the relevant
+  # information saved with the object.
+  
+  def test_16_warrior_class
+    w = Warrior.new(:imp)
+    assert_equal "Imp", w.name
+    assert_equal [ Word.new("MOV","0","1") ], w.code
+    assert_equal 0, w.symbols[:start]
+  end
+
+end
+
+# Set up and initialize a mini-machine that has the assembled instructions
+# in array a loaded into memory, and a program counter set up to fetch
+# the first instruction.
+
+def make_machine(a, n = a.length)
+  mem = Memory.new(n)
+  name, code, symbols, errors = MARS.assemble(a)
+  code.each_with_index do |x, i|
+    mem.store(i, x)
+  end
+  pc = PC.new(name, 0)
+  return mem, pc
+end	
+

data/test/random_test.rb

@@ -4,37 +4,86 @@ require 'test_helper'
 include RandomLab
 
 class TestRandoms < Test::Unit::TestCase
+  
+  # The prng_sequence method makes a sequence of numbers using a linear congruential
+  # method with the specified a, c, and m values
+  
+  def test_01_prng_sequence
+    sched8 = prng_sequence(1, 8, 12)
+    assert_equal 12, sched8.length
+    assert_equal 3, sched8.uniq.length
+    
+    sched7 = prng_sequence(1, 7, 12)
+    assert_equal 12, sched7.length
+    assert_equal 12, sched7.uniq.length
+    
+    seq1 = prng_sequence(3, 337, 1000)
+    assert_equal [0, 337, 348, 381], seq1[0..3]
+    assert_equal 100, seq1.uniq.length
+    
+    seq2 = prng_sequence(81, 337, 1000)
+    assert_equal [0, 337, 634, 691], seq2[0..3]
+    assert_equal 1000, seq2.uniq.length
+  end
+  
+  # A PRNG object generates the same sequence of values as the prng_sequence method,
+  # but makes them on demand.  Test the sequence, test resetting the seed, test again.
+  # Also tests the random(n,m) method, which maps a sequence value to n..m
+  
+  def test_02_PRNG
+    p = PRNG.new(81, 337, 1000)
+    assert_equal 0, p.state
+    assert_equal 337, p.advance
+    assert_equal 634, p.advance
+    
+    p.seed(0)
+    assert_equal 0, p.state
+    assert_equal 337, p.advance
+    assert_equal 634, p.advance
+
+    p.seed(0)
+    assert_equal 2, p.random(1,6)     #  (337 % 6) + 1
+    assert_equal 5, p.random(1,6)     #  (634 % 6) + 1
+  end
 
   # For the Card tests, a call to the Card constructor with an integer argument 
   # makes a specified card, starting with 0 = A ♠ and ending with 51 = 2 ♣.
+  
+  def test_03_cards
+    c1 = Card.new(0)
+    assert_equal :ace, c1.rank
+    assert_equal :spades, c1.suit
+    
+    c2 = Card.new(51)
+    assert_equal :two, c2.rank
+    assert_equal :clubs, c2.suit
+  end
 
   # Make a full deck, make sure every card is present.  Then shuffle the deck,
   # check again.  Sort the shuffled deck, make sure all cards are there and in
   # order.
   
-  def test_01_decks
-    deck1 = deal((0..51).to_a)
-    check_all_cards(deck1)
-    deck2 = shuffle
-    check_all_cards(deck2)
-    deck3 = deck2.sort
-    check_all_cards(deck3)
-    assert_equal deck1, deck3
+  def test_04_deck
+    d = new_deck
+    check_all_cards(d)
+    permute(d)
+    check_all_cards(d)
+    d.sort!
+    assert_equal new_deck, d
   end
   
   # Make one of each kind of poker hand.  
   
-  def test_02_poker_hands
-    print "\n  poker hands"
-    assert_equal poker_hand(deal([0,1,2,3,4])),     :straight_flush
-    assert_equal poker_hand(deal([0,13,26,39,1])),  :four_of_a_kind
-    assert_equal poker_hand(deal([0,13,26,1,14])),  :full_house
-    assert_equal poker_hand(deal([0,2,4,6,8])),     :flush
-    assert_equal poker_hand(deal([0,14,2,3,4])),    :straight
-    assert_equal poker_hand(deal([0,13,26,1,15])),  :three_of_a_kind
-    assert_equal poker_hand(deal([0,13,1,14,15])),  :two_pair
-    assert_equal poker_hand(deal([0,13,1,2,3])),    :pair
-    assert_equal poker_hand(deal([0,14,29,44,45])), :nada
+  def test_05_poker_ranks
+    assert_equal poker_rank(deal([0,1,2,3,4])),     :straight_flush
+    assert_equal poker_rank(deal([0,13,26,39,1])),  :four_of_a_kind
+    assert_equal poker_rank(deal([0,13,26,1,14])),  :full_house
+    assert_equal poker_rank(deal([0,2,4,6,8])),     :flush
+    assert_equal poker_rank(deal([0,14,2,3,4])),    :straight
+    assert_equal poker_rank(deal([0,13,26,1,15])),  :three_of_a_kind
+    assert_equal poker_rank(deal([0,13,1,14,15])),  :two_pair
+    assert_equal poker_rank(deal([0,13,1,2,3])),    :pair
+    assert_equal poker_rank(deal([0,14,29,44,45])), :high_card
   end
 
   
@@ -43,6 +92,9 @@ class TestRandoms < Test::Unit::TestCase
   and initialized with a count of 0.
   
   +check_all_cards+ makes sure there are 13 of each suit and 4 of each rank. 
+  
+  +deal(a)+ maps all ints in +a+ into the corresponding Card (used to create
+  a known hand for testing poker ranks)
 =end
 
   def bins(a)
@@ -60,5 +112,9 @@ class TestRandoms < Test::Unit::TestCase
     rb.each { |x,n| assert_equal n, 4 }
     sb.each { |x,n| assert_equal n, 13 }
   end
+  
+  def deal(a)
+    return a.map { |x| Card.new(x) }
+  end
 
 end