basis/combinators/random/random-docs.factor

   1 ! Copyright (C) 2010 Jon Harper.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: assocs help.markup help.syntax kernel quotations
   4 combinators.random.private sequences ;
   5 IN: combinators.random
   6
   7 HELP: call-random
   8 { $values { "seq" "a sequence of quotations" } }
   9 { $description "Calls a random quotation from the given sequence of quotations." } ;
  10
  11 HELP: execute-random
  12 { $values { "seq" "a sequence of words" } }
  13 { $description "Executes a random word from the given sequence of quotations." } ;
  14
  15 HELP: ifp
  16 { $values
  17     { "p" "a number between 0 and 1" } { "true" quotation } { "false" quotation }
  18 }
  19 { $description "Calls the " { $snippet "true" } " quotation with probability " { $snippet "p" }
  20 " and the " { $snippet "false" } " quotation with probability (1-" { $snippet "p" } ")." } ;
  21
  22 HELP: casep
  23 { $values
  24     { "assoc" "a sequence of probability/quotations pairs with an optional quotation at the end" }
  25 }
  26 { $description "Calls the different quotations randomly with the given probability. The optional quotation at the end "
  27 "will be given a probability so that the sum of the probabilities is one. Therefore, the sum of the probabilities "
  28 "must be exactly one when no default quotation is given, or between zero and one when it is given. "
  29 "Additionally, all probabilities must be numbers between 0 and 1. "
  30 "These rules are enforced during the macro expansion by throwing " { $link bad-probabilities } " "
  31 "if they are not respected." }
  32 { $examples
  33     "The following two forms will output 1 with 0.2 probability, 2 with 0.3 probability and 3 with 0.5 probability"
  34     { $code
  35         "USING: combinators.random ;"
  36         "{ { 0.2 [ 1 ] }"
  37         "  { 0.3 [ 2 ] }"
  38         "  { 0.5 [ 3 ] } } casep ."
  39     }
  40     $nl
  41     { $code
  42         "USING: combinators.random ;"
  43         "{ { 0.2 [ 1 ] }"
  44         "  { 0.3 [ 2 ] }"
  45         "  { [ 3 ] } } casep ."
  46     }
  47
  48 }
  49
  50 { $see-also casep* } ;
  51
  52 HELP: casep*
  53 { $values
  54     { "assoc" "a sequence of probability/word pairs with an optional quotation at the end" }
  55 }
  56 { $description "Calls the different quotations randomly with the given probability. Unlike " { $link casep } ", "
  57 "the probabilities are interpreted as conditional probabilities. "
  58 "All probabilities must be numbers between 0 and 1. "
  59 "The sequence must end with a pair whose probability is one, or a quotation."
  60 "These rules are enforced during the macro expansion by throwing " { $link bad-probabilities } " "
  61 "if they are not respected." }
  62 { $examples
  63     "The following two forms will output 1 with 0.5 probability, 2 with 0.25 probability and 3 with 0.25 probability"
  64     { $code
  65         "USING: combinators.random ;"
  66         "{ { 0.5 [ 1 ] }"
  67         "  { 0.5 [ 2 ] }"
  68         "  { 1 [ 3 ] } } casep* ."
  69     }
  70     $nl
  71     { $code
  72         "USING: combinators.random ;"
  73         "{ { 0.5 [ 1 ] }"
  74         "  { 0.5 [ 2 ] }"
  75         "  { [ 3 ] } } casep* ."
  76     }
  77
  78 }
  79 { $see-also casep } ;
  80
  81 HELP: unlessp
  82 { $values
  83     { "p" "a number between 0 and 1" } { "false" quotation }
  84 }
  85 { $description "Variant of " { $link ifp } " with no " { $snippet "true" } " quotation." } ;
  86
  87 HELP: whenp
  88 { $values
  89     { "p" "a number between 0 and 1" } { "true" quotation }
  90 }
  91 { $description "Variant of " { $link ifp } " with no " { $snippet "false" } " quotation." } ;
  92
  93 ARTICLE: "combinators.random" "Random combinators"
  94 "The " { $vocab-link "combinators.random" } " vocabulary implements simple combinators to easily express random choices"
  95 " between multiple code paths."
  96 $nl
  97 "For all these combinators, the stack effect of the different given quotations or words must be the same."
  98 $nl
  99 "Variants of if, when and unless:"
 100 { $subsections
 101     ifp
 102     whenp
 103     unlessp }
 104 "Variants of case:"
 105 { $subsections
 106     casep
 107     casep*
 108     call-random
 109     execute-random
 110 } ;
 111
 112 ABOUT: "combinators.random"