From b54b36af8f21c82a8f0a99efb0d979267aa43e6f Mon Sep 17 00:00:00 2001 From: Lukas Rytz Date: Thu, 26 Aug 2010 14:35:02 +0000 Subject: documentation for scala.xml.pull, contribution ... documentation for scala.xml.pull, contribution by Dave Copeland. close #3786, no review. --- src/library/scala/xml/pull/XMLEvent.scala | 42 +++++++++++++++++++------ src/library/scala/xml/pull/XMLEventReader.scala | 22 +++---------- src/library/scala/xml/pull/package.scala | 41 ++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 28 deletions(-) create mode 100644 src/library/scala/xml/pull/package.scala (limited to 'src') 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 `foo`. + * @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 `foo`. + * @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 ``, the target would + * be `foo` + * @param text the remainder of the instruction. For the instruction ``, 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 } -/**

- * A pull parser that offers to view an XML document as a series of events. - * Example usage: - * 

- *  import scala.xml.pull._
- *  import scala.io.Source
- *
- *  object reader {
- *    val src = Source.fromString("")
- *    val er = new XMLEventReader(src)
- *
- *    def main(args: Array[String]) {
- *      while (er.hasNext)
- *        Console.println(er.next)
- *    }
- *  }
- *
+/** + * 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(""" + * + * + * ]>Hello&bar;>""") + * + * 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 -- cgit v1.2.3