basis/match/match-docs.factor

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax namespaces assocs
   4 kernel combinators ;
   5 IN: match
   6
   7 HELP: match
   8 { $values { "value1" object } { "value2" object } { "bindings" assoc }
   9 }
  10 { $description "Pattern match " { $snippet "value1" } " against " { $snippet "value2" } ". These values can be any Factor value, including sequences and tuples. The values can contain pattern variables, which are symbols that begin with '?'. The result is a hashtable of the bindings, mapping the pattern variables from one sequence to the equivalent value in the other sequence. The " { $link _ } " symbol can be used to ignore the value at that point in the pattern for the match." }
  11 { $examples
  12     { $unchecked-example "USE: match" "MATCH-VARS: ?a ?b ;\n{ ?a { 2 ?b } 5 } { 1 { 2 3 } _ } match ." "H{ { ?a 1 } { ?b 3 } }" }
  13 }
  14 { $see-also match-cond POSTPONE: MATCH-VARS: replace-patterns match-replace } ;
  15
  16 HELP: match-cond
  17 { $values { "assoc" "a sequence of pairs" } }
  18 { $description "Calls the second quotation in the first pair whose first sequence yields a successful " { $link match } " against the top of the stack. The second quotation, when called, has the hashtable returned from the " { $link match } " call bound as the top namespace so " { $link get } " can be used to retrieve the values. A single quotation will always yield a true value. To have a fallthrough match clause use the " { $link _ } " match variable." }
  19 { $errors "Throws a " { $link no-match-cond } " error if none of the test quotations yield a true value." }
  20 { $examples
  21     { $code
  22         "USE: match" "MATCH-VARS: ?value ;\n{ increment 346126 } {\n  { { increment ?value } [ ?value do-something ] }\n  { { decrement ?value } [ ?value do-something-else ] }\n  { _ [ no-match-found ] }\n} match-cond" }
  23 }
  24 { $see-also match POSTPONE: MATCH-VARS: replace-patterns match-replace } ;
  25
  26 HELP: MATCH-VARS:
  27 { $syntax "MATCH-VARS: var ... ;" }
  28 { $values { "var" "a match variable name beginning with '?'" } }
  29 { $description "Creates a symbol that can be used in " { $link match } " and " { $link match-cond } " for binding values in the matched sequence. The symbol name is created as a word that is defined to get the value of the symbol out of the current namespace. This can be used in " { $link match-cond } " to retrive the values in the quotation body." }
  30 { $examples
  31     { $code "USE: match" "MATCH-VARS: ?value ;\n{ increment 346126 } {\n  { { increment ?value } [ ?value do-something ] }\n  { { decrement ?value } [ ?value do-something-else ] }\n  { _ [ no-match-found ] }\n} match-cond" }
  32 }
  33 { $see-also match match-cond replace-patterns match-replace } ;
  34
  35 HELP: replace-patterns
  36 { $values { "object" object } { "result" object } }
  37 { $description "Copy the object, replacing each occurrence of a pattern matching variable with the actual value of that variable." }
  38 { $see-also match-cond POSTPONE: MATCH-VARS: match-replace } ;
  39
  40 HELP: match-replace
  41 { $values { "object" object } { "pattern1" object } { "pattern2" object } { "result" object } }
  42 { $description "Matches the " { $snippet "object" } " against " { $snippet "pattern1" } ". The pattern match variables in " { $snippet "pattern1" } " are assigned the values from the matching " { $snippet "object" } ". These are then replaced into the " { $snippet "pattern2" } " pattern match variables." }
  43 { $examples
  44   { $example
  45       "USING: match prettyprint ;"
  46       "IN: scratchpad"
  47       "MATCH-VARS: ?a ?b ;"
  48       "{ 1 2 } { ?a ?b } { ?b ?a } match-replace ."
  49       "{ 2 1 }"
  50   }
  51 }
  52 { $see-also match-cond POSTPONE: MATCH-VARS: } ;
  53
  54 ARTICLE: "match" "Pattern matching"
  55 "The " { $vocab-link "match" } " vocabulary implements ML-style pattern matching."
  56 $nl
  57 "Variables used for pattern matching must be explicitly defined first:"
  58 { $subsections POSTPONE: MATCH-VARS: }
  59 "A basic pattern match:"
  60 { $subsections match }
  61 "A conditional form analogous to " { $link cond } ":"
  62 { $subsections match-cond }
  63 "Pattern replacement:"
  64 { $subsections match-replace } ;
  65
  66 ABOUT: "match"