basis/regexp/combinators/combinators-docs.factor

   1 ! Copyright (C) 2009 Daniel Ehrenberg
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup regexp strings ;
   4 IN: regexp.combinators
   5
   6 ABOUT: "regexp.combinators"
   7
   8 ARTICLE: "regexp.combinators.intro" "Regular expression combinator rationale"
   9 "Regular expression combinators are useful when part of the regular expression contains user input. For example, given a sequence of strings on the stack, a regular expression which matches any one of them can be constructed:"
  10 { $code
  11   "[ <literal> ] map <or>"
  12 }
  13 "Without combinators, a naive approach would look as follows:"
  14 { $code
  15   "\"|\" join <regexp>"
  16 }
  17 "However, this code is incorrect, because one of the strings in the sequence might contain characters which have special meaning inside a regular expression. Combinators avoid this problem by building a regular expression syntax tree directly, without any parsing." ;
  18
  19 ARTICLE: "regexp.combinators" "Regular expression combinators"
  20 "The " { $vocab-link "regexp.combinators" } " vocabulary defines combinators which can be used to build up regular expressions to match strings. This complements the traditional syntax defined in the " { $vocab-link "regexp" } " vocabulary."
  21 { $subsections "regexp.combinators.intro" }
  22 "Basic combinators:"
  23 { $subsections <literal> <nothing> }
  24 "Higher-order combinators for building new regular expressions from existing ones:"
  25 { $subsections
  26     <or>
  27     <and>
  28     <not>
  29     <sequence>
  30     <zero-or-more>
  31 }
  32 "Derived combinators implemented in terms of the above:"
  33 { $subsections <one-or-more> }
  34 "Setting options:"
  35 { $subsections <option> } ;
  36
  37 HELP: <literal>
  38 { $values { "string" string } { "regexp" regexp } }
  39 { $description "Creates a regular expression which matches the given literal string." } ;
  40
  41 HELP: <nothing>
  42 { $values { "value" regexp } }
  43 { $description "The empty regular language." } ;
  44
  45 HELP: <or>
  46 { $values { "regexps" "a sequence of regular expressions" } { "disjunction" regexp } }
  47 { $description "Creates a new regular expression which matches the union of what elements of the sequence match." } ;
  48
  49 HELP: <and>
  50 { $values { "regexps" "a sequence of regular expressions" } { "conjunction" regexp } }
  51 { $description "Creates a new regular expression which matches the intersection of what elements of the sequence match." } ;
  52
  53 HELP: <sequence>
  54 { $values { "regexps" "a sequence of regular expressions" } { "regexp" regexp } }
  55 { $description "Creates a new regular expression which matches strings that match each element of the sequence in order." } ;
  56
  57 HELP: <not>
  58 { $values { "regexp" regexp } { "not-regexp" regexp } }
  59 { $description "Creates a new regular expression which matches everything that the given regexp does not match." } ;
  60
  61 HELP: <one-or-more>
  62 { $values { "regexp" regexp } { "regexp+" regexp } }
  63 { $description "Creates a new regular expression which matches one or more copies of the given regexp." } ;
  64
  65 HELP: <option>
  66 { $values { "regexp" regexp } { "regexp?" regexp } }
  67 { $description "Creates a new regular expression which matches zero or one copies of the given regexp." } ;
  68
  69 HELP: <zero-or-more>
  70 { $values { "regexp" regexp } { "regexp*" regexp } }
  71 { $description "Creates a new regular expression which matches zero or more copies of the given regexp." } ;