Add documentation for poker vocab

diff --git a/extra/poker/poker-docs.factor b/extra/poker/poker-docs.factor
new file mode 100644 (file)
index 0000000..09019a2
--- /dev/null
+++ b/extra/poker/poker-docs.factor
@@ -0,0 +1,30 @@
+USING: help.markup help.syntax strings ;
+IN: poker
+
+HELP: <hand>
+{ $values { "str" string } { "hand" "a new hand" } }
+{ $description "Creates a new poker hand containing the cards specified in " { $snippet "str" } "." }
+{ $examples
+    { $example "USING: kernel math.order poker prettyprint ;"
+        "\"AC KC QC JC TC\" \"7C 6D 5H 4S 2C\" [ <hand> ] bi@ <=> ." "+lt+" }
+    { $example "USING: kernel poker prettyprint ;"
+        "\"TC 9C 8C 7C 6C\" \"TH 9H 8H 7H 6H\" [ <hand> ] bi@ = ." "t" }
+}
+{ $notes "Cards may be specified in any order. Hands are directly comparable to each other on the basis of their computed value. Two hands are considered equal when they would tie in a game (despite being composed of different cards)." } ;
+
+HELP: >cards
+{ $values { "hand" "a hand" } { "str" string } }
+{ $description "Outputs a string representation of a hand's cards." }
+{ $examples
+    { $example "USING: poker prettyprint ;"
+        "\"AC KC QC JC TC\" <hand> >cards ." "\"AC KC QC JC TC\"" }
+} ;
+
+HELP: >value
+{ $values { "hand" "a hand" } { "str" string } }
+{ $description "Outputs a string representation of a hand's value." }
+{ $examples
+    { $example "USING: poker prettyprint ;"
+        "\"AC KC QC JC TC\" <hand> >value ." "\"Straight Flush\"" }
+}
+{ $notes "This should not be used as a basis for hand comparison." } ;

diff --git a/extra/poker/poker.factor b/extra/poker/poker.factor
index ca999dbf6e6036f6bee5c0181e9b87de1930033e..2a7fe73762e6fdcd501b20d6fccc0b10b29a66be 100644 (file)
--- a/extra/poker/poker.factor
+++ b/extra/poker/poker.factor
@@ -155,20 +155,6 @@ CONSTANT: VALUE_STR { "" "Straight Flush" "Four of a Kind" "Full House" "Flush"
         [ drop "S" ]
     } cond ;
 
-PRIVATE>
-
-TUPLE: hand
-    { cards sequence }
-    { value integer } ;
-
-M: hand <=> [ value>> ] compare ;
-M: hand equal?
-    over hand? [ [ value>> ] bi@ = ] [ 2drop f ] if ;
-
-: <hand> ( str -- hand )
-    " " split [ >ckf ] map
-    dup hand-value hand boa ;
-
 : hand-rank ( hand -- rank )
     value>> {
         { [ dup 6185 > ] [ drop HIGH_CARD ] }        ! 1277 high card
@@ -182,10 +168,24 @@ M: hand equal?
         [ drop STRAIGHT_FLUSH ]                      !   10 straight-flushes
     } cond ;
 
-: >value ( hand -- str )
-    hand-rank VALUE_STR nth ;
+PRIVATE>
+
+TUPLE: hand
+    { cards sequence }
+    { value integer } ;
+
+M: hand <=> [ value>> ] compare ;
+M: hand equal?
+    over hand? [ [ value>> ] bi@ = ] [ 2drop f ] if ;
+
+: <hand> ( str -- hand )
+    " " split [ >ckf ] map
+    dup hand-value hand boa ;
 
 : >cards ( hand -- str )
     cards>> [
         [ >card-rank ] [ >card-suit ] bi append
     ] map " " join ;
+
+: >value ( hand -- str )
+    hand-rank VALUE_STR nth ;