Documenting read-dtd and friends; renaming sax to each-element

diff --git a/basis/xml/data/tags.txt b/basis/xml/data/tags.txt
new file mode 100644 (file)
index 0000000..2a50137
--- /dev/null
+++ b/basis/xml/data/tags.txt
@@ -0,0 +1,2 @@
+collections
+assocs

diff --git a/basis/xml/dispatch/authors.txt b/basis/xml/dispatch/authors.txt
new file mode 100644 (file)
index 0000000..f990dd0
--- /dev/null
+++ b/basis/xml/dispatch/authors.txt
@@ -0,0 +1 @@
+Daniel Ehrenberg

diff --git a/basis/xml/dispatch/summary.txt b/basis/xml/dispatch/summary.txt
new file mode 100644 (file)
index 0000000..6751e55
--- /dev/null
+++ b/basis/xml/dispatch/summary.txt
@@ -0,0 +1 @@
+'Generic words' that dispatch on XML tag names

diff --git a/basis/xml/dispatch/tags.txt b/basis/xml/dispatch/tags.txt
new file mode 100644 (file)
index 0000000..71c0ff7
--- /dev/null
+++ b/basis/xml/dispatch/tags.txt
@@ -0,0 +1 @@
+syntax

diff --git a/basis/xml/interpolate/summary.txt b/basis/xml/interpolate/summary.txt
new file mode 100644 (file)
index 0000000..7c18fc8
--- /dev/null
+++ b/basis/xml/interpolate/summary.txt
@@ -0,0 +1 @@
+Syntax for XML interpolation

diff --git a/basis/xml/interpolate/tags.txt b/basis/xml/interpolate/tags.txt
new file mode 100644 (file)
index 0000000..d236e96
--- /dev/null
+++ b/basis/xml/interpolate/tags.txt
@@ -0,0 +1,2 @@
+syntax
+enterprise

diff --git a/basis/xml/tests/test.factor b/basis/xml/tests/test.factor
index 99b660276cfb0efa916544f7722f2962a8420f88..bed729e300eba9f5c60f66e5332e933d65870bb9 100644 (file)
--- a/basis/xml/tests/test.factor
+++ b/basis/xml/tests/test.factor
@@ -8,7 +8,7 @@ sequences.deep accessors io.streams.string ;
 
 ! This is insufficient
 \ read-xml must-infer
-[ [ drop ] sax ] must-infer
+[ [ drop ] each-element ] must-infer
 \ string>xml must-infer
 
 SYMBOL: xml-file

diff --git a/basis/xml/utilities/tags.txt b/basis/xml/utilities/tags.txt
new file mode 100644 (file)
index 0000000..71c0ff7
--- /dev/null
+++ b/basis/xml/utilities/tags.txt
@@ -0,0 +1 @@
+syntax

diff --git a/basis/xml/xml-docs.factor b/basis/xml/xml-docs.factor
index 264a71c8e93a950fac380d4718379eb1a50c78fe..26d4319b5e8087954889311859555f16c21a81ae 100644 (file)
--- a/basis/xml/xml-docs.factor
+++ b/basis/xml/xml-docs.factor
@@ -1,66 +1,82 @@
 ! Copyright (C) 2005, 2009 Daniel Ehrenberg\r
 ! See http://factorcode.org/license.txt for BSD license.\r
-USING: help.markup help.syntax xml.data io ;\r
+USING: help.markup help.syntax xml.data io strings ;\r
 IN: xml\r
 \r
 HELP: string>xml\r
-{ $values { "string" "a string" } { "xml" "an xml document" } }\r
-{ $description "converts a string into an " { $link xml }\r
-    " datatype for further processing" } ;\r
+{ $values { "string" string } { "xml" xml } }\r
+{ $description "Converts a string into an " { $link xml }\r
+    " tree for further processing." } ;\r
 \r
 HELP: read-xml\r
-{ $values { "stream" "a stream that supports readln" }\r
-    { "xml" "an XML document" } }\r
-{ $description "exausts the given stream, reading an XML document from it. A binary stream, one without encoding, should be used as input, and the encoding is automatically detected." } ;\r
+{ $values { "stream" "an input stream" } { "xml" xml } }\r
+{ $description "Exausts the given stream, reading an XML document from it. A binary stream, one without encoding, should be used as input, and the encoding is automatically detected." } ;\r
 \r
 HELP: file>xml\r
-{ $values { "filename" "a string representing a filename" }\r
-    { "xml" "an XML document" } }\r
-{ $description "opens the given file, reads it in as XML, closes the file and returns the corresponding XML tree" } ;\r
+{ $values { "filename" string } { "xml" xml } }\r
+{ $description "Opens the given file, reads it in as XML, closes the file and returns the corresponding XML tree. The encoding is automatically detected." } ;\r
 \r
 { string>xml read-xml file>xml } related-words\r
 \r
 HELP: read-xml-chunk\r
 { $values { "stream" "an input stream" } { "seq" "a sequence of elements" } }\r
-{ $description "rather than parse a document, as " { $link read-xml } " does, this word parses and returns a sequence of XML elements (tags, strings, etc), ie a document fragment. This is useful for pieces of XML which may have more than one main tag." }\r
+{ $description "Rather than parse a document, as " { $link read-xml } " does, this word parses and returns a sequence of XML elements (tags, strings, etc), ie a document fragment. This is useful for pieces of XML which may have more than one main tag." }\r
 { $see-also read-xml } ;\r
 \r
-HELP: sax\r
+HELP: each-element\r
 { $values { "stream" "an input stream" } { "quot" "a quotation ( xml-elem -- )" } }\r
-{ $description "parses the XML document, and whenever an event is encountered (a tag piece, comment, parsing instruction, directive or string element), the quotation is called with that event on the stack. The quotation has all responsibility to deal with the event properly, and it is advised that generic words be used in dispatching on the event class." }\r
+{ $description "Parses the XML document, and whenever an event is encountered (a tag piece, comment, parsing instruction, directive or string element), the quotation is called with that event on the stack. The quotation has all responsibility to deal with the event properly, and it is advised that generic words be used in dispatching on the event class." }\r
 { $notes "It is important to note that this is not SAX, merely an event-based XML view" }\r
 { $see-also read-xml } ;\r
 \r
 HELP: pull-xml\r
-{ $class-description "represents the state of a pull-parser for XML. Has one slot, scope, which is a namespace which contains all relevant state information." }\r
+{ $class-description "Represents the state of a pull-parser for XML. Has one slot, scope, which is a namespace which contains all relevant state information." }\r
 { $see-also <pull-xml> pull-event pull-elem } ;\r
 \r
 HELP: <pull-xml>\r
 { $values { "pull-xml" "a pull-xml tuple" } }\r
-{ $description "creates an XML pull-based parser which reads from " { $link input-stream } ", executing all initial XML commands to set up the parser." }\r
+{ $description "Creates an XML pull-based parser which reads from " { $link input-stream } ", executing all initial XML commands to set up the parser." }\r
 { $see-also pull-xml pull-elem pull-event } ;\r
 \r
 HELP: pull-elem\r
 { $values { "pull" "an XML pull parser" } { "xml-elem/f" "an XML tag, string, or f" } }\r
-{ $description "gets the next XML element from the given XML pull parser. Returns f upon exhaustion." }\r
+{ $description "Gets the next XML element from the given XML pull parser. Returns f upon exhaustion." }\r
 { $see-also pull-xml <pull-xml> pull-event } ;\r
 \r
 HELP: pull-event\r
 { $values { "pull" "an XML pull parser" } { "xml-event/f" "an XML tag event, string, or f" } }\r
-{ $description "gets the next XML event from the given XML pull parser. Returns f upon exhaustion." }\r
+{ $description "Gets the next XML event from the given XML pull parser. Returns f upon exhaustion." }\r
 { $see-also pull-xml <pull-xml> pull-elem } ;\r
 \r
+HELP: read-dtd\r
+{ $values { "stream" "an input stream" } { "dtd" dtd } }\r
+{ $description "Exhausts a stream, producing a " { $link dtd } " from the contents." } ;\r
+\r
+HELP: file>dtd\r
+{ $values { "filename" string } { "dtd" dtd } }\r
+{ $description "Reads a file in UTF-8, converting it into an XML " { $link dtd } "." } ;\r
+\r
+HELP: string>dtd\r
+{ $values { "string" string } { "dtd" dtd } }\r
+{ $description "Interprets a string as an XML " { $link dtd } "." } ;\r
+\r
+{ read-dtd file>dtd string>dtd } related-words\r
+\r
 ARTICLE: { "xml" "reading" } "Reading XML"\r
     "The following words are used to read something into an XML document"\r
     { $subsection string>xml }\r
     { $subsection read-xml }\r
     { $subsection read-xml-chunk }\r
     { $subsection string>xml-chunk }\r
-    { $subsection file>xml } ;\r
+    { $subsection file>xml }\r
+    "To read a DTD:"\r
+    { $subsection read-dtd }\r
+    { $subsection file>dtd }\r
+    { $subsection string>dtd } ;\r
 \r
 ARTICLE: { "xml" "events" } "Event-based XML parsing"\r
     "In addition to DOM-style parsing based around " { $link read-xml } ", the XML module also provides SAX-style event-based parsing. This uses much of the same data structures as normal XML, with the exception of the classes " { $link xml } " and " { $link tag } " and as such, the article " { $vocab-link "xml.data" } " may be useful in learning how to process documents in this way. Other useful words are:"\r
-    { $subsection sax }\r
+    { $subsection each-element }\r
     { $subsection opener }\r
     { $subsection closer }\r
     { $subsection contained }\r

diff --git a/basis/xml/xml.factor b/basis/xml/xml.factor
index fdabbdc4df84690161e5032a74b2ea6460bec209..b043d5771ea175f16b5c761150dbb71510767df6 100644 (file)
--- a/basis/xml/xml.factor
+++ b/basis/xml/xml.factor
@@ -6,7 +6,7 @@ xml.data xml.errors xml.elements ascii xml.entities
 xml.writer xml.state xml.autoencoding assocs xml.tokenize xml.name ;
 IN: xml
 
-!   -- Overall parser with data tree
+<PRIVATE
 
 : add-child ( object -- )
     xml-stack get peek second push ;
@@ -89,6 +89,8 @@ M: closer process
 
 SYMBOL: text-now?
 
+PRIVATE>
+
 TUPLE: pull-xml scope ;
 : <pull-xml> ( -- pull-xml )
     [
@@ -106,6 +108,8 @@ TUPLE: pull-xml scope ;
         ] if text-now? set
     ] bind ;
 
+<PRIVATE
+
 : done? ( -- ? )
     xml-stack get length 1 = ;
 
@@ -116,27 +120,33 @@ TUPLE: pull-xml scope ;
         [ (pull-elem) ] if
     ] if ;
 
+PRIVATE>
+
 : pull-elem ( pull -- xml-elem/f )
     [ init-xml-stack (pull-elem) ] with-scope ;
 
+<PRIVATE
+
 : call-under ( quot object -- quot )
     swap dup slip ; inline
 
-: sax-loop ( quot: ( xml-elem -- ) -- )
+: xml-loop ( quot: ( xml-elem -- ) -- )
     parse-text call-under
-    get-char [ make-tag call-under sax-loop ]
+    get-char [ make-tag call-under xml-loop ]
     [ drop ] if ; inline recursive
 
-: sax ( stream quot: ( xml-elem -- ) -- )
+PRIVATE>
+
+: each-element ( stream quot: ( xml-elem -- ) -- )
     swap [
         reset-prolog init-ns-stack
         start-document [ call-under ] when*
-        sax-loop
-    ] with-state ; inline recursive
+        xml-loop
+    ] with-state ; inline
 
 : (read-xml) ( -- )
     start-document [ process ] when*
-    [ process ] sax-loop ; inline
+    [ process ] xml-loop ; inline
 
 : (read-xml-chunk) ( stream -- prolog seq )
     [
@@ -155,7 +165,8 @@ TUPLE: pull-xml scope ;
     [ (read-xml-chunk) nip ] with-variable ;
 
 : string>xml ( string -- xml )
-    <string-reader> read-xml ;
+    t string-input?
+    [ <string-reader> read-xml ] with-variable ;
 
 : string>xml-chunk ( string -- xml )
     t string-input?