basis/xml/data/data-docs.factor

   1 USING: help.markup help.syntax sequences strings ;
   2 IN: xml.data
   3
   4 ABOUT: "xml.data"
   5
   6 ARTICLE: "xml.data" "XML data types"
   7 "The " { $vocab-link "xml.data" } " vocabulary defines a simple document object model for XML. Everything is simply a tuple and can be manipulated as such."
   8 { $subsections
   9     { "xml.data" "classes" }
  10     { "xml.data" "constructors" }
  11 }
  12 "Simple words for manipulating names:"
  13 { $subsections
  14     names-match?
  15     assure-name
  16 }
  17 "For high-level tools for manipulating XML, see " { $vocab-link "xml.traversal" } ;
  18
  19 ARTICLE: { "xml.data" "classes" } "XML data classes"
  20 "XML documents and chunks are made of the following classes:"
  21 { $subsections
  22     xml
  23     xml-chunk
  24     tag
  25     name
  26     contained-tag
  27     open-tag
  28     prolog
  29     comment
  30     instruction
  31     unescaped
  32     element-decl
  33     attlist-decl
  34     entity-decl
  35     system-id
  36     public-id
  37     doctype-decl
  38     notation-decl
  39 } ;
  40
  41 ARTICLE: { "xml.data" "constructors" } "XML data constructors"
  42 "These data types are constructed with:"
  43 { $subsections
  44     <xml>
  45     <xml-chunk>
  46     <tag>
  47     <name>
  48     <contained-tag>
  49     <prolog>
  50     <comment>
  51     <instruction>
  52     <unescaped>
  53     <simple-name>
  54     <element-decl>
  55     <attlist-decl>
  56     <entity-decl>
  57     <system-id>
  58     <public-id>
  59     <doctype-decl>
  60     <notation-decl>
  61 } ;
  62
  63 HELP: tag
  64 { $class-description "Tuple representing an XML tag, delegating to a " { $link
  65 name } ", containing the slots attrs (an alist of names to strings) and children (a sequence). Tags implement the sequence protocol by acting like a sequence of its chidren, and the assoc protocol by acting like its attributes." }
  66 { $see-also <tag> name contained-tag xml } ;
  67
  68 HELP: <tag>
  69 { $values { "name" "an XML tag name" }
  70     { "attrs" "an alist of names to strings" }
  71     { "children" sequence }
  72     { "tag" tag } }
  73 { $description "Constructs an XML " { $link tag } " with the name (not a string) and tag attributes specified in attrs and children specified." }
  74 { $see-also tag <contained-tag> } ;
  75
  76 HELP: name
  77 { $class-description "Represents an XML name, with the fields space (a string representing the namespace, as written in the document, tag (a string of the actual name of the tag) and url (a string of the URL that the namespace points to)." }
  78 { $see-also <name> tag } ;
  79
  80 HELP: <name>
  81 { $values { "space" "a string" } { "main" "a string" } { "url" "a string" }
  82     { "name" "an XML tag name" } }
  83 { $description "Creates a name tuple with the namespace prefix space, the the given main part of the name, and the namespace URL given by url." }
  84 { $see-also name <tag> } ;
  85
  86 HELP: contained-tag
  87 { $class-description "This is a subclass of " { $link tag } " consisting of tags with no body, like " { $snippet "<a/>" } "." }
  88 { $see-also tag <contained-tag> } ;
  89
  90 HELP: <contained-tag>
  91 { $values { "name" "an XML tag name" }
  92     { "attrs" "an alist from names to strings" }
  93     { "tag" tag } }
  94 { $description "Creates an empty tag (like " { $snippet "<a/>" } ") with the specified name and tag attributes." }
  95 { $see-also contained-tag <tag> } ;
  96
  97 HELP: xml
  98 { $class-description "Tuple representing an XML document, delegating to the main tag, containing the fields prolog (the header " { $snippet "<?xml...?>" } "), before (whatever comes between the prolog and the main tag) and after (whatever comes after the main tag)." }
  99 { $see-also <xml> tag prolog } ;
 100
 101 HELP: <xml>
 102 { $values { "prolog" "an XML prolog" } { "before" "a sequence of XML elements" }
 103 { "body" tag } { "after" "a sequence of XML elements" } { "xml" "an XML document" } }
 104 { $description "Creates an XML document. The " { $snippet "before" } " and " { $snippet "after" } " slots store what comes before and after the main tag, and " { $snippet "body" } "contains the main tag itself." }
 105 { $see-also xml <tag> } ;
 106
 107 HELP: prolog
 108 { $class-description "represents an XML prolog, with the tuple fields version (containing \"1.0\" or \"1.1\"), encoding (a string representing the encoding type), and standalone (t or f, whether the document is standalone without external entities)" }
 109 { $see-also <prolog> xml } ;
 110
 111 HELP: <prolog>
 112 { $values { "version" "a string, 1.0 or 1.1" }
 113 { "encoding" "a string" } { "standalone" "a boolean" } { "prolog" "an XML prolog" } }
 114 { $description "Creates an XML prolog tuple." }
 115 { $see-also prolog <xml> } ;
 116
 117 HELP: comment
 118 { $class-description "Represents a comment in XML. This tuple has one slot, " { $snippet "text" } ", which contains the string of the comment." }
 119 { $see-also <comment> } ;
 120
 121 HELP: <comment>
 122 { $values { "text" string } { "comment" comment } }
 123 { $description "Creates an XML " { $link comment } " tuple." }
 124 { $see-also comment } ;
 125
 126 HELP: instruction
 127 { $class-description "Represents an XML instruction, such as " { $snippet "<?xsl stylesheet='foo.xml'?>" } ". Contains one slot, " { $snippet "text" } ", which contains the string between the question marks." }
 128 { $see-also <instruction> } ;
 129
 130 HELP: <instruction>
 131 { $values { "text" "a string" } { "instruction" "an XML instruction" } }
 132 { $description "Creates an XML parsing instruction, like " { $snippet "<?xsl stylesheet='foo.xml'?>" } "." }
 133 { $see-also instruction } ;
 134
 135 HELP: opener
 136 { $class-description "Describes an opening tag, like " { $snippet "<a>" } ". Contains two slots, " { $snippet "name" } " and " { $snippet "attrs" } " containing, respectively, the name of the tag and its attributes." } ;
 137
 138 HELP: closer
 139 { $class-description "Describes a closing tag, like " { $snippet "</a>" } ". Contains one slot, " { $snippet "name" } ", containing the closer's name." } ;
 140
 141 HELP: contained
 142 { $class-description "Represents a self-closing tag, like " { $snippet "<a/>" } ". Contains two slots, " { $snippet "name" } " and " { $snippet "attrs" } " containing, respectively, the name of the tag and its attributes." } ;
 143
 144 { opener closer contained } related-words
 145
 146 HELP: open-tag
 147 { $class-description "Represents a tag that does have children, ie. is not a contained tag" }
 148 { $notes "The constructor used for this class is simply " { $link <tag> } "." }
 149 { $see-also tag contained-tag } ;
 150
 151 HELP: names-match?
 152 { $values { "name1" "a name" } { "name2" "a name" } { "?" "t or f" } }
 153 { $description "Checks to see if the two names match, that is, if all fields are equal, ignoring fields whose value is f in either name." }
 154 { $example "USING: prettyprint xml.data ;" "T{ name f \"rpc\" \"methodCall\" f } T{ name f f \"methodCall\" \"http://www.xmlrpc.org/\" } names-match? ." "t" }
 155 { $see-also name } ;
 156
 157 HELP: assure-name
 158 { $values { "string/name" "a string or a name" } { "name" "a name" } }
 159 { $description "Converts a string into an XML name, if it is not already a name." } ;
 160
 161 HELP: <simple-name>
 162 { $values { "string" string } { "name" name } }
 163 { $description "Converts a string into an XML name with an empty prefix and URL." } ;
 164
 165 HELP: element-decl
 166 { $class-description "Describes the class of element declarations, like <!ELEMENT  greeting (#PCDATA)>." } ;
 167
 168 HELP: <element-decl>
 169 { $values { "name" name } { "content-spec" string } { "element-decl" entity-decl } }
 170 { $description "Creates an element declaration object, of the class " { $link element-decl } } ;
 171
 172 HELP: attlist-decl
 173 { $class-description "Describes the class of element declarations, like " { $snippet "<!ATTLIST pre xml:space (preserve) #FIXED 'preserve'>" } "." } ;
 174
 175 HELP: <attlist-decl>
 176 { $values { "name" name } { "att-defs" string } { "attlist-decl" attlist-decl } }
 177 { $description "Creates an element declaration object, of the class " { $link attlist-decl } } ;
 178
 179 HELP: entity-decl
 180 { $class-description "Describes the class of element declarations, like " { $snippet "<!ENTITY foo 'bar'>" } "." } ;
 181
 182 HELP: <entity-decl>
 183 { $values { "name" name } { "def" string } { "pe?" "t or f" } { "entity-decl" entity-decl } }
 184 { $description "Creates an entity declaration object, of the class " { $link entity-decl } ". The pe? slot should be t if the object is a DTD-internal entity, like " { $snippet "<!ENTITY % foo 'bar'>" } " and f if the object is like " { $snippet "<!ENTITY foo 'bar'>" } ", that is, it can be used outside of the DTD." } ;
 185
 186 HELP: system-id
 187 { $class-description "Describes the class of system identifiers within an XML DTD directive, such as " { $snippet "<!DOCTYPE greeting " { $emphasis "SYSTEM 'hello.dtd'" } ">" } "." } ;
 188
 189 HELP: <system-id>
 190 { $values { "system-literal" string } { "system-id" system-id } }
 191 { $description "Constructs a " { $link system-id } " tuple." } ;
 192
 193 HELP: public-id
 194 { $class-description "Describes the class of public identifiers within an XML DTD directive, such as " { $snippet "<!DOCTYPE open-hatch " { $emphasis "PUBLIC '-//Textuality//TEXT Standard open-hatch boilerplate//EN' 'http://www.textuality.com/boilerplate/OpenHatch.xml'" } ">" } } ;
 195
 196 HELP: <public-id>
 197 { $values { "pubid-literal" string } { "system-literal" string } { "public-id" public-id } }
 198 { $description "Constructs a " { $link system-id } " tuple." } ;
 199
 200 HELP: notation-decl
 201 { $class-description "Describes the class of element declarations, like " { $snippet "<!NOTATION jpg SYSTEM './jpgviewer'>" } "." } ;
 202
 203 HELP: <notation-decl>
 204 { $values { "name" string } { "id" string } { "notation-decl" notation-decl } }
 205 { $description "Creates an notation declaration object, of the class " { $link notation-decl } "." } ;
 206
 207 HELP: doctype-decl
 208 { $class-description "Describes the class of doctype declarations." } ;
 209
 210 HELP: <doctype-decl>
 211 { $values { "name" name } { "external-id" id } { "internal-subset" sequence } { "doctype-decl" doctype-decl } }
 212 { $description "Creates a new doctype declaration object, of the class " { $link doctype-decl } ". Only one of external-id or internal-subset will be non-null." } ;
 213
 214 HELP: unescaped
 215 { $class-description "When constructing XML documents to write to output, it can be useful to splice in a string which is already written. This tuple type allows for that. Printing an " { $snippet "unescaped" } " is the same is printing its " { $snippet "string" } " slot." } ;
 216
 217 HELP: <unescaped>
 218 { $values { "string" string } { "unescaped" unescaped } }
 219 { $description "Constructs an " { $link unescaped } " tuple, given a string." } ;
 220
 221 HELP: xml-chunk
 222 { $class-description "Encapsulates a balanced fragment of an XML document. This is a sequence (following the sequence protocol) of XML data types, eg " { $link string } "s and " { $link tag } "s." } ;
 223
 224 HELP: <xml-chunk>
 225 { $values { "seq" sequence } { "xml-chunk" xml-chunk } }
 226 { $description "Constructs an " { $link xml-chunk } " tuple, given a sequence to be its contents." } ;