mcs/tools/mdoc/Mono.Documentation/ecmadoc.cs

   1 //
   2 // ecmadoc.cs
   3 //
   4 // Author:
   5 //   Jonathan Pryor  <jpryor@novell.com>
   6 //
   7 // Copyright (c) 2010 Novell, Inc. (http://www.novell.com)
   8 //
   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:
  16 //
  17 // The above copyright notice and this permission notice shall be
  18 // included in all copies or substantial portions of the Software.
  19 //
  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.
  27 //
  28
  29 using System;
  30 using System.Collections.Generic;
  31 using System.IO;
  32 using System.Linq;
  33 using System.Text;
  34 using System.Xml;
  35 using System.Xml.Linq;
  36
  37 using Monodoc;
  38 using Mono.Documentation;
  39
  40 using Mono.Options;
  41 using Mono.Rocks;
  42
  43 namespace Mono.Documentation
  44 {
  45         public class MDocUpdateEcmaXml : MDocCommand
  46         {
  47                 string file = "CLILibraryTypes.xml";
  48                 List<string> directories;
  49                 Dictionary<string, HashSet<string>> libraries = new Dictionary<string, HashSet<string>>();
  50
  51                 public override void Run (IEnumerable<string> args)
  52                 {
  53                         string current_library = "";
  54
  55                         var options = new OptionSet () {
  56                                 { "o|out=",
  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.",
  60                                         v => file = v },
  61                                 { "library=",
  62                                         "The {LIBRARY} that the following --type=TYPE types should be a part of.",
  63                                         v => current_library = v },
  64                                 { "type=",
  65                                         "The full {TYPE} name of a type to copy into the output file.",
  66                                         v => AddTypeToLibrary (current_library, v) },
  67                         };
  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)
  73                                 return;
  74
  75                         Update ();
  76                 }
  77
  78                 void AddTypeToLibrary (string library, string type)
  79                 {
  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 ('+', '.'));
  84                 }
  85
  86                 void Update ()
  87                 {
  88                         Action<string> creator = file => {
  89                                 XDocument docs = LoadFile (this.file);
  90
  91                                 var seenLibraries = new HashSet<string> ();
  92
  93                                 UpdateExistingLibraries (docs, seenLibraries);
  94                                 GenerateMissingLibraries (docs, seenLibraries);
  95
  96                                 SortLibraries (docs.Root);
  97                                 SortTypes (docs.Root);
  98
  99                                 using (var output = CreateWriter (file)) {
 100                                         foreach (var node in docs.Nodes ()) {
 101                                                 if (node.NodeType == XmlNodeType.Element || node.NodeType == XmlNodeType.Text)
 102                                                         continue;
 103                                                 node.WriteTo (output);
 104                                         }
 105                                         docs.Root.WriteTo (output);
 106                                         output.WriteWhitespace ("\r\n");
 107                                 }
 108                         };
 109                         MdocFile.UpdateFile (this.file, creator);
 110                 }
 111
 112                 static XDocument LoadFile (string file)
 113                 {
 114                         if (file == "-" || !File.Exists (file))
 115                                 return CreateDefaultDocument ();
 116
 117                         var settings = new XmlReaderSettings {
 118                                 DtdProcessing = DtdProcessing.Parse
 119                         };
 120                         using (var reader = XmlReader.Create (file, settings))
 121                                 return XDocument.Load (reader);
 122                 }
 123
 124                 static XDocument CreateDefaultDocument ()
 125                 {
 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"));
 133                 }
 134
 135                 static XmlWriter CreateWriter (string file)
 136                 {
 137                         var settings = new XmlWriterSettings {
 138                                 Indent              = true,
 139                                 IndentChars         = "\t",
 140                                 NewLineChars        = "\r\n",
 141                                 OmitXmlDeclaration  = true,
 142                         };
 143
 144                         if (file == "-")
 145                                 return XmlWriter.Create (Console.Out, settings);
 146
 147                         settings.Encoding = new UTF8Encoding (false);
 148                         return XmlWriter.Create (file, settings);
 149                 }
 150
 151                 void UpdateExistingLibraries (XDocument docs, HashSet<string> seenLibraries)
 152                 {
 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)) {
 157                                         continue;
 158                                 }
 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
 164                                                 ? null
 165                                                 : XmlDocUtils.ToEscapedTypeName (fullName.Value);
 166                                         if (typeName == null || !libraryTypes.Contains (typeName)) {
 167                                                 continue;
 168                                         }
 169                                         type.Remove ();
 170                                         seenTypes.Add (typeName);
 171                                         types.Add (LoadType (typeName, library.Value));
 172                                 }
 173                                 foreach (string typeName in libraryTypes.Except (seenTypes))
 174                                         types.Add (LoadType (typeName, library.Value));
 175                         }
 176                 }
 177
 178                 void GenerateMissingLibraries (XDocument docs, HashSet<string> seenLibraries)
 179                 {
 180                         foreach (KeyValuePair<string, HashSet<string>> lib in libraries) {
 181                                 if (seenLibraries.Contains (lib.Key))
 182                                         continue;
 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))));
 186                         }
 187                 }
 188
 189                 XElement LoadType (string type, string library)
 190                 {
 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);
 196                                 }
 197                         }
 198                         throw new FileNotFoundException ("Unable to find documentation file for type: " + type + ".");
 199                 }
 200
 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)
 206                 {
 207                         int end = type.Length;
 208                         int dot;
 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 ('.', '+'));
 213                                 end = dot;
 214                         }
 215                         yield return new KeyValuePair<string, string> ("", type.Replace ('.', '+'));
 216                 }
 217
 218                 static XElement FixupType (string path, string library)
 219                 {
 220                         var type = XElement.Load (path);
 221
 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 ('.', '_')));
 226                         }
 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);
 234                                 else
 235                                         type.Add (member);
 236                         }
 237
 238                         XElement ai = type.Element ("AssemblyInfo");
 239
 240                         XElement assembly =
 241                                 XElement.Load (
 242                                                 Path.Combine (
 243                                                         Path.Combine (Path.GetDirectoryName (path), ".."),
 244                                                         "index.xml"))
 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)
 250                                 return type;
 251
 252                         if (assembly.Element ("AssemblyPublicKey") != null)
 253                                 ai.Add (assembly.Element ("AssemblyPublicKey"));
 254
 255                         if (assembly.Element ("AssemblyCulture") != null)
 256                                 ai.Add (assembly.Element ("AssemblyCulture"));
 257                         else
 258                                 ai.Add (new XElement ("AssemblyCulture", "neutral"));
 259
 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");
 269                                 if (dest == null)
 270                                         ai.Add (dest = new XElement ("Attributes"));
 271                                 dest.Add (clsDefAttr);
 272                         }
 273
 274                         return type;
 275                 }
 276
 277                 static void SortLibraries (XContainer libraries)
 278                 {
 279                         SortElements (libraries, (x, y) => x.Attribute ("Library").Value.CompareTo (y.Attribute ("Library").Value));
 280                 }
 281
 282                 static void SortElements (XContainer container, Comparison<XElement> comparison)
 283                 {
 284                         var items = new List<XElement> ();
 285                         foreach (var e in container.Elements ())
 286                                 items.Add (e);
 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]);
 291                         }
 292                 }
 293
 294                 static void SortTypes (XContainer libraries)
 295                 {
 296                         foreach (var types in libraries.Elements ("Types")) {
 297                                 SortElements (types, (x, y) => {
 298                                                 string xName, yName;
 299                                                 int xCount, yCount;
 300
 301                                                 GetTypeSortName (x, out xName, out xCount);
 302                                                 GetTypeSortName (y, out yName, out yCount);
 303
 304                                                 int c = xName.CompareTo (yName);
 305                                                 if (c != 0)
 306                                                         return c;
 307                                                 if (xCount < yCount)
 308                                                         return -1;
 309                                                 if (yCount < xCount)
 310                                                         return 1;
 311                                                 return 0;
 312                                 });
 313                         }
 314                 }
 315
 316                 static void GetTypeSortName (XElement element, out string name, out int typeParamCount)
 317                 {
 318                         typeParamCount = 0;
 319                         name = element.Attribute ("Name").Value;
 320
 321                         int lt = name.IndexOf ('<');
 322                         if (lt >= 0) {
 323                                 int gt = name.IndexOf ('>', lt);
 324                                 if (gt >= 0) {
 325                                         typeParamCount = name.Substring (lt, gt-lt).Count (c => c == ',') + 1;
 326                                 }
 327                                 name = name.Substring (0, lt);
 328                         }
 329                 }
 330         }
 331 }