basis/xml/interpolate/interpolate-docs.factor

   1 USING: help.markup help.syntax present multiline ;
   2 IN: xml.interpolate
   3
   4 ABOUT: "xml.interpolate"
   5
   6 ARTICLE: "xml.interpolate" "XML literal interpolation"
   7 "The " { $vocab-link "xml.interpolate" } " vocabulary provides a convenient syntax for generating XML documents and chunks. It defines the following parsing words:"
   8 { $subsection POSTPONE: <XML }
   9 { $subsection POSTPONE: [XML }
  10 "For a description of the common syntax of these two, see"
  11 { $subsection { "xml.interpolate" "in-depth" } } ;
  12
  13 HELP: <XML
  14 { $syntax "<XML <?xml version=\"1.0\"?><document>...</document> XML>" }
  15 { $description "This syntax allows the interpolation of XML documents. When evaluated, there is an XML document on the stack. For more information about XML interpolation, see " { $link { "xml.interpolate" "in-depth" } } "." } ;
  16
  17 HELP: [XML
  18 { $syntax "[XML foo <x>...</x> bar <y>...</y> baz XML]" }
  19 { $description "This syntax allows the interpolation of XML chunks. When evaluated, there is a sequence of XML elements (tags, strings, comments, etc) on the stack. For more information about XML interpolation, see " { $link { "xml.interpolate" "in-depth" } } "." } ;
  20
  21 ARTICLE: { "xml.interpolate" "in-depth" } "XML interpolation syntax"
  22 "XML interpolation has two forms for each of the words " { $link POSTPONE: <XML } " and " { $link POSTPONE: [XML } ": a fry-like form and a locals form. To splice locals in, use the syntax " { $snippet "<-variable->" } ". To splice something in from the stack, in the style of " { $vocab-link "fry" } ", use the syntax " { $snippet "<->" } ". An XML interpolation form may only use one of these styles."
  23 $nl
  24 "These forms can be used where a tag might go, as in " { $snippet "[XML <foo><-></foo> XML]" } " or where an attribute might go, as in " { $snippet "[XML <foo bar=<->/> XML]" } ". When an attribute is spliced in, it is not included if the value is " { $snippet "f" } " and if the value is not a string, the value is put through " { $link present } ". Here is an example of the fry style of XML interpolation:"
  25 { $example
  26 {" USING: splitting sequences xml.writer xml.interpolate ;
  27 "one two three" " " split
  28 [ [XML <item><-></item> XML] ] map
  29 <XML <doc><-></doc> XML> pprint-xml"}
  30 {" <?xml version="1.0" encoding="UTF-8"?>
  31 <doc>
  32   <item>
  33     one
  34   </item>
  35   <item>
  36     two
  37   </item>
  38   <item>
  39     three
  40   </item>
  41 </doc>"} }
  42 "Here is an example of the locals version:"
  43 { $example
  44 {" USING: locals urls xml.interpolate xml.writer ;
  45 [let |
  46     number [ 3 ]
  47     false [ f ]
  48     url [ URL" http://factorcode.org/" ]
  49     string [ "hello" ]
  50     word [ \ drop ] |
  51     <XML
  52         <x
  53             number=<-number->
  54             false=<-false->
  55             url=<-url->
  56             string=<-string->
  57             word=<-word-> />
  58     XML> pprint-xml ] "}
  59 {" <?xml version="1.0" encoding="UTF-8"?>
  60 <x number="3" url="http://factorcode.org/" string="hello" word="drop"/>"} } ;