5 // Jonathan Pryor <jpryor@novell.com>
7 // Copyright (c) 2010 Novell, Inc. (http://www.novell.com)
9 // Permission is hereby granted, free of charge, to any person obtaining
10 // a copy of this software and associated documentation files (the
11 // "Software"), to deal in the Software without restriction, including
12 // without limitation the rights to use, copy, modify, merge, publish,
13 // distribute, sublicense, and/or sell copies of the Software, and to
14 // permit persons to whom the Software is furnished to do so, subject to
15 // the following conditions:
17 // The above copyright notice and this permission notice shall be
18 // included in all copies or substantial portions of the Software.
20 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
23 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
24 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
25 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
26 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
30 using System.Collections.Generic;
35 using System.Xml.Linq;
38 using Mono.Documentation;
43 namespace Mono.Documentation
45 public class MDocUpdateEcmaXml : MDocCommand
47 string file = "CLILibraryTypes.xml";
48 List<string> directories;
49 Dictionary<string, HashSet<string>> libraries = new Dictionary<string, HashSet<string>>();
51 public override void Run (IEnumerable<string> args)
53 string current_library = "";
55 var options = new OptionSet () {
57 "{FILE} to generate/update documentation within.\n" +
58 "If not specified, will process " + file + ".\n" +
59 "Set to '-' to skip updates and write to standard output.",
62 "The {LIBRARY} that the following --type=TYPE types should be a part of.",
63 v => current_library = v },
65 "The full {TYPE} name of a type to copy into the output file.",
66 v => AddTypeToLibrary (current_library, v) },
68 directories = Parse (options, args, "export-ecma-xml",
69 "[OPTIONS]+ DIRECTORIES",
70 "Export mdoc documentation within DIRECTORIES into ECMA-format XML.\n\n" +
71 "DIRECTORIES are mdoc(5) directories as produced by 'mdoc update'.");
72 if (directories == null || directories.Count == 0)
78 void AddTypeToLibrary (string library, string type)
80 HashSet<string> types;
81 if (!libraries.TryGetValue (library, out types))
82 libraries.Add (library, types = new HashSet<string> ());
83 types.Add (type.Replace ('/', '.').Replace ('+', '.'));
88 Action<string> creator = file => {
89 XDocument docs = LoadFile (this.file);
91 var seenLibraries = new HashSet<string> ();
93 UpdateExistingLibraries (docs, seenLibraries);
94 GenerateMissingLibraries (docs, seenLibraries);
96 SortLibraries (docs.Root);
97 SortTypes (docs.Root);
99 using (var output = CreateWriter (file)) {
100 foreach (var node in docs.Nodes ()) {
101 if (node.NodeType == XmlNodeType.Element || node.NodeType == XmlNodeType.Text)
103 node.WriteTo (output);
105 docs.Root.WriteTo (output);
106 output.WriteWhitespace ("\r\n");
109 MdocFile.UpdateFile (this.file, creator);
112 static XDocument LoadFile (string file)
114 if (file == "-" || !File.Exists (file))
115 return CreateDefaultDocument ();
117 var settings = new XmlReaderSettings {
118 DtdProcessing = DtdProcessing.Parse
120 using (var reader = XmlReader.Create (file, settings))
121 return XDocument.Load (reader);
124 static XDocument CreateDefaultDocument ()
126 return new XDocument (
127 new XComment (" ====================================================================== "),
128 new XComment (" This XML is a description of the Common Language Infrastructure (CLI) library. "),
129 new XComment (" This file is a normative part of Partition IV of the following standards: ISO/IEC 23271 and ECMA 335 "),
130 new XComment (" ====================================================================== "),
131 new XDocumentType ("Libraries", null, "CLILibraryTypes.dtd", null),
132 new XElement ("Libraries"));
135 static XmlWriter CreateWriter (string file)
137 var settings = new XmlWriterSettings {
140 NewLineChars = "\r\n",
141 OmitXmlDeclaration = true,
145 return XmlWriter.Create (Console.Out, settings);
147 settings.Encoding = new UTF8Encoding (false);
148 return XmlWriter.Create (file, settings);
151 void UpdateExistingLibraries (XDocument docs, HashSet<string> seenLibraries)
153 foreach (XElement types in docs.Root.Elements ("Types")) {
154 XAttribute library = types.Attribute ("Library");
155 HashSet<string> libraryTypes;
156 if (library == null || !libraries.TryGetValue (library.Value, out libraryTypes)) {
159 seenLibraries.Add (library.Value);
160 var seenTypes = new HashSet<string> ();
161 foreach (XElement type in types.Elements ("Type").ToList ()) {
162 XAttribute fullName = type.Attribute ("FullName");
163 string typeName = fullName == null
165 : XmlDocUtils.ToEscapedTypeName (fullName.Value);
166 if (typeName == null || !libraryTypes.Contains (typeName)) {
170 seenTypes.Add (typeName);
171 types.Add (LoadType (typeName, library.Value));
173 foreach (string typeName in libraryTypes.Except (seenTypes))
174 types.Add (LoadType (typeName, library.Value));
178 void GenerateMissingLibraries (XDocument docs, HashSet<string> seenLibraries)
180 foreach (KeyValuePair<string, HashSet<string>> lib in libraries) {
181 if (seenLibraries.Contains (lib.Key))
183 seenLibraries.Add (lib.Key);
184 docs.Root.Add (new XElement ("Types", new XAttribute ("Library", lib.Key),
185 lib.Value.Select (type => LoadType (type, lib.Key))));
189 XElement LoadType (string type, string library)
191 foreach (KeyValuePair<string, string> permutation in GetTypeDirectoryFilePermutations (type)) {
192 foreach (string root in directories) {
193 string path = Path.Combine (root, Path.Combine (permutation.Key, permutation.Value + ".xml"));
194 if (File.Exists (path))
195 return FixupType (path, library);
198 throw new FileNotFoundException ("Unable to find documentation file for type: " + type + ".");
201 // type has been "normalized", which (alas) means we have ~no clue which
202 // part is the namespace and which is the type name, particularly
203 // problematic as types may be nested to any level.
204 // Try ~all permutations. :-)
205 static IEnumerable<KeyValuePair<string, string>> GetTypeDirectoryFilePermutations (string type)
207 int end = type.Length;
209 while ((dot = type.LastIndexOf ('.', end-1)) >= 0) {
210 yield return new KeyValuePair<string, string> (
211 type.Substring (0, dot),
212 type.Substring (dot+1).Replace ('.', '+'));
215 yield return new KeyValuePair<string, string> ("", type.Replace ('.', '+'));
218 static XElement FixupType (string path, string library)
220 var type = XElement.Load (path);
222 XAttribute fullName = type.Attribute ("FullName");
223 XAttribute fullNameSp = type.Attribute ("FullNameSP");
224 if (fullNameSp == null && fullName != null) {
225 type.Add (new XAttribute ("FullNameSP", fullName.Value.Replace ('.', '_')));
227 if (type.Element ("TypeExcluded") == null)
228 type.Add (new XElement ("TypeExcluded", "0"));
229 if (type.Element ("MemberOfLibrary") == null) {
230 XElement member = new XElement ("MemberOfLibrary", library);
231 XElement assemblyInfo = type.Element ("AssemblyInfo");
232 if (assemblyInfo != null)
233 assemblyInfo.AddBeforeSelf (member);
238 XElement ai = type.Element ("AssemblyInfo");
243 Path.Combine (Path.GetDirectoryName (path), ".."),
245 .Element ("Assemblies")
246 .Elements ("Assembly")
247 .FirstOrDefault (a => a.Attribute ("Name").Value == ai.Element ("AssemblyName").Value &&
248 a.Attribute ("Version").Value == ai.Element ("AssemblyVersion").Value);
249 if (assembly == null)
252 if (assembly.Element ("AssemblyPublicKey") != null)
253 ai.Add (assembly.Element ("AssemblyPublicKey"));
255 if (assembly.Element ("AssemblyCulture") != null)
256 ai.Add (assembly.Element ("AssemblyCulture"));
258 ai.Add (new XElement ("AssemblyCulture", "neutral"));
260 // TODO: assembly attributes?
261 // The problem is that .NET mscorlib.dll v4.0 has ~26 attributes, and
262 // importing these for every time seems like some serious bloat...
263 var clsDefAttr = assembly.Elements ("Attributes").Elements ("Attribute")
264 .FirstOrDefault (a => a.Element ("AttributeName").Value.StartsWith ("System.CLSCompliant"));
265 if (clsDefAttr != null &&
266 ai.Elements ("Attributes").Elements ("Attribute")
267 .FirstOrDefault (a => a.Element ("AttributeName").Value.StartsWith ("System.CLSCompliant")) == null) {
268 var dest = ai.Element ("Attributes");
270 ai.Add (dest = new XElement ("Attributes"));
271 dest.Add (clsDefAttr);
277 static void SortLibraries (XContainer libraries)
279 SortElements (libraries, (x, y) => x.Attribute ("Library").Value.CompareTo (y.Attribute ("Library").Value));
282 static void SortElements (XContainer container, Comparison<XElement> comparison)
284 var items = new List<XElement> ();
285 foreach (var e in container.Elements ())
287 items.Sort (comparison);
288 for (int i = items.Count - 1; i > 0; --i) {
289 items [i-1].Remove ();
290 items [i].AddBeforeSelf (items [i-1]);
294 static void SortTypes (XContainer libraries)
296 foreach (var types in libraries.Elements ("Types")) {
297 SortElements (types, (x, y) => {
301 GetTypeSortName (x, out xName, out xCount);
302 GetTypeSortName (y, out yName, out yCount);
304 int c = xName.CompareTo (yName);
316 static void GetTypeSortName (XElement element, out string name, out int typeParamCount)
319 name = element.Attribute ("Name").Value;
321 int lt = name.IndexOf ('<');
323 int gt = name.IndexOf ('>', lt);
325 typeParamCount = name.Substring (lt, gt-lt).Count (c => c == ',') + 1;
327 name = name.Substring (0, lt);