core/combinators/short-circuit/short-circuit-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math quotations ;
   4 IN: combinators.short-circuit
   5
   6 HELP: 0&&
   7 { $values { "quots" "a sequence of quotations with stack effect " { $snippet "( -- ? )" } } { "?" "the result of the last quotation, or " { $link f } } }
   8 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
   9
  10 HELP: 0||
  11 { $values { "quots" "a sequence of quotations with stack effect " { $snippet "( -- ? )" } } { "?" "the first true result, or " { $link f } } }
  12 { $description "If every quotation in the sequence outputs " { $link f } ", outputs " { $link f } ", otherwise outputs the result of the first quotation that did not yield " { $link f } "." } ;
  13
  14 HELP: 1&&
  15 { $values { "obj" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj -- ? )" } } { "?" "the result of the last quotation, or " { $link f } } }
  16 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
  17
  18 HELP: 1||
  19 { $values { "obj" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj -- ? )" } } { "?" "the first true result, or " { $link f } } }
  20 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same element from the datastack and must return a boolean." } ;
  21
  22 HELP: 2&&
  23 { $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 -- ? )" } } { "?" "the result of the last quotation, or " { $link f } } }
  24 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
  25
  26 HELP: 2||
  27 { $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 -- ? )" } } { "?" "the first true result, or " { $link f } } }
  28 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same two elements from the datastack and must return a boolean." } ;
  29
  30 HELP: 3&&
  31 { $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 obj3 -- ? )" } } { "?" "the result of the last quotation, or " { $link f } } }
  32 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
  33
  34 HELP: 3||
  35 { $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 obj3 -- ? )" } } { "?" "the first true result, or " { $link f } } }
  36 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same three elements from the datastack and must return a boolean." } ;
  37
  38 HELP: n&&
  39 { $values
  40     { "quots" "a sequence of quotations" } { "n" integer }
  41     { "quot" quotation } }
  42 { $description "A macro that rewrites the code to pass " { $snippet "n" } " parameters from the stack to each quotation, evaluating the result in the same manner as " { $link 0&& } "." } ;
  43
  44 HELP: n||
  45 { $values
  46     { "quots" "a sequence of quotations" } { "n" integer }
  47     { "quot" quotation } }
  48 { $description "A macro that rewrites the code to pass " { $snippet "n" } " parameters from the stack to each OR quotation." } ;
  49
  50 ARTICLE: "combinators.short-circuit" "Short-circuit combinators"
  51 "The " { $vocab-link "combinators.short-circuit" } " vocabulary stops a computation early once a condition is met." $nl
  52 "AND combinators:"
  53 { $subsections
  54     0&&
  55     1&&
  56     2&&
  57     3&&
  58 }
  59 "OR combinators:"
  60 { $subsections
  61     0||
  62     1||
  63     2||
  64     3||
  65 }
  66 "Generalized combinators:"
  67 { $subsections
  68     n&&
  69     n||
  70 }
  71 ;
  72
  73 ABOUT: "combinators.short-circuit"