From: handa <handa>
Date: Mon, 7 Dec 2009 04:01:05 +0000 (+0000)
Subject: *** empty log message ***
X-Git-Url: http://git.chise.org/gitweb/?a=commitdiff_plain;h=ad9688b36b476f477e9a9aa6f2b3407b2c6b47bd;p=m17n%2Fm17n-lib-cs.git

*** empty log message ***
---

diff --git a/XmlExpr.cs b/XmlExpr.cs
index 08954e8..18de2ec 100644
--- a/XmlExpr.cs
+++ b/XmlExpr.cs
@@ -9,15 +9,14 @@ using System.Xml;
 
 namespace System.Xml
 {
+  /// <summary>
+  /// Static class to provide XmlExpression loader and evaluator.
+  /// </summary>
   public static class Xexpression
   {
-    private static int trace_depth = 0;
-
-    public static int TraceDepth {
-      get { return trace_depth; }
-      set { trace_depth = value; }
-    }
-
+    /// <summary>
+    /// Exception thrown while loading and evaluating XmlExpression.
+    /// </summary>
     public class Error : Exception
     {
       private readonly Symbol name;
@@ -1971,37 +1970,93 @@ namespace System.Xml
       public override string ToString () { return str; }
     }
 
+    /// <summary> Structure of term object.</summary>
     public struct Term
     {
-      public int intval;
-      public object objval;
+      internal int intval;
+      internal object objval;
 
-      // <integer>...</integer>
+      /// <summary>Create an integer term.</summary>
+      /// <param name='i'>Integer value of the term.</param>
+      /// <returns>An integer term.</returns>
+      /// <remarks>Create an integer term that has the integer value
+      /// specified by <paramref name="i"/>.  This is an constant
+      /// term; i.e. the integer value never changes.</remarks>
       public Term (int i) { intval = i; objval = null; }
-      // <symbol>...</symbol>
+
+      /// <summary>Create a symbol term.</summary>
+      /// <param name='name'>Symbol value of the term.</param>
+      /// <returns>A symbol term.</returns>
+      /// <remarks>Create a symbol term that has the symbol value
+      /// specified by <paramref name="name"/>.  This is an constant
+      /// term; i.e. the symbol value never changes.  It is evaluated
+      /// to itself.</remarks>
       public Term (Symbol name) { intval = 0; objval = name; }
-      // <string>...</string>
+
+      /// <summary>Create a string term.</summary>
+      /// <param name='str'>String value of the term.</param>
+      /// <returns>A string term.</returns>
+      /// <remarks>Create a string term that has the string value
+      /// specified by <paramref name="str"/>.  It is evaluated to
+      /// itself.  The string value can be modified by "ins", "del",
+      /// and "concat" functions.</remarks>
       public Term (string str) { intval = 0; objval = new Str (str); }
       // <list>...</list>
+
+      /// <summary>Create a list term.</summary>
+      /// <param name='list'>List value of the term.</param>
+      /// <returns>A list term.</returns>
+      /// <remarks>Create a list term that has the list value
+      /// specified by <paramref name="list"/>.  It is evaluated to
+      /// itself.  The list value can be modified by "ins", "del", and
+      /// "append" functions.</remarks>
       public Term (List<Term> list) { intval = 0; objval = list; }
       // <error ename="ERROR-NAME">ERROR-MESSASGE</error>
+
+      /// <summary>Create an error term.</summary>
+      /// <param name='name'>Name of the error.</param>
+      /// <param name='message'>Error message.</param>
+      /// <returns>An error term.</returns>
+      /// <remarks>Create an error term whose error name is <paramref
+      /// name="name"/> and error message is <paramref
+      /// name="message"/>.  It is evaluated to itself.</remarks>
       public Term (Symbol name, string message)
 	{
 	  intval = 0;
 	  objval = new ErrorTerm (name, message);
 	}
 
-      public Term (Str str) { intval = 0; objval = str; }
-      public Term (TermValue obj) { intval = 0; objval = obj; }
+      /// <summary>Create a term of a specific value</summary>
+      /// <param name='val'>Value of the term.</param>
+      /// <returns>A term.</returns>
+      /// <remarks>Create a term whose value is <paramref name="val">.
+      /// It is evaluated to a term that is returned by "Eval" method
+      /// of <paramref name="val">.</remarks>
+      public Term (TermValue val) { intval = 0; objval = val; }
 
-      // <varref vname="VNAME"/>
+      internal Term (Str str) { intval = 0; objval = str; }
+
+      /// <summary>Create a varref term.</summary>
+      /// <param name='domain'>Domain to create the term in.</param>
+      /// <param name='vname'>Name of the referred variable.</param>
+      /// <returns>A varref term.</returns>
+      /// <remarks>Create a varref term that is evaluated to the value
+      /// of the referring variable.</remarks>
       public Term (Domain domain, Symbol vname)
 	{
 	  intval = 0;
 	  objval = new Varref (vname);
 	}
 
-      // <funcall fname="FNAME">...</funcall>
+      /// <summary>Create a funcall term.</summary>
+      /// <param name='domain'>Domain to create the term in.</param>
+      /// <param name='fname'>Name of the calling function.</param>
+      /// <param name='args'>Array of terms that are given to the
+      /// function as arguments.</param>
+      /// <returns>A funcall term.</returns>
+      /// <remarks>Create a funcall term that is evaluated to a term
+      /// returned by the function <paramref name="fname"> when called
+      /// with <paramref name="args">.<remarks>
       public Term (Domain domain, Symbol fname, Term[] args)
 	: this (domain, fname, Qnull, args) { }
 
@@ -2377,7 +2432,7 @@ namespace System.Xml
       return args;
     }
 
-    public static Symbol parse_defun_head (Domain domain, XmlNode node)
+    private static Symbol parse_defun_head (Domain domain, XmlNode node)
     {
       Symbol name = node.Attributes[Qfname].Value;
       int min_args, max_args;
@@ -2391,7 +2446,7 @@ namespace System.Xml
       return name;
     }
 
-    public static void parse_defun_body (Domain domain, XmlNode node)
+    private static void parse_defun_body (Domain domain, XmlNode node)
     {
       bool is_defun = node.Name == Qdefun;
       Symbol name = node.Attributes[Qfname].Value;
@@ -2459,17 +2514,17 @@ namespace System.Xml
       }
     }
 
-    private static bool default_stop (XmlNode n) { return n == null; }
-
-    public delegate bool ParseStop (XmlNode node);
+    /// <summary>Parse a node and the following siblings as "term"s in a
+    /// specific domain.</summary>
+    /// <param name='domain'></param>
+    /// <param name='start'></param>
+    /// <param name='stop'></param>
+    /// <returns>Array of terms.</returns>
 
-    public static Term[] Parse (Domain domain, XmlNode node, ParseStop stop)
+    public static Term[] Parse (Domain domain, XmlNode start, XmlNode stop)
     {
-      if (stop == null)
-	stop = default_stop;
-
       XmlNode n;
-      for (n = node; ! stop (n); n = n.NextSibling)
+      for (n = start; n != stop && n != null; n = n.NextSibling)
 	if (n.NodeType == XmlNodeType.Element
 	    && (n.Name == Qdefun || n.Name == Qdefmacro))
 	  {
@@ -2477,30 +2532,30 @@ namespace System.Xml
 	      parse_defun_head (domain, n);
 	    } catch (Error e) {
 	      if (e.Node == null)
-		e.Node = node;
+		e.Node = n;
 	      throw e;
 	    } catch (Exception e) {
-	      throw new Error (Error.UnknownError, node, e, "Parsing error");
+	      throw new Error (Error.UnknownError, n, e, "Parsing error");
 	    }
 	  }
 
       List<Term> terms = new List<Term> ();
-      for (; node != n; node = node.NextSibling)
-	if (node.NodeType == XmlNodeType.Element)
+      for (; start != n; start = start.NextSibling)
+	if (start.NodeType == XmlNodeType.Element)
 	  {
 	    try {
-	      if (node.Name == Qdefun || node.Name == Qdefmacro)
-		parse_defun_body (domain, node);
-	      else if (node.Name == Qdefvar)
-		parse_defvar (domain, node);
+	      if (start.Name == Qdefun || start.Name == Qdefmacro)
+		parse_defun_body (domain, start);
+	      else if (start.Name == Qdefvar)
+		parse_defvar (domain, start);
 	      else
-		terms.Add (Parse (domain, node));
+		terms.Add (Parse (domain, start));
 	    } catch (Error e) {
 	      if (e.Node == null)
-		e.Node = node;
+		e.Node = start;
 	      throw e;
 	    } catch (Exception e) {
-	      throw new Error (Error.UnknownError, node, e, "Parsing error");
+	      throw new Error (Error.UnknownError, start, e, "Parsing error");
 	    }
 	  }
       return terms.ToArray ();
@@ -2526,11 +2581,21 @@ namespace System.Xml
       return Parse (domain, node.FirstChild, null);
     }
 
+    /// <summary>Evaluate a term in a specific domain.</summary>
+    /// <param name='domain'>Domain to evaluate the term in.</param>
+    /// <param name='term'>The term to evaluate.</param>
+    /// <returns>The result of evaluating the <paramref
+    /// name="term"/>.</returns>
     public static Term Eval (Domain domain, Term term)
     {
       return Eval (domain, new Term[] { term });
     }
 
+    /// <summary>Evaluate terms in a specific domain.</summary>
+    /// <param name='domain'>Domain to evaluate terms in.</param>
+    /// <param name='terms'>Array of terms to evaluate.</param>
+    /// <returns>The result of evaluating the last term of <paramref
+    /// name="terms"/>.</returns>
     public static Term Eval (Domain domain, Term[] terms)
     {
       Term result = Zero;
@@ -2549,5 +2614,16 @@ namespace System.Xml
 	throw new Error (Error.UnknownError, null, e, "Runtime error");
       }
     }
+
+    // TRACING
+
+    private static int trace_depth = 0;
+
+    /// <value> TraceDepth specifies the minimum depth of call stack
+    /// to suppress tracing.  0 means no tracing.  </value>
+    public static int TraceDepth {
+      get { return trace_depth; }
+      set { trace_depth = value; }
+    }
   }
 }