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