From 48946a261df80bb1da8b8feac70b3a313b09b3fe Mon Sep 17 00:00:00 2001 From: michelou Date: Sun, 15 Oct 2006 09:38:04 +0000 Subject: added more comments in scala/xml/Utility.scala --- src/library/scala/xml/Utility.scala | 215 +++++++++++++++++++++++++----------- 1 file changed, 151 insertions(+), 64 deletions(-) (limited to 'src') diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala index dd189360cb..1041faa2aa 100644 --- a/src/library/scala/xml/Utility.scala +++ b/src/library/scala/xml/Utility.scala @@ -15,18 +15,31 @@ import compat.StringBuilder import collection.mutable.{Set, HashSet} /** - * Utility functions for processing instances of bound and - * not bound XML classes, as well as escaping text nodes. + * The Utility object provides utility functions for processing + * instances of bound and not bound XML classes, as well as escaping text nodes. + * + * @author Burak Emir */ object Utility extends AnyRef with parsing.TokenTests { def view(s: String): Text = Text(s) - /* escapes the characters < > & and " from string */ + /** + * Escapes the characters < > & and " from string. + * + * @param text ... + * @return ... + */ final def escape(text: String): String = escape(text, new StringBuilder()).toString() - /* appends escaped string to s */ + /** + * Appends escaped string to s. + * + * @param text ... + * @param s ... + * @return ... + */ final def escape(text: String, s: StringBuilder): StringBuilder = { for (val c <- Iterator.fromString(text)) c match { case '<' => s.append("<") @@ -39,8 +52,14 @@ object Utility extends AnyRef with parsing.TokenTests { s } - /* appends unescaped string to s, amp becomes & lt becomes < - * @returns null if ref was not a predefined entity + /** + * Appends unescaped string to s, amp becomes & + * lt becomes < etc.. + * + * @param ref ... + * @param s ... + * @return null if ref was not a predefined + * entity. */ final def unescape(ref: String, s: StringBuilder): StringBuilder = ref match { @@ -56,9 +75,9 @@ object Utility extends AnyRef with parsing.TokenTests { * Returns a set of all namespaces used in a sequence of nodes * and all their descendants, including the empty namespaces. * - * @param nodes + * @param nodes ... + * @return ... */ - def collectNamespaces(nodes: Seq[Node]): Set[String] = { var m = new HashSet[String]() val it = nodes.elements @@ -67,31 +86,43 @@ object Utility extends AnyRef with parsing.TokenTests { m } - /** adds all namespaces in node to set */ + /** + * Adds all namespaces in node to set. + * + * @param n ... + * @param set ... + */ def collectNamespaces(n: Node, set: Set[String]): Unit = { - if( n.typeTag$ >= 0 ) { - set += n.namespace; + if (n.typeTag$ >= 0) { + set += n.namespace for (val a <- n.attributes) a match { - case _:PrefixedAttribute => - set += a.getNamespace(n) - case _ => - } + case _:PrefixedAttribute => + set += a.getNamespace(n) + case _ => + } for (val i <- n.child) collectNamespaces(i, set); } } - /** string representation of an XML node, with comments stripped the comments + /** + * Returs the string representation of an XML node, with comments stripped + * the comments. + * + * @param n the XML node + * @return the string representation of node n. + * * @see "toXML(Node, Boolean)" */ - def toXML(n: Node): String = toXML(n, true); + def toXML(n: Node): String = toXML(n, true) /** - * String representation of a Node. uses namespace mapping from - * defaultPrefixes(n). + * Return the string representation of a Node. uses namespace mapping from + * defaultPrefixes(n). * - * @param n - * @param stripComment + * @param n the XML node + * @param stripComment ... + * @return ... * * @todo define a way to escape literal characters to &xx; references */ @@ -102,12 +133,13 @@ object Utility extends AnyRef with parsing.TokenTests { } - /** appends a tree to the given stringbuffer within given namespace scope. + /** + * Appends a tree to the given stringbuffer within given namespace scope. * - * @param n the node - * @param pscope the parent scope - * @param sb stringbuffer to append to - * @param stripComment if true, strip comments + * @param n the node + * @param pscope the parent scope + * @param sb stringbuffer to append to + * @param stripComment if true, strip comments */ def toXML(x: Node, pscope: NamespaceBinding, sb: StringBuilder, stripComment: Boolean): Unit = { x match { @@ -139,14 +171,21 @@ object Utility extends AnyRef with parsing.TokenTests { } } - def sequenceToXML(children: Seq[Node], pscope: NamespaceBinding, sb: StringBuilder, stripComment: Boolean): Unit = { - if(children.isEmpty) + /** + * @param children ... + * @param pscope ... + * @param sb ... + * @param stripComment ... + */ + def sequenceToXML(children: Seq[Node], pscope: NamespaceBinding, + sb: StringBuilder, stripComment: Boolean): Unit = { + if (children.isEmpty) return - else if(children forall { y => y.isInstanceOf[Atom[Any]] && !y.isInstanceOf[Text] }) { // add space + else if (children forall { y => y.isInstanceOf[Atom[Any]] && !y.isInstanceOf[Text] }) { // add space val it = children.elements val f = it.next toXML(f, f.scope, sb, stripComment) - while(it.hasNext) { + while (it.hasNext) { val x = it.next sb.append(' ') toXML(x, x.scope, sb, stripComment) @@ -156,8 +195,12 @@ object Utility extends AnyRef with parsing.TokenTests { } } - - /** returns prefix of qualified name if any */ + /** + * Returns prefix of qualified name if any. + * + * @param name ... + * @return ... + */ final def prefix(name: String): Option[String] = { val i = name.indexOf(':'.asInstanceOf[Int]) if( i != -1 ) Some( name.substring(0, i) ) else None @@ -191,33 +234,52 @@ object Utility extends AnyRef with parsing.TokenTests { } */ + /** + * @param s ... + * @return ... + */ def systemLiteralToString(s: String): String = { val sb = new StringBuilder() systemLiteralToString(sb, s) sb.toString() } + /** + * @param sb ... + * @param s ... + * @return ... + */ def systemLiteralToString(sb: StringBuilder, s: String): StringBuilder = { sb.append("SYSTEM ") appendQuoted(s, sb) } + /** + * @param s ... + * @return ... + */ def publicLiteralToString(s: String): String = { val sb = new StringBuilder() systemLiteralToString(sb, s) sb.toString() } + /** + * @param sb ... + * @param s ... + * @return ... + */ def publicLiteralToString(sb: StringBuilder, s: String): StringBuilder = { sb.append("PUBLIC \"").append(s).append('"') } /** - * Appends "s" if s does not contain ", 's' - * otherwise + * Appends "s" if string s does not contain ", + * 's' otherwise. * - * @param s - * @param sb + * @param s ... + * @param sb ... + * @return ... */ def appendQuoted(s: String, sb: StringBuilder) = { val ch = if (s.indexOf('"'.asInstanceOf[Int]) == -1) '"' else '\''; @@ -227,19 +289,25 @@ object Utility extends AnyRef with parsing.TokenTests { /** * Appends "s" and escapes and " i s with \" * - * @param s - * @param sb + * @param s ... + * @param sb ... + * @return ... */ def appendEscapedQuoted(s: String, sb: StringBuilder) = { sb.append('"') val z:Seq[Char] = Predef.string2seq(s) - for( val c <- z ) c match { + for (val c <- z) c match { case '"' => sb.append('\\'); sb.append('"') case _ => sb.append(c) } sb.append('"') } + /** + * @param s ... + * @param index ... + * @return ... + */ def getName(s: String, index: Int): String = { var i = index; val sb = new StringBuilder(); @@ -247,14 +315,20 @@ object Utility extends AnyRef with parsing.TokenTests { var c = s.charAt(i); if (isNameStart(s.charAt(i))) while (i < s.length() && { c = s.charAt(i); isNameChar(c)}) { - sb.append(c); + sb.append(c) i = i + 1 } sb.toString() } else null } - /** returns null if the value is a correct attribute value, error message if it isn't */ + /** + * Returns null if the value is a correct attribute value, + * error message if it isn't. + * + * @param value ... + * @return ... + */ def checkAttributeValue(value: String): String = { var i = 0 while (i < value.length()) { @@ -263,9 +337,9 @@ object Utility extends AnyRef with parsing.TokenTests { return "< not allowed in attribute value"; case '&' => val n = getName(value, i+1); - if (n== null) + if (n == null) return "malformed entity reference in attribute value ["+value+"]"; - i = i + n.length() + 1; + i = i + n.length() + 1 if (i >= value.length() || value.charAt(i) != ';') return "malformed entity reference in attribute value ["+value+"]"; case _ => @@ -275,15 +349,19 @@ object Utility extends AnyRef with parsing.TokenTests { null } - /** new + /** + * new + * + * @param value ... + * @return ... */ - def parseAttributeValue(value:String):Seq[Node] = { - val zs:Seq[Char] = value + def parseAttributeValue(value: String): Seq[Node] = { + val zs: Seq[Char] = value val sb = new StringBuilder var rfb: StringBuilder = null val nb = new NodeBuffer() val it = zs.elements - while(it.hasNext) { + while (it.hasNext) { var c = it.next c match { case '&' => // entity! flush buffer into text node @@ -294,10 +372,10 @@ object Utility extends AnyRef with parsing.TokenTests { sb.append(theChar) case x => - if(rfb==null) rfb = new StringBuilder() + if (rfb==null) rfb = new StringBuilder() rfb.append(x) c = it.next - while(c != ';') { + while (c != ';') { rfb.append(c) c = it.next } @@ -305,7 +383,7 @@ object Utility extends AnyRef with parsing.TokenTests { rfb.setLength(0) unescape(ref,sb) match { case null => - if(sb.length() > 0) { // flush buffer + if (sb.length() > 0) { // flush buffer nb += Text(sb.toString()) sb.setLength(0) } @@ -317,9 +395,9 @@ object Utility extends AnyRef with parsing.TokenTests { sb.append(x) } } - if(sb.length() > 0) { // flush buffer + if (sb.length() > 0) { // flush buffer val x = Text(sb.toString()) - if(nb.length == 0) + if (nb.length == 0) return x else nb += x @@ -327,30 +405,39 @@ object Utility extends AnyRef with parsing.TokenTests { return nb } - /** CharRef ::= "&#" '0'..'9' {'0'..'9'} ";" - * | "&#x" '0'..'9'|'A'..'F'|'a'..'f' { hexdigit } ";" + /** + * 
+   *   CharRef ::= "&#" '0'..'9' {'0'..'9'} ";"
+   *             | "&#x" '0'..'9'|'A'..'F'|'a'..'f' { hexdigit } ";"
+   *
+ *

+ * see [66] + *

* - * see [66] + * @param ch ... + * @param nextch ... + * @param reportSyntaxError ... + * @return ... */ def parseCharRef(ch: () => Char, nextch: () => Unit, reportSyntaxError:(String) => Unit): String = { - val hex = (ch() == 'x') && { nextch(); true }; - val base = if (hex) 16 else 10; - var i = 0; + val hex = (ch() == 'x') && { nextch(); true } + val base = if (hex) 16 else 10 + var i = 0 while (ch() != ';') { ch() match { case '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' => - i = i * base + Character.digit( ch(), base ); + i = i * base + Character.digit(ch(), base) case 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' => if (! hex) - reportSyntaxError("hex char not allowed in decimal char ref\n" - +"Did you mean to write &#x ?"); + reportSyntaxError("hex char not allowed in decimal char ref\n" + + "Did you mean to write &#x ?") else - i = i * base + Character.digit(ch(), base); + i = i * base + Character.digit(ch(), base) case _ => - reportSyntaxError("character '" + ch() + " not allowed in char ref\n"); + reportSyntaxError("character '" + ch() + " not allowed in char ref\n") } - nextch(); + nextch() } String.valueOf(i.asInstanceOf[char]) } -- cgit v1.2.3