diff options
author | Lukas Rytz <lukas.rytz@epfl.ch> | 2010-08-26 14:35:02 +0000 |
---|---|---|
committer | Lukas Rytz <lukas.rytz@epfl.ch> | 2010-08-26 14:35:02 +0000 |
commit | b54b36af8f21c82a8f0a99efb0d979267aa43e6f (patch) | |
tree | c93d75eaa2ae9136d24f20842a5d9c110829a3b2 | |
parent | e73fa382cc72c054f1dcab2d9525fe4cc0eedda1 (diff) | |
download | scala-b54b36af8f21c82a8f0a99efb0d979267aa43e6f.tar.gz scala-b54b36af8f21c82a8f0a99efb0d979267aa43e6f.tar.bz2 scala-b54b36af8f21c82a8f0a99efb0d979267aa43e6f.zip |
documentation for scala.xml.pull, contribution ...
documentation for scala.xml.pull, contribution by Dave Copeland. close
#3786, no review.
-rw-r--r-- | src/library/scala/xml/pull/XMLEvent.scala | 42 | ||||
-rw-r--r-- | src/library/scala/xml/pull/XMLEventReader.scala | 22 | ||||
-rw-r--r-- | src/library/scala/xml/pull/package.scala | 41 |
3 files changed, 77 insertions, 28 deletions
diff --git a/src/library/scala/xml/pull/XMLEvent.scala b/src/library/scala/xml/pull/XMLEvent.scala index 3de618e3a7..255bf3b8a8 100644 --- a/src/library/scala/xml/pull/XMLEvent.scala +++ b/src/library/scala/xml/pull/XMLEvent.scala @@ -11,27 +11,49 @@ package scala.xml package pull -/** This class represents an XML event for pull parsing. - * Pull parsing means that during the traversal of the XML - * tree we are parsing, each "event" is returned to the caller - * and the traversal is suspended. +/** An XML event for pull parsing. All events received during + * parsing will be one of the subclasses of this trait. */ trait XMLEvent -/** An element is encountered the first time */ +/** + * An Element's start tag was encountered. + * @param pre prefix, if any, on the element. This is the `xs` in `<xs:string>foo</xs:string>`. + * @param label the name of the element, not including the prefix + * @param attrs any attributes on the element + */ case class EvElemStart(pre: String, label: String, attrs: MetaData, scope: NamespaceBinding) extends XMLEvent -/** An element is encountered the last time */ +/** + * An Element's end tag was encountered. + * @param pre prefix, if any, on the element. This is the `xs` in `<xs:string>foo</xs:string>`. + * @param label the name of the element, not including the prefix + */ case class EvElemEnd(pre: String, label: String) extends XMLEvent -/** A text node is encountered */ +/** + * A text node was encountered. + * @param text the text that was found + */ case class EvText(text: String) extends XMLEvent -/** An entity reference is encountered */ +/** An entity reference was encountered. + * @param the name of the entity, e.g. `gt` when encountering the entity `>` + */ case class EvEntityRef(entity: String) extends XMLEvent -/** A processing instruction is encountered */ +/** + * A processing instruction was encountered. + * @param target the "PITarget" of the processing instruction. For the instruction `<?foo bar="baz"?>`, the target would + * be `foo` + * @param text the remainder of the instruction. For the instruction `<?foo bar="baz"?>`, the text would + * be `bar="baz"` + * @see [[http://www.w3.org/TR/REC-xml/#sec-pi]] + */ case class EvProcInstr(target: String, text: String) extends XMLEvent -/** A comment is encountered */ +/** + * A comment was encountered + * @param text the text of the comment + */ case class EvComment(text: String) extends XMLEvent diff --git a/src/library/scala/xml/pull/XMLEventReader.scala b/src/library/scala/xml/pull/XMLEventReader.scala index 90c19f9c0b..fa428a440f 100644 --- a/src/library/scala/xml/pull/XMLEventReader.scala +++ b/src/library/scala/xml/pull/XMLEventReader.scala @@ -16,28 +16,14 @@ import java.nio.channels.ClosedChannelException import scala.io.Source import scala.xml.parsing.{ ExternalSources, MarkupHandler, MarkupParser } -/** <p> - * A pull parser that offers to view an XML document as a series of events. - * Example usage: - * </p><pre> - * <b>import</b> scala.xml.pull._ - * <b>import</b> scala.io.Source - * - * <b>object</b> reader { - * <b>val</b> src = Source.fromString("<hello><world/></hello>") - * <b>val</b> er = new XMLEventReader(src) - * - * <b>def</b> main(args: Array[String]) { - * while (er.hasNext) - * Console.println(er.next) - * } - * } - * </pre> +/** + * Main entry point into creating an event-based XML parser. Treating this + * as a [[scala.collection.Iterator]] will provide access to the generated events. + * @param src A [[scala.io.Source]] for XML data to parse * * @author Burak Emir * @author Paul Phillips */ - class XMLEventReader(src: Source) extends ProducerConsumerIterator[XMLEvent] { // We implement a pull parser as an iterator, but since we may be operating on diff --git a/src/library/scala/xml/pull/package.scala b/src/library/scala/xml/pull/package.scala new file mode 100644 index 0000000000..3742c55513 --- /dev/null +++ b/src/library/scala/xml/pull/package.scala @@ -0,0 +1,41 @@ +package scala.xml + +/** + * Classes needed to view an XML document as a series of events. The document + * is parsed by an [[scala.xml.pull.XMLEventReader]] instance. You can treat it as + * an [[scala.collection.Iterator]] to retrieve the events, which are all + * subclasses of [[scala.xml.pull.XMLEvent]]. + * + * {{{ + * scala> val source = Source.fromString("""<?xml version="1.0" encoding="UTF-8" standalone="yes"?> + * <?instruction custom value="customvalue"?> + * <!DOCTYPE foo [ + * <!ENTITY bar "BAR"> + * ]><foo>Hello<!-- this is a comment --><bar>&bar;</bar><bar>></bar></foo>""") + * + * source: scala.io.Source = non-empty iterator + * + * scala> val reader = new XMLEventReader(source) + * reader: scala.xml.pull.XMLEventReader = non-empty iterator + * + * scala> reader.foreach{ println(_) } + * EvProcInstr(instruction,custom value="customvalue") + * EvText( + * ) + * EvElemStart(null,foo,,) + * EvText(Hello) + * EvComment( this is a comment ) + * EvElemStart(null,bar,,) + * EvText(BAR) + * EvElemEnd(null,bar) + * EvElemStart(null,bar,,) + * EvEntityRef(gt) + * EvElemEnd(null,bar) + * EvElemEnd(null,foo) + * EvText( + * + * ) + * + * }}} + */ +package object pull |