basis/xml/syntax/syntax-docs.factor

   1 ! Copyright (C) 2005, 2009 Daniel Ehrenberg
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax xml.data present ;
   4 IN: xml.syntax
   5
   6 ABOUT: "xml.syntax"
   7
   8 ARTICLE: "xml.syntax" "Syntax extensions for XML"
   9 "The " { $link "xml.syntax" } " vocabulary defines a number of new parsing words for XML processing."
  10 { $subsections
  11     { "xml.syntax" "tags" }
  12     { "xml.syntax" "literals" }
  13     POSTPONE: XML-NS:
  14 } ;
  15
  16 ARTICLE: { "xml.syntax" "tags" } "Dispatch on XML tag names"
  17 "There is a system, analogous to generic words, for processing XML. A word can dispatch off the name of the tag that is passed to it. To define such a word, use"
  18 { $subsections POSTPONE: TAGS: }
  19 "and to define a new 'method' for this word, use"
  20 { $subsections POSTPONE: TAG: } ;
  21
  22 HELP: TAGS:
  23 { $syntax "TAGS: word" }
  24 { $values { "word" "a new word to define" } }
  25 { $description "Creates a new word to which dispatches on XML tag names." }
  26 { $see-also POSTPONE: TAG: } ;
  27
  28 HELP: TAG:
  29 { $syntax "TAG: tag word definition... ;" }
  30 { $values { "tag" "an XML tag name" } { "word" "an XML process" } }
  31 { $description "Defines a 'method' on a word created with " { $link POSTPONE: TAGS: } ". It determines what such a word should do for an argument that is has the given name." }
  32 { $examples { $code "TAGS: x ( tag -- )\nTAG: a x drop \"hi\" write ;" } }
  33 { $see-also POSTPONE: TAGS: } ;
  34
  35 ARTICLE: { "xml.syntax" "literals" } "XML literals"
  36 "The following words provide syntax for XML literals:"
  37 { $subsections
  38     POSTPONE: <XML
  39     POSTPONE: [XML
  40 }
  41 "These can be used for creating an XML literal, which can be used with variables or a fry-like syntax to interpolate data into XML."
  42 { $subsections { "xml.syntax" "interpolation" } } ;
  43
  44 HELP: <XML
  45 { $syntax "<XML <?xml version=\"1.0\"?><document>...</document> XML>" }
  46 { $description "This gives syntax for literal XML documents. When evaluated, there is an XML document (" { $link xml } ") on the stack. It can be used for interpolation as well, if interpolation slots are used. For more information about XML interpolation, see " { $link { "xml.syntax" "interpolation" } } "." } ;
  47
  48 HELP: [XML
  49 { $syntax "[XML foo <x>...</x> bar <y>...</y> baz XML]" }
  50 { $description "This gives syntax for literal XML documents. When evaluated, there is an XML chunk (" { $link xml-chunk } ") on the stack. For more information about XML interpolation, see " { $link { "xml.syntax" "interpolation" } } "." } ;
  51
  52 ARTICLE: { "xml.syntax" "interpolation" } "XML interpolation syntax"
  53 "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."
  54 $nl
  55 "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:"
  56 { $example
  57 """USING: splitting xml.writer xml.syntax ;
  58 "one two three" " " split
  59 [ [XML <item><-></item> XML] ] map
  60 <XML <doc><-></doc> XML> pprint-xml"""
  61
  62 """<?xml version="1.0" encoding="UTF-8"?>
  63 <doc>
  64   <item>
  65     one
  66   </item>
  67   <item>
  68     two
  69   </item>
  70   <item>
  71     three
  72   </item>
  73 </doc>""" }
  74 "Here is an example of the locals version:"
  75 { $example
  76 """USING: locals urls xml.syntax xml.writer ;
  77 [let
  78     3 :> number
  79     f :> false
  80     URL" http://factorcode.org/" :> url
  81     "hello" :> string
  82     \\ drop :> word
  83     <XML
  84         <x
  85             number=<-number->
  86             false=<-false->
  87             url=<-url->
  88             string=<-string->
  89             word=<-word-> />
  90     XML> pprint-xml
  91 ]"""
  92
  93 """<?xml version="1.0" encoding="UTF-8"?>
  94 <x number="3" url="http://factorcode.org/" string="hello" word="drop"/>""" }
  95 "XML interpolation can also be used, in conjunction with " { $vocab-link "inverse" } " in pattern matching. For example:"
  96 { $example """USING: xml.syntax inverse ;
  97 : dispatch ( xml -- string )
  98     {
  99         { [ [XML <a><-></a> XML] ] [ "a" prepend ] }
 100         { [ [XML <b><-></b> XML] ] [ "b" prepend ] }
 101         { [ [XML <b val='yes'/> XML] ] [ "yes" ] }
 102         { [ [XML <b val=<->/> XML] ] [ "no" prepend ] }
 103     } switch ;
 104 [XML <a>pple</a> XML] dispatch write"""
 105 "apple" } ;
 106
 107 HELP: XML-NS:
 108 { $syntax "XML-NS: name http://url" }
 109 { $description "Defines a new word of the given name which constructs XML names in the namespace of the given URL. The names constructed are memoized." } ;