extra/backtrack/backtrack-docs.factor

   1 ! Copyright (c) 2009 Samuel Tardieu.
   2 ! See See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax quotations sequences ;
   4 IN: backtrack
   5
   6 HELP: fail
   7 { $description "Signal that the current alternative is not acceptable. This will cause either backtracking to occur, or a failure to be signalled, as explained in the " { $link amb } " word description." }
   8 { $see-also amb cut-amb }
   9 ;
  10
  11 HELP: amb
  12 { $values
  13   { "seq" "the alternatives" }
  14   { "elt" "one of the alternatives" }
  15 }
  16 { $description "The amb (ambiguous) word saves the state of the current computation (through the " { $vocab-link "continuations" } " vocabulary) and returns the first alternative. When " { $link fail } " is invoked, the saved state will be restored and the next alternative will be returned. When there are no more alternatives, " { $link fail } " will go up one level to the location of the previous " { $link amb } " call. If there are no more calls up the chain, an error will be signalled." }
  17 { $see-also fail cut-amb }
  18 ;
  19
  20 HELP: cut-amb
  21 { $description "Reset the amb system. Calling this word resets the whole stack of " { $link amb } " calls and should not be done lightly."}
  22 { $see-also amb fail }
  23 ;
  24
  25 HELP: amb-execute
  26 { $values
  27   { "seq" "a list of words" }
  28 }
  29 { $description "Execute the first word in the list, and go to the next one if " { $link fail } " is called." } ;
  30
  31 HELP: if-amb
  32 { $values
  33   { "true" { $quotation "( -- ? )" } }
  34   { "false" quotation }
  35   { "?" "a boolean" }
  36 }
  37 { $description "Execute the first quotation and returns " { $link t } " if it returns " { $link t } " itself. If it fails with " { $link fail } " or returns " { $link f } ", then the second quotation is executed and " { $link f } " is returned." } ;
  38
  39 HELP: amb-all
  40 { $values
  41   { "quot" { $quotation "( -- )" } }
  42 }
  43 { $description "Execute all the alternatives in the quotation by calling " { $link fail } " repeatedly at the end." }
  44 { $see-also bag-of fail }
  45 ;
  46
  47 HELP: bag-of
  48 { $values
  49   { "quot" { $quotation "( -- result )" } }
  50   { "seq" sequence }
  51 }
  52 { $description "Execute all the alternatives in the quotation and collect the results." }
  53 { $see-also amb-all } ;