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 sequences
   4 kernel combinators ;
   5 IN: match
   6
   7 HELP: match
   8 { $values { "value1" object } { "value2" object } { "bindings" assoc }
   9 }
  10 { $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. " }
  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. To have a fallthrough match clause use the '_' match variable." }
  19 { $examples
  20     { $code "USE: match" "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" }
  21 }
  22 { $see-also match POSTPONE: MATCH-VARS: replace-patterns match-replace } ;
  23
  24
  25 HELP: MATCH-VARS:
  26 { $syntax "MATCH-VARS: var ... ;" }
  27 { $values { "var" "a match variable name beginning with '?'" } }
  28 { $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." }
  29 { $examples
  30     { $code "USE: match" "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" }
  31 }
  32 { $see-also match match-cond replace-patterns match-replace } ;
  33
  34 HELP: replace-patterns
  35 { $values { "object" object } { "result" object } }
  36 { $description "Copy the object, replacing each occurrence of a pattern matching variable with the actual value of that variable." }
  37 { $see-also match-cond POSTPONE: MATCH-VARS: match-replace } ;
  38
  39 HELP: match-replace
  40 { $values { "object" object } { "pattern1" object } { "pattern2" object } { "result" object } }
  41 { $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." }
  42 { $examples
  43   { $example
  44       "USING: match prettyprint ;"
  45       "IN: scratchpad"
  46       "MATCH-VARS: ?a ?b ;"
  47       "{ 1 2 } { ?a ?b } { ?b ?a } match-replace ."
  48       "{ 2 1 }"
  49   }
  50 }
  51 { $see-also match-cond POSTPONE: MATCH-VARS: } ;
  52
  53 ARTICLE: "match" "Pattern matching"
  54 "The " { $vocab-link "match" } " vocabulary implements ML-style pattern matching."
  55 $nl
  56 "Variables used for pattern matching must be explicitly defined first:"
  57 { $subsection POSTPONE: MATCH-VARS: }
  58 "A basic pattern match:"
  59 { $subsection match }
  60 "A conditional form analogous to " { $link cond } ":"
  61 { $subsection match-cond }
  62 "Pattern replacement:"
  63 { $subsection match-replace } ;
  64
  65 ABOUT: "match"