extra/parser-combinators/replace/replace-docs.factor

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup parser-combinators
   4 parser-combinators.replace ;
   5
   6 HELP: tree-write
   7 { $values
   8   { "object" "an object" } }
   9 { $description
  10     "Write the object to the standard output stream, unless "
  11     "it is an array, in which case recurse through the array "
  12     "writing each object to the stream." }
  13 { $example "[ { 65 \"bc\" { 68 \"ef\" } } tree-write ] string-out ." "\"AbcDef\"" } ;
  14
  15 HELP: search
  16 { $values
  17   { "string" "a string" }
  18   { "parser" "a parser combinator based parser" }
  19   { "seq"    "a sequence" }
  20 }
  21 { $description
  22     "Returns a sequence containing the parse results of all substrings "
  23     "from the input string that successfully parse using the "
  24     "parser."
  25 }
  26
  27 { $example "\"one 123 two 456\" 'integer' search ." "{ 123 456 }" }
  28 { $example "\"one 123 \\\"hello\\\" two 456\" 'integer' 'string' <|> search ." "{ 123 \"hello\" 456 }" }
  29 { $see-also search* replace replace* } ;
  30
  31 HELP: search*
  32 { $values
  33   { "string" "a string" }
  34   { "parsers" "a sequence of parser combinator based parsers" }
  35   { "seq"    "a sequence" }
  36 }
  37 { $description
  38     "Returns a sequence containing the parse results of all substrings "
  39     "from the input string that successfully parse using any of the "
  40     "parsers in the 'parsers' sequence."
  41 }
  42
  43 { $example "\"one 123 \\\"hello\\\" two 456\" 'integer' 'string' 2array search* ." "{ 123 \"hello\" 456 }" }
  44 { $see-also search replace replace* } ;
  45
  46 HELP: replace
  47 { $values
  48   { "string" "a string" }
  49   { "parser" "a parser combinator based parser" }
  50   { "result"    "a string" }
  51 }
  52 { $description
  53     "Returns a copy of the original string but with all substrings that "
  54     "successfully parse with the given parser replaced with "
  55     "the result of that parser."
  56 }
  57 { $example "\"one 123 two 456\" 'integer' [ 2 * number>string ] <@ replace ." "\"one 246 two 912\"" }
  58 { $example "\"hello *world* from *factor*\" 'bold' [ \"<strong>\" swap \"</strong>\" 3append ] <@ replace ." "\"hello <strong>world</strong> from <strong>factor</strong>\"" }
  59 { $example "\"hello *world* from _factor_\"\n 'bold' [ \"<strong>\" swap \"</strong>\" 3append ] <@\n 'italic' [ \"<emphasis>\" swap \"</emphasis>\" 3append ] <@ <|>\n replace ." "\"hello <strong>world</strong> from <emphasis>factor</emphasis>\"" }
  60 { $see-also search search* replace* } ;
  61
  62 HELP: replace*
  63 { $values
  64   { "string" "a string" }
  65   { "parsers" "a sequence of parser combinator based parsers" }
  66   { "result"    "a string" }
  67 }
  68 { $description
  69     "Returns a copy of the original string but with all substrings that "
  70     "successfully parse with the given parsers replaced with "
  71     "the result of that parser. Each parser is done in sequence so that "
  72     "the parse results of the first parser can be replaced by later parsers."
  73 }
  74 { $example "\"*hello _world_*\"\n 'bold' [ \"<strong>\" swap \"</strong>\" 3append ] <@\n 'italic' [ \"<emphasis>\" swap \"</emphasis>\" 3append ] <@ 2array\n replace* ." "\"<strong>hello <emphasis>world</emphasis></strong>\"" }
  75 { $see-also search search* replace* } ;
  76