Resolved several issues relating to the object model for METAL templates:

---

* Resolved #514 - providing ZPT documents with a mechanism to specify a class that they should inherit from

* * Created a new class: ZptMetadata
* * * This describes the optional attributes that relate to a ZPT template document

* * Wrote unit tests for all of this

* * Improved an existing unit test to provider faster rendering of the test document

* * Created a method by which 'foreign' types (types from other assemblies) may be registered
    as ZPT template document types

* * Created a simple class to provide a heirarchical structure (like folders) for use
    with a TalesContext: TalesStructureProvider
* * * This is also tested

---

* Resolved #512 - creating an object model for METAL documents to refer to each other and their macros

* * Created new child class of TalesStructureProvider: ZptDocumentCollection which includes a method to read
    a collection of ZPT documents from the filesystem.

* * Created unit tests for this functionality

* Created and tested implementation for loading other macros from a METAL document

* The GetUseMacro() method of a MetalElement is working and tested

Author: craigfowler

.gitignore

@@ -1,6 +1,8 @@
 bin/
+obj/
 *.pidb
 *.desktop
 *.userprefs
 TestResult.xml
 .directory
+ZopePageTemplates.VisualState.xml

Parser/ITemplateDocument.cs

@@ -0,0 +1,78 @@
+//  
+//  ITemplateDocument.cs
+//  
+//  Author:
+//       Craig Fowler <[email protected]>
+// 
+//  Copyright (c) 2010 Craig Fowler
+// 
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+// 
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU General Public License for more details.
+// 
+//  You should have received a copy of the GNU General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+using System;
+using CraigFowler.Web.ZPT.Tales;
+using CraigFowler.Web.ZPT.Tal;
+using System.Xml;
+namespace CraigFowler.Web.ZPT
+{
+	/// <summary>
+	/// <para>Interface describes a document template which may expose the TAL and/or METAL functionality.</para>
+	/// </summary>
+	public interface ITemplateDocument
+	{
+		/// <summary>
+		/// <para>
+		/// Gets and sets whether or not this document should force the reindentation and reformatting of the document on
+		/// rendering.  This property is only applicable if <see cref="XmlDocument.PreserveWhitespace"/> is false.
+		/// </para>
+		/// </summary>
+		bool ReformatDocument { get; set; }
+		
+    /// <summary>
+    /// <para>Gets and sets the <see cref="TalesContext"/> for this document.</para>
+    /// </summary>
+		TalesContext TalesContext { get; set; }
+		
+		/// <summary>
+    /// <para>Overloaded.  Renders this node and its children using the given <see cref="TalOutput"/> instance.</para>
+		/// </summary>
+		/// <param name="output">
+		/// A <see cref="TalOutput"/>
+		/// </param>
+		void Render(TalOutput output);
+		
+    /// <summary>
+    /// <para>Overloaded.  Renders the output of this document to the given <see cref="XmlWriter"/>.</para>
+    /// </summary>
+    /// <param name="writer">
+    /// An <see cref="XmlWriter"/> to write the rendere output of this document to.
+    /// </param>
+		void Render(XmlWriter writer);
+		
+    /// <summary>
+    /// <para>Overloaded.  Convenience method that renders the output of this document to a string.</para>
+    /// </summary>
+    /// <returns>
+    /// A <see cref="System.String"/>, the rendered output document.
+    /// </returns>
+		string Render();
+		
+		/// <summary>
+		/// <para>Overloaded.  Reads XML from a file at <paramref name="path"/> into this instance.</para>
+		/// </summary>
+		/// <param name="path">
+		/// A <see cref="System.String"/>
+		/// </param>
+		void Load(string path);
+	}
+}
+

Parser/IZptDocument.cs

@@ -0,0 +1,67 @@
+//  
+//  IZptDocument.cs
+//  
+//  Author:
+//       Craig Fowler <[email protected]>
+// 
+//  Copyright (c) 2010 Craig Fowler
+// 
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+// 
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU General Public License for more details.
+// 
+//  You should have received a copy of the GNU General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+using System;
+using CraigFowler.Web.ZPT.Tal;
+using CraigFowler.Web.ZPT.Metal;
+using CraigFowler.Web.ZPT.Tales;
+using System.Collections.Generic;
+
+namespace CraigFowler.Web.ZPT
+{
+	/// <summary>
+	/// <para>Interface describes a Zope Page Templates document.</para>
+	/// <seealso cref="ZptMetadata.DocumentClass"/>
+	/// </summary>
+	public interface IZptDocument
+	{
+		/// <summary>
+		/// <para>Gets and sets the document metadata for this ZPT document.</para>
+		/// </summary>
+		ZptMetadata Metadata { get; set; }
+		
+		/// <summary>
+		/// <para>
+		/// Read-only.  Gets whether this ZPT document has macro-expansions (METAL) enabled or not.  If this property is
+		/// false then the underlying document will be a <see cref="TalDocument"/> instead of a
+		/// <see cref="MetalDocument"/>.
+		/// </para>
+		/// </summary>
+		bool MetalEnabled { get; }
+		
+		/// <summary>
+		/// <para>Gets the XML template document that is associated with this instance.</para>
+		/// </summary>
+		/// <returns>
+		/// An object instance that implements <see cref="ITemplateDocument"/>.
+		/// </returns>
+		ITemplateDocument GetTemplateDocument();
+    
+    /// <summary>
+    /// <para>Gets a collection of the <see cref="MetalMacro"/> instances that this instance contains.</para>
+    /// </summary>
+    /// <returns>
+    /// A dictionary of <see cref="MetalMacro"/>, indexed by <see cref="System.String"/>
+    /// </returns>
+    [TalesAlias("macros")]
+    MetalMacroCollection GetMacros();
+	}
+}
+

Parser/Metal/Exceptions/MetalException.cs

@@ -0,0 +1,96 @@
+//  
+//  MetalException.cs
+//  
+//  Author:
+//       Craig Fowler <[email protected]>
+// 
+//  Copyright (c) 2011 Craig Fowler
+// 
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+// 
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU General Public License for more details.
+// 
+//  You should have received a copy of the GNU General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+using System;
+namespace CraigFowler.Web.ZPT.Metal.Exceptions
+{
+  /// <summary>
+  /// <para>
+  /// Represents an <see cref="Exception"/> that is raised in relation to handling of METAL macros.
+  /// </para>
+  /// </summary>
+  public class MetalException : Exception
+  {
+    #region constants
+    
+    private const string DEFAULT_MESSAGE = "There was an error relating to a METAL document or element";
+    
+    #endregion
+    
+    #region properties
+    
+    /// <summary>
+    /// <para>
+    /// Gets and sets a value that indicates whether this exception indicates a permanent error in parsing the
+    /// expression.
+    /// </para>
+    /// <para>
+    /// In a permanent error, changing the values within the domain model will not help resolving the error.
+    /// </para>
+    /// </summary>
+    public bool PermanentError
+    {
+      get;
+      protected set;
+    }
+    
+    #endregion
+    
+    #region constructors
+    
+    /// <summary>
+    /// <para>Initialises this instance with default values.</para>
+    /// </summary>
+    public MetalException() : this(DEFAULT_MESSAGE, null) {}
+    
+    /// <summary>
+    /// <para>Initialises this instance with an exception message.</para>
+    /// </summary>
+    /// <param name="message">
+    /// A <see cref="System.String"/>
+    /// </param>
+    public MetalException(string message) : this(message, null) {}
+    
+    /// <summary>
+    /// <para>Initialises this instance with an inner exception.</para>
+    /// </summary>
+    /// <param name="inner">
+    /// A <see cref="Exception"/>
+    /// </param>
+    public MetalException(Exception inner) : this(DEFAULT_MESSAGE, inner) {}
+    
+    /// <summary>
+    /// <para>Initialises this instance with an exception message and an inner exception.</para>
+    /// </summary>
+    /// <param name="message">
+    /// A <see cref="System.String"/>
+    /// </param>
+    /// <param name="inner">
+    /// A <see cref="Exception"/>
+    /// </param>
+    public MetalException(string message, Exception inner) : base(message, inner)
+    {
+      this.PermanentError = true;
+    }
+    
+    #endregion
+  }
+}
+

Parser/Metal/IMetalDocument.cs

@@ -0,0 +1,39 @@
+//  
+//  IMetalDocument.cs
+//  
+//  Author:
+//       Craig Fowler <[email protected]>
+// 
+//  Copyright (c) 2011 Craig Fowler
+// 
+//  This program is free software: you can redistribute it and/or modify
+//  it under the terms of the GNU General Public License as published by
+//  the Free Software Foundation, either version 3 of the License, or
+//  (at your option) any later version.
+// 
+//  This program is distributed in the hope that it will be useful,
+//  but WITHOUT ANY WARRANTY; without even the implied warranty of
+//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//  GNU General Public License for more details.
+// 
+//  You should have received a copy of the GNU General Public License
+//  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+using System;
+using System.Collections.Generic;
+
+namespace CraigFowler.Web.ZPT.Metal
+{
+  /// <summary>
+  /// <para>Marker interface for a <see cref="ITemplateDocument"/> that is METAL-capable.</para>
+  /// </summary>
+  public interface IMetalDocument : ITemplateDocument
+  {
+    /// <summary>
+    /// <para>
+    /// Read-only.  Gets a collection of the <see cref="MetalMacro"/>s that are defined within this document.
+    /// </para>
+    /// </summary>
+    MetalMacroCollection Macros { get; }
+  }
+}
+