basis/multiline/multiline-docs.factor

   1 USING: help.markup help.syntax strings ;
   2 IN: multiline
   3
   4 HELP: STRING:
   5 { $syntax "STRING: name\nfoo\n;" }
   6 { $description "Forms a multiline string literal, or 'here document' stored in the word called name. A semicolon is used to signify the end, and that semicolon must be on a line by itself, not preceeded or followed by any whitespace. The string will have newlines in between lines but not at the end, unless there is a blank line before the semicolon." } ;
   7
   8 HELP: <"
   9 { $syntax "<\" text \">" }
  10 { $description "This forms a multiline string literal ending in \">. Unlike the " { $link POSTPONE: STRING: } " form, you can end it in the middle of a line. This construct is non-nesting. In the example above, the string would be parsed as \"text\"." } ;
  11
  12 HELP: /*
  13 { $syntax "/* comment */" }
  14 { $description "Provides C-like comments that can span multiple lines. One caveat is that " { $snippet "/*" } " and " { $snippet "*/" } " are still tokens and must not abut the comment text itself." }
  15 { $example "USING: multiline ;"
  16            "/* I think that I shall never see"
  17            "   A poem lovely as a tree. */"
  18            ""
  19 } ;
  20
  21 HELP: HEREDOC:
  22 { $syntax "HEREDOC: marker\n...text...\nmarker" }
  23 { $values { "marker" "a word (token)" } { "text" "arbitrary text" } { "value" string } }
  24 { $description "Returns a string delimited by an arbitrary user-defined token. This delimiter must be exactly the text beginning at the first non-blank character after the " { $link POSTPONE: HEREDOC: } " until the end of the line containing the " { $link POSTPONE: HEREDOC: } ". Text is captured until a line is found conatining exactly this delimter string." }
  25 { $warning "Whitespace is significant." }
  26 { $examples
  27     { $example "USING: multiline prettyprint ;"
  28                "HEREDOC: END\nx\nEND\n."
  29                "\"x\\n\""
  30     }
  31     { $example "USING: multiline prettyprint sequences ;"
  32                "2 5 HEREDOC: zap\nfoo\nbar\nzap\nsubseq ."
  33                "\"o\\nb\""
  34     }
  35 } ;
  36
  37 HELP: DELIMITED:
  38 { $syntax "DELIMITED: marker\n...text...\nmarker" }
  39 { $values { "marker" "a word (token)" } { "text" "arbitrary text" } { "value" string } }
  40 { $description "Returns a string delimited by an arbitrary user-defined token. This delimiter must be exactly the text beginning at the first non-blank character after the " { $link POSTPONE: DELIMITED: } " until the end of the line containing the " { $link POSTPONE: DELIMITED: } ". Text is captured until the exact delimiter string is found, regardless of where." }
  41 { $examples
  42     { $example "USING: multiline prettyprint ;"
  43                "DELIMITED: factor blows my mind"
  44 "whoafactor blows my mind ."
  45                 "\"whoa\""
  46     }
  47 } ;
  48
  49 { POSTPONE: <" POSTPONE: STRING: } related-words
  50
  51 HELP: parse-multiline-string
  52 { $values { "end-text" "a string delineating the end" } { "str" "the parsed string" } }
  53 { $description "Parses the input stream until the " { $snippet "end-text" } " is reached and returns the parsed text as a string." }
  54 { $notes "Used to implement " { $link POSTPONE: /* } " and " { $link POSTPONE: <" } "." } ;
  55
  56 ARTICLE: "multiline" "Multiline"
  57 "Multiline strings:"
  58 { $subsection POSTPONE: STRING: }
  59 { $subsection POSTPONE: <" }
  60 { $subsection POSTPONE: HEREDOC: }
  61 { $subsection POSTPONE: DELIMITED: }
  62 "Multiline comments:"
  63 { $subsection POSTPONE: /* }
  64 "Writing new multiline parsing words:"
  65 { $subsection parse-multiline-string }
  66 ;
  67
  68 ABOUT: "multiline"