libs/match/match.facts

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help match namespaces ;
   4
   5 HELP: match
   6 { $values { "value1" "an object" } { "value2" "an object" } { "bindings" "A hashtable" }
   7 }
   8 { $description "Pattern match value1 against 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 '_' symbol can be used to ignore the value at that point in the pattern for the match. " }
   9 { $examples
  10     { $example "MATCH-VARS: ?a ?b ;\n{ ?a { 2 ?b } 5 } { 1 { 2 3 } _ } match\n => H{ { ?a 1 } { ?b 3 } }" }
  11 }
  12 { $see-also match-cond POSTPONE: MATCH-VARS: } ;
  13
  14 HELP: match-cond
  15 { $values { "value" "an object" } { "assoc" "A sequence of quotation pairs" } }
  16 { $description "Calls the second quotation in the first pair whose first sequence yields a successful " { $link match } " against 'value'. 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. To have a fallthrough match clause use the '_' match variable." }
  17 { $examples
  18     { $example "MATCH-VARS: ?value ;\n{ increment ?value } {\n  { { increment ?value } [ ?value do-something ] }\n  { { decrement ?value } [ ?value do-something-else ] }\n  { _ [ no-match-found ] }\n} match-cond" }
  19 }
  20 { $see-also match POSTPONE: MATCH-VARS: } ;
  21
  22
  23 HELP: MATCH-VARS:
  24 { $syntax "MATCH-VARS: var ... ;" }
  25 { $values { "var" "a match variable name beginning with '?'" } }
  26 { $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." }
  27 { $examples
  28     { $example "MATCH-VARS: ?value ;\n{ increment ?value } {\n  { { increment ?value } [ ?value do-something ] }\n  { { decrement ?value } [ ?value do-something-else ] }\n  { _ [ no-match-found ] }\n} match-cond" }
  29 }
  30 { $see-also match match-cond } ;