basis/combinators/random/random-docs.factor

   1 ! Copyright (C) 2010 Jon Harper.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays combinators.random.private help.markup help.syntax
   4 kernel math quotations random 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 prettyprint ;"
  36         "{"
  37         "    { 0.2 [ 1 ] }"
  38         "    { 0.3 [ 2 ] }"
  39         "    { 0.5 [ 3 ] }"
  40         "} casep ."
  41     }
  42     $nl
  43     { $code
  44         "USING: combinators.random prettyprint ;"
  45         "{"
  46         "    { 0.2 [ 1 ] }"
  47         "    { 0.3 [ 2 ] }"
  48         "    [ 3 ]"
  49         "} casep ."
  50     }
  51
  52 }
  53
  54 { $see-also casep* } ;
  55
  56 HELP: casep*
  57 { $values
  58     { "assoc" "a sequence of probability/word pairs with an optional quotation at the end" }
  59 }
  60 { $description "Calls the different quotations randomly with the given probability. Unlike " { $link casep } ", "
  61 "the probabilities are interpreted as conditional probabilities. "
  62 "All probabilities must be numbers between 0 and 1. "
  63 "The sequence must end with a pair whose probability is one, or a quotation."
  64 "These rules are enforced during the macro expansion by throwing " { $link bad-probabilities } " "
  65 "if they are not respected." }
  66 { $examples
  67     "The following two forms will output 1 with 0.5 probability, 2 with 0.25 probability and 3 with 0.25 probability"
  68     { $code
  69         "USING: combinators.random prettyprint ;"
  70         "{"
  71         "    { 0.5 [ 1 ] }"
  72         "    { 0.5 [ 2 ] }"
  73         "    { 1 [ 3 ] }"
  74         "} casep* ."
  75     }
  76     $nl
  77     { $code
  78         "USING: combinators.random prettyprint ;"
  79         "{"
  80         "    { 0.5 [ 1 ] }"
  81         "    { 0.5 [ 2 ] }"
  82         "    [ 3 ]"
  83         "} casep* ."
  84     }
  85
  86 }
  87 { $see-also casep } ;
  88
  89 HELP: unlessp
  90 { $values
  91     { "p" "a number between 0 and 1" } { "false" quotation }
  92 }
  93 { $description "Variant of " { $link ifp } " with no " { $snippet "true" } " quotation." } ;
  94
  95 HELP: whenp
  96 { $values
  97     { "p" "a number between 0 and 1" } { "true" quotation }
  98 }
  99 { $description "Variant of " { $link ifp } " with no " { $snippet "false" } " quotation." } ;
 100
 101 ARTICLE: "combinators.random" "Random combinators"
 102 "The " { $vocab-link "combinators.random" } " vocabulary implements simple combinators to easily express random choices"
 103 " between multiple code paths."
 104 $nl
 105 "For all these combinators, the stack effect of the different given quotations or words must be the same."
 106 $nl
 107 "Variants of if, when and unless:"
 108 { $subsections
 109     ifp
 110     whenp
 111     unlessp }
 112 "Variants of case:"
 113 { $subsections
 114     casep
 115     casep*
 116     call-random
 117     execute-random
 118 } ;
 119
 120 ABOUT: "combinators.random"