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 preceded 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 "/* comment */" }
  10 { $description "Provides C-like comments that can span multiple lines. One caveat is that " { $snippet "/*" } " and " { $snippet "*/" } " are still tokens and must not appear in the comment text itself. Another caveat is that, unlike in C, the whitespace space after the " { $snippet "/*" } " is mandatory." }
  11 { $examples
  12     { $example "USING: multiline ;"
  13            "/* I think that I shall never see"
  14            "   A poem lovely as a tree. */"
  15             ""
  16     }
  17 } ;
  18
  19 HELP: HEREDOC:
  20 { $syntax "HEREDOC: marker\n...text...\nmarker" }
  21 { $values { "marker" "a word (token)" } { "text" "arbitrary text" } { "value" string } }
  22 { $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 " { $link POSTPONE: HEREDOC: } " until the end of the line containing " { $link POSTPONE: HEREDOC: } ". Text is captured until a line is found containing exactly this delimiter string." }
  23 { $warning "Whitespace is significant." }
  24 { $examples
  25     { $example "USING: multiline prettyprint ;"
  26                "HEREDOC: END\nx\nEND\n."
  27                "\"x\\n\""
  28     }
  29     { $example "USING: multiline prettyprint sequences ;"
  30                "2 5 HEREDOC: zap\nfoo\nbar\nzap\nsubseq ."
  31                "\"o\\nb\""
  32     }
  33 } ;
  34
  35 HELP: parse-multiline-string
  36 { $values { "end-text" "a string delineating the end" } { "str" "the parsed string" } }
  37 { $description "Parses the input stream until the " { $snippet "end-text" } " is reached and returns the parsed text as a string." }
  38 { $notes "Used to implement " { $link POSTPONE: /* } "." } ;
  39
  40 ARTICLE: "multiline" "Multiline"
  41 "Multiline strings:"
  42 { $subsections
  43     POSTPONE: STRING:
  44     POSTPONE: HEREDOC:
  45 }
  46 "Multiline comments:"
  47 { $subsections POSTPONE: /* }
  48 "Writing new multiline parsing words:"
  49 { $subsections parse-multiline-string }
  50 ;
  51
  52 ABOUT: "multiline"