Merge branch 'contracts'

1 files changed, 448 insertions, 0 deletions

diff --git a/tools/Sandcastle/Source/BuildAssembler/BuildComponents/ResolveConceptualLinksComponent.cs b/tools/Sandcastle/Source/BuildAssembler/BuildComponents/ResolveConceptualLinksComponent.cs
new file mode 100644
index 0000000..2531e23
--- /dev/null
+++ b/tools/Sandcastle/Source/BuildAssembler/BuildComponents/ResolveConceptualLinksComponent.cs
@@ -0,0 +1,448 @@
+// Copyright © Microsoft Corporation.
+// This source file is subject to the Microsoft Permissive License.
+// See http://www.microsoft.com/resources/sharedsource/licensingbasics/sharedsourcelicenses.mspx.
+// All other rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using System.Xml;
+using System.Xml.XPath;
+using System.Text.RegularExpressions;
+using System.Web;
+
+
+namespace Microsoft.Ddue.Tools {
+
+	public class ResolveConceptualLinksComponent : BuildComponent {
+
+        // Instantiation logic
+
+		public ResolveConceptualLinksComponent (BuildAssembler assembler, XPathNavigator configuration) : base(assembler, configuration) {
+
+            string showBrokenLinkTextValue = configuration.GetAttribute("showBrokenLinkText", String.Empty);
+            if (!String.IsNullOrEmpty(showBrokenLinkTextValue)) showBrokenLinkText = Convert.ToBoolean(showBrokenLinkTextValue);
+
+			XPathNodeIterator targetsNodes = configuration.Select("targets");
+			foreach (XPathNavigator targetsNode in targetsNodes) {
+
+                // the base directory containing target; required
+                string baseValue = targetsNode.GetAttribute("base", String.Empty);
+                if (String.IsNullOrEmpty(baseValue)) WriteMessage(MessageLevel.Error, "Every targets element must have a base attribute that specifies the path to a directory of target metadata files.");
+                baseValue = Environment.ExpandEnvironmentVariables(baseValue);
+                if (!Directory.Exists(baseValue)) WriteMessage(MessageLevel.Error, String.Format("The specified target metadata directory '{0}' does not exist.", baseValue));
+
+                // an xpath expression to construct a file name
+                // (not currently used; pattern is hard-coded to $target.cmp.xml
+                string filesValue = targetsNode.GetAttribute("files", String.Empty);
+
+                // an xpath expression to construct a url
+                string urlValue = targetsNode.GetAttribute("url", String.Empty);
+                XPathExpression urlExpression;
+                if (String.IsNullOrEmpty(urlValue)) {
+                    urlExpression = XPathExpression.Compile("concat(/metadata/topic/@id,'.htm')");
+                } else {
+                    urlExpression = CompileXPathExpression(urlValue);
+                }
+                
+                // an xpath expression to construct link text
+                string textValue = targetsNode.GetAttribute("text", String.Empty);
+                XPathExpression textExpression;
+                if (String.IsNullOrEmpty(textValue)) {
+                    textExpression = XPathExpression.Compile("string(/metadata/topic/title)");
+                } else {
+                    textExpression = CompileXPathExpression(textValue);
+                }
+
+                // the type of link to create to targets found in the directory; required
+                string typeValue = targetsNode.GetAttribute("type", String.Empty);
+                if (String.IsNullOrEmpty(typeValue)) WriteMessage(MessageLevel.Error, "Every targets element must have a type attribute that specifies what kind of link to create to targets found in that directory.");
+                
+                // convert the link type to an enumeration member
+                LinkType type = LinkType.None;
+                try {
+                    type = (LinkType) Enum.Parse(typeof(LinkType), typeValue, true);
+                } catch (ArgumentException) {
+                    WriteMessage(MessageLevel.Error, String.Format("'{0}' is not a valid link type.", typeValue));
+                }
+
+                // we have all the required information; create a TargetDirectory and add it to our collection
+                TargetDirectory targetDirectory = new TargetDirectory(baseValue, urlExpression, textExpression, type);
+                targetDirectories.Add(targetDirectory);
+
+            }
+
+            WriteMessage(MessageLevel.Info, String.Format("Collected {0} targets directories.", targetDirectories.Count));	
+
+		}
+
+        private XPathExpression CompileXPathExpression (string xpath) {
+            XPathExpression expression = null;
+            try {
+                expression = XPathExpression.Compile(xpath);
+            } catch (ArgumentException e) {
+                WriteMessage(MessageLevel.Error, String.Format("'{0}' is not a valid XPath expression. The error message is: {1}", xpath, e.Message));
+            } catch (XPathException e) {
+                WriteMessage(MessageLevel.Error, String.Format("'{0}' is not a valid XPath expression. The error message is: {1}", xpath, e.Message));
+            }
+            return (expression);
+        }
+
+        // Conceptual link resolution logic
+
+		public override void Apply (XmlDocument document, string key) {
+			ResolveConceptualLinks(document, key);
+		}
+
+        private bool showBrokenLinkText = false;
+
+        private string BrokenLinkDisplayText (string target, string text) {
+            if (showBrokenLinkText) {
+                return(String.Format("{0}", text));
+            } else {
+                return(String.Format("[{0}]", target));
+            }
+        }
+
+        private TargetDirectoryCollection targetDirectories = new TargetDirectoryCollection();
+
+        private static XPathExpression conceptualLinks = XPathExpression.Compile("//conceptualLink");
+
+        private static Regex validGuid = new Regex(@"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", RegexOptions.Compiled);
+
+		private void ResolveConceptualLinks (XmlDocument document, string key) {
+
+			// find links
+			XPathNodeIterator linkIterator = document.CreateNavigator().Select(conceptualLinks);
+
+			// copy them to an array, because enumerating through an XPathNodeIterator
+			// fails when the nodes in it are altered
+			XPathNavigator[] linkNodes = BuildComponentUtilities.ConvertNodeIteratorToArray(linkIterator);
+			
+			foreach (XPathNavigator linkNode in linkNodes) {
+
+                ConceptualLinkInfo link = ConceptualLinkInfo.Create(linkNode);
+
+                // determine url, text, and link type
+                string url = null;
+                string text = null;
+                LinkType type = LinkType.None;
+                bool isValidLink = validGuid.IsMatch(link.Target);
+                if (isValidLink) {
+                    // a valid link; try to fetch target info
+                    TargetInfo target = GetTargetInfoFromCache(link.Target.ToLower());
+                    if (target == null) {
+                        // no target found; issue warning, set link style to none, and text to in-source fall-back
+                        //type = LinkType.None;
+                        type = LinkType.Index;
+                        text = BrokenLinkDisplayText(link.Target, link.Text);
+                        WriteMessage(MessageLevel.Warn, String.Format("Unknown conceptual link target '{0}'.", link.Target));
+                    } else {
+                        // found target; get url, text, and type from stored info
+                        url = target.Url;
+                        text = target.Text;
+                        type = target.Type;
+                    }
+                } else {
+                    // not a valid link; issue warning, set link style to none, and text to invalid target
+                    //type = LinkType.None;
+                    type = LinkType.Index;
+                    text = BrokenLinkDisplayText(link.Target, link.Text);
+                    WriteMessage(MessageLevel.Warn, String.Format("Invalid conceptual link target '{0}'.", link.Target));
+                }
+
+                // write opening link tag and target info
+                XmlWriter writer = linkNode.InsertAfter();
+                switch (type) {
+                    case LinkType.None:
+                        writer.WriteStartElement("span");
+                        writer.WriteAttributeString("class", "nolink");
+                        break;
+                    case LinkType.Local:
+                        writer.WriteStartElement("a");
+                        writer.WriteAttributeString("href", url);
+                        break;
+                    case LinkType.Index:
+                        writer.WriteStartElement("mshelp", "link", "http://msdn.microsoft.com/mshelp");
+                        writer.WriteAttributeString("keywords", link.Target.ToLower());
+                        writer.WriteAttributeString("tabindex", "0");
+                        break;
+                }
+
+                // write the link text
+                writer.WriteString(text);
+
+                // write the closing link tag
+                writer.WriteEndElement();
+                writer.Close();
+
+                // delete the original tag
+                linkNode.DeleteSelf();
+            }
+		}
+
+
+
+
+		// a simple caching system for target names
+
+		private TargetInfo GetTargetInfoFromCache (string target) {
+
+			TargetInfo info;
+			if (!cache.TryGetValue(target, out info)) {
+				info = targetDirectories.GetTargetInfo(target + ".cmp.xml");
+
+				if (cache.Count >= cacheSize) cache.Clear();
+
+				cache.Add(target, info);
+			}
+
+            return(info);
+
+		}
+
+		private static int cacheSize = 1000;
+
+		private Dictionary<string,TargetInfo> cache = new Dictionary<string,TargetInfo>(cacheSize);
+
+        //private CustomContext context = new CustomContext();
+
+	}
+
+	// different types of links
+
+	internal enum LinkType {
+		None,		// not active
+		Local,		// a href
+		Index  	// mshelp:link keyword
+        //Regex       // regular expression with match/replace
+	}
+
+    // a representation of a targets directory, along with all the assoicated expressions used to
+    // find target metadat files in it, and extract urls and link text from those files
+
+    internal class TargetDirectory {
+
+        private string directory;
+
+        private XPathExpression fileExpression = XPathExpression.Compile("concat($target,'.cmp.htm')");
+
+        private XPathExpression urlExpression = XPathExpression.Compile("concat(/metadata/topic/@id,'.htm')");
+
+        private XPathExpression textExpression = XPathExpression.Compile("string(/metadata/topic/title)");
+
+        private LinkType type;
+
+        public string Directory {
+            get {
+                return (directory);
+            }
+        }
+
+        public XPathExpression UrlExpression {
+            get {
+                return (urlExpression);
+            }
+        }
+
+        public XPathExpression TextExpression {
+            get {
+                return (textExpression);
+            }
+        }
+
+
+        public LinkType LinkType {
+            get {
+                return (type);
+            }
+        }
+
+        public TargetDirectory (string directory, LinkType type) {
+            if (directory == null) throw new ArgumentNullException("directory");
+            this.directory = directory;
+            this.type = type;
+        }
+
+        public TargetDirectory (string directory, XPathExpression urlExpression, XPathExpression textExpression, LinkType type) {
+            if (directory == null) throw new ArgumentNullException("directory");
+            if (urlExpression == null) throw new ArgumentNullException("urlExpression");
+            if (textExpression == null) throw new ArgumentNullException("textExpression");
+            this.directory = directory;
+            this.urlExpression = urlExpression;
+            this.textExpression = textExpression;
+            this.type = type;
+        }
+
+        private XPathDocument GetDocument (string file) {
+            string path = Path.Combine(directory, file);
+            if (File.Exists(path)) {
+                XPathDocument document = new XPathDocument(path);
+                return (document);
+            } else {
+                return (null);
+            }
+        }
+
+        public TargetInfo GetTargetInfo (string file) {
+            XPathDocument document = GetDocument(file);
+            if (document == null) {
+                return(null);
+            } else {
+                XPathNavigator context = document.CreateNavigator();
+
+                string url = context.Evaluate(urlExpression).ToString();
+                string text = context.Evaluate(textExpression).ToString();
+                TargetInfo info = new TargetInfo(url, text, type);
+                return(info);
+            }
+        }
+
+        public TargetInfo GetTargetInfo (XPathNavigator linkNode, CustomContext context) {
+
+            // compute the metadata file name to open
+            XPathExpression localFileExpression = fileExpression.Clone();
+            localFileExpression.SetContext(context);
+            string file = linkNode.Evaluate(localFileExpression).ToString();
+            if (String.IsNullOrEmpty(file)) return (null);
+
+            // load the metadata file
+            XPathDocument metadataDocument = GetDocument(file);
+            if (metadataDocument == null) return (null);
+
+            // querry the metadata file for the target url and link text
+            XPathNavigator metadataNode = metadataDocument.CreateNavigator();
+            XPathExpression localUrlExpression = urlExpression.Clone();
+            localUrlExpression.SetContext(context);
+            string url = metadataNode.Evaluate(localUrlExpression).ToString();
+            XPathExpression localTextExpression = textExpression.Clone();
+            localTextExpression.SetContext(context);
+            string text = metadataNode.Evaluate(localTextExpression).ToString();
+
+            // return this information
+            TargetInfo info = new TargetInfo(url, text, type);
+            return (info);
+        }
+
+
+
+    }
+
+    // our collection of targets directories
+
+    internal class TargetDirectoryCollection {
+
+        public TargetDirectoryCollection() {}
+
+        private List<TargetDirectory> targetDirectories = new List<TargetDirectory>();
+
+        public int Count {
+            get {
+                return(targetDirectories.Count);
+            }
+        }
+
+        public void Add (TargetDirectory targetDirectory) {
+            targetDirectories.Add(targetDirectory);
+        }
+
+        public TargetInfo GetTargetInfo (string file) {
+            foreach (TargetDirectory targetDirectory in targetDirectories) {
+                TargetInfo info = targetDirectory.GetTargetInfo(file);
+                if (info != null) return (info);
+            }
+            return (null);
+        }
+
+        public TargetInfo GetTargetInfo (XPathNavigator linkNode, CustomContext context) {
+            foreach (TargetDirectory targetDirectory in targetDirectories) {
+                TargetInfo info = targetDirectory.GetTargetInfo(linkNode, context);
+                if (info != null) return (info);
+            }
+            return (null);
+        }
+
+    }
+
+    // a representation of a resolved target, containing all the information necessary to actually write out the link
+
+    internal class TargetInfo {
+
+        private string url;
+
+        private string text;
+
+        private LinkType type;
+
+        public string Url {
+            get {
+                return(url);
+            }
+        }
+
+        public string Text {
+            get {
+                return(text);
+            }
+        }
+
+        public LinkType Type {
+            get {
+                return(type);
+            }
+        }
+
+        internal TargetInfo (string url, string text, LinkType type) {
+            if (url == null) throw new ArgumentNullException("url");
+            if (text == null) throw new ArgumentNullException("url");
+            this.url = url;
+            this.text = text;
+            this.type = type;
+        }
+    }
+
+    // a representation of a conceptual link
+
+    internal class ConceptualLinkInfo {
+
+        private string target;
+
+        private string text;
+
+        private bool showText = false;
+
+        public string Target {
+            get {
+                return (target);
+            }
+        }
+
+        public string Text {
+            get {
+                return (text);
+            }
+        }
+
+        public bool ShowText {
+            get {
+                return (showText);
+            }
+        }
+
+        private ConceptualLinkInfo () { }
+
+        public static ConceptualLinkInfo Create (XPathNavigator node) {
+            if (node == null) throw new ArgumentNullException("node");
+            
+            ConceptualLinkInfo info = new ConceptualLinkInfo();
+            
+            info.target = node.GetAttribute("target", String.Empty);
+            info.text = node.ToString();
+            
+            return(info);
+        }
+
+    }
+
+}
\ No newline at end of file