basis/inverse/inverse-docs.factor

   1 USING: help.markup help.syntax kernel quotations words ;
   2 IN: inverse
   3
   4 HELP: [undo]
   5 { $values { "quot" quotation } { "undo" "the inverse of the quotation" } }
   6 { $description "Creates the inverse of the given quotation" }
   7 { $see-also undo } ;
   8
   9 HELP: undo
  10 { $values { "quot" quotation } }
  11 { $description "Executes the inverse of the given quotation" }
  12 { $see-also [undo] } ;
  13
  14 HELP: define-inverse
  15 { $values { "word" word } { "quot" "the inverse" } }
  16 { $description "Defines the inverse of a given word, taking no arguments from the quotation, only the stack." }
  17 { $see-also define-dual define-involution define-pop-inverse } ;
  18
  19 HELP: define-dual
  20 { $values { "word1" word } { "word2" word } }
  21 { $description "Defines the inverse of each word as being the other one." }
  22 { $see-also define-inverse define-involution } ;
  23
  24 HELP: define-involution
  25 { $values { "word" word } }
  26 { $description "Defines a word as being its own inverse." }
  27 { $see-also define-dual define-inverse } ;
  28
  29 HELP: define-pop-inverse
  30 { $values { "word" word } { "n" "number of arguments to be taken from the inverted quotation" } { "quot" quotation } }
  31 { $description "Defines the inverse of the given word, taking the given number of arguments from the inverted quotation. The quotation given should generate an inverse quotation." }
  32 { $see-also define-inverse } ;
  33
  34 HELP: matches?
  35 { $values { "quot" quotation } { "?" boolean } }
  36 { $description "Tests if the stack can match the given quotation. The quotation is inverted, and if the inverse can run without a unification failure, then t is returned. Else f is returned. If a different error is encountered (such as stack underflow), this will be propagated." } ;
  37
  38 HELP: switch
  39 { $values { "quot-alist" "an alist from inverse quots to quots" } }
  40 { $description "The equivalent of a case expression in a programming language with buitlin pattern matchining. It attempts to match the stack with each of the patterns, in order, by treating them as inverse quotations. Failure causes the next pattern to be tested." }
  41 { $code
  42 "TUPLE: cons car cdr ;"
  43 "C: <cons> cons"
  44 ": sum ( list -- sum )"
  45 "    {"
  46 "        { [ <cons> ] [ sum + ] }"
  47 "        { [ f ] [ 0 ] }"
  48 "    } switch ;" }
  49 { $see-also undo } ;
  50
  51 ARTICLE: { "inverse" "intro" } "Invertible quotations"
  52 "The inverse vocab defines a way to 'undo' quotations, and builds a pattern matching framework on that basis. A quotation can be inverted by reversing it and inverting each word. To define the inverse for particular word, use"
  53 { $subsections
  54     define-inverse
  55     define-pop-inverse
  56 }
  57 "To build an inverse quotation"
  58 { $subsections [undo] }
  59 "To use the inverse quotation for pattern matching"
  60 { $subsections
  61     undo
  62     matches?
  63     switch
  64 } ;
  65
  66 IN: inverse
  67 ABOUT: { "inverse" "intro" }