git.roojs.org Git - gnome.introspection-doc-generator/blob - JSDOC/SymbolSet.js

   1 //<script type="text/javascript">
   2
   3
   4 XObject         = imports.XObject.XObject;
   5 DocComment      = imports.DocComment.DocComment;
   6 // circular references..
   7 ///Options         = imports.BuildDocs.Options;
   8 //Parser          = imports.Parser.Parser;
   9 //Symbol          = imports.Symbol.Symbol;
  10
  11
  12
  13 SymbolSet = XObject.define(
  14     function() {
  15         this.init();
  16     },
  17     Object,
  18     {
  19
  20         _index : false,
  21
  22
  23         init : function() {
  24             this._index = {};
  25         },
  26
  27         keys : function()
  28         {
  29             var found = [];
  30             for (var p in this._index) {
  31                 found.push(p);
  32             }
  33             return found;
  34         },
  35
  36
  37         hasSymbol : function(alias) {
  38             return typeof(this._index[alias]) != 'undefined';
  39             //return this.keys().indexOf(alias) > -1;
  40         },
  41
  42         addSymbol : function(symbol) {
  43             //print("ADDING SYMBOL:"+symbol.alias.toString());
  44
  45
  46             if (this.hasSymbol(symbol.alias)) {
  47                 imports.BuildDocs.Options.LOG.warn("Overwriting symbol documentation for: "+symbol.alias + ".");
  48             }
  49             this._index[symbol.alias] = symbol;
  50         },
  51
  52         getSymbol : function(alias) {
  53
  54             if (this.hasSymbol(alias)) return this._index[alias];
  55             return false;
  56         },
  57
  58         toArray : function() {
  59             var found = [];
  60             for (var p in this._index) {
  61                 found.push(this._index[p]);
  62             }
  63             return found;
  64         },
  65         /**
  66          * for serializing
  67          */
  68         toJSON : function() {
  69             return {
  70                 '*object' : 'SymbolSet',
  71                 _index : this._index
  72             };
  73
  74         },
  75
  76
  77         deleteSymbol : function(alias) {
  78             if (!this.hasSymbol(alias)) return;
  79             delete this._index[alias];
  80         },
  81
  82         renameSymbol : function(oldName, newName) {
  83             // todo: should check if oldname or newname already exist
  84             if (typeof(this._index[oldName]) == "undefined") {
  85                 throw "Cant rename " + oldName + " to " + newName + " As it doesnt exist";
  86                }
  87             this._index[newName] = this._index[oldName];
  88             this.deleteSymbol(oldName);
  89             this._index[newName].alias = newName;
  90             return newName;
  91         },
  92
  93         relate : function() {
  94             this.resolveBorrows();
  95             this.resolveMemberOf();
  96             this.resolveAugments();
  97         },
  98
  99         resolveBorrows : function() {
 100             for (p in this._index) {
 101                 var symbol = this._index[p];
 102                 if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
 103
 104                 var borrows = symbol.inherits;
 105                 for (var i = 0; i < borrows.length; i++) {
 106                     var borrowed = this.getSymbol(borrows[i].alias);
 107                     if (!borrowed) {
 108                         imports.BuildDocs.Options.LOG.warn("Can't borrow undocumented "+borrows[i].alias+".");
 109                         continue;
 110                     }
 111
 112                     var borrowAsName = borrows[i].as;
 113                     var borrowAsAlias = borrowAsName;
 114                     if (!borrowAsName) {
 115                         imports.BuildDocs.Options.LOG.warn("Malformed @borrow, 'as' is required.");
 116                         continue;
 117                     }
 118
 119                     if (borrowAsName.length > symbol.alias.length && borrowAsName.indexOf(symbol.alias) == 0) {
 120                         borrowAsName = borrowAsName.replace(borrowed.alias, "")
 121                     }
 122                     else {
 123                         var joiner = "";
 124                         if (borrowAsName.charAt(0) != "#") joiner = ".";
 125                         borrowAsAlias = borrowed.alias + joiner + borrowAsName;
 126                     }
 127
 128                     borrowAsName = borrowAsName.replace(/^[#.]/, "");
 129
 130                     if (this.hasSymbol(borrowAsAlias)) continue;
 131
 132                     var clone = borrowed.clone();
 133                     clone.name = borrowAsName;
 134                     clone.alias = borrowAsAlias;
 135                     this.addSymbol(clone);
 136                 }
 137             }
 138         },
 139
 140         resolveMemberOf : function() {
 141             for (var p in this._index) {
 142                 var symbol = this.getSymbol(p);
 143
 144                 if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
 145
 146                 // the memberOf value was provided in the @memberOf tag
 147                 else if (symbol.memberOf) {
 148                     var parts = symbol.alias.match(new RegExp("^("+symbol.memberOf+"[.#-])(.+)$"));
 149
 150                     // like foo.bar is a memberOf foo
 151                     if (parts) {
 152                         symbol.memberOf = parts[1];
 153                         symbol.name = parts[2];
 154                     }
 155                     // like bar is a memberOf foo
 156                     else {
 157                         var joiner = symbol.memberOf.charAt(symbol.memberOf.length-1);
 158                         if (!/[.#-]/.test(joiner)) symbol.memberOf += ".";
 159
 160                         this.renameSymbol(p, symbol.memberOf + symbol.name);
 161                     }
 162                 }
 163                 // the memberOf must be calculated
 164                 else {
 165                     var parts = symbol.alias.match(/^(.*[.#-])([^.#-]+)$/);
 166                     if (parts) {
 167                         symbol.memberOf = parts[1];
 168                         symbol.name = parts[2];
 169                     }
 170                 }
 171
 172                 // set isStatic, isInner
 173                 if (symbol.memberOf) {
 174                     switch (symbol.memberOf.charAt(symbol.memberOf.length-1)) {
 175                         case '#' :
 176                             symbol.isStatic = false;
 177                             symbol.isInner = false;
 178                             break;
 179
 180                         case '.' :
 181                             symbol.isStatic = true;
 182                             symbol.isInner = false;
 183                             break;
 184
 185                         case '-' :
 186                             symbol.isStatic = false;
 187                             symbol.isInner = true;
 188                             break;
 189
 190                     }
 191                 }
 192
 193                 // unowned methods and fields belong to the global object
 194                 if (!symbol.is("CONSTRUCTOR") && !symbol.isNamespace && symbol.memberOf == "") {
 195                     symbol.memberOf = "_global_";
 196                 }
 197
 198                 // clean up
 199                 if (symbol.memberOf.match(/[.#-]$/)) {
 200                     symbol.memberOf = symbol.memberOf.substr(0, symbol.memberOf.length-1);
 201                 }
 202                 //print("looking for memberOf: " + symbol.memberOf + " FOR " + symbol.alias);
 203                 // add to parent's methods or properties list
 204                 if (symbol.memberOf) {
 205                     var container = this.getSymbol(symbol.memberOf);
 206                     if (!container) {
 207                         if (SymbolSet.isBuiltin(symbol.memberOf)) {
 208                             container = imports.Parser.Parser.addBuiltin(symbol.memberOf);
 209                         }
 210                         else {
 211                            // print("symbol NOT a BUILT IN - createing a container");
 212                             // Eg. Ext.y.z (missing y)
 213                             // we need to add in the missing symbol...
 214                             container = new imports.Symbol.Symbol(symbol.memberOf, [], "OBJECT", new DocComment(""));
 215                             container.isNamespace = true;
 216                             this.addSymbol( container );
 217                            // print(container.toSource());
 218                             //container = this.getSymbol(symbol.memberOf);
 219                             // fake container ... so dont ad symbols to it..
 220                             continue;
 221                             container = false;
 222                             //LOG.warn("Can't document "+symbol.name +" as a member of undocumented symbol "+symbol.memberOf+".");
 223                             //LOG.warn("We only have the following symbols: \n" +
 224                             //    this.keys.toSource());
 225                         }
 226                     }
 227
 228                     if (container && !container.isNamespace) container.addMember(symbol);
 229                 }
 230             }
 231         },
 232
 233         resolveAugments : function() {
 234             // does this sort out multiple extends???
 235             for (var p in this._index) {
 236                 var symbol = this.getSymbol(p);
 237                 this.buildAugmentsList(symbol); /// build heirachy of inheritance...
 238                 if (symbol.alias == "_global_" || symbol.is("FILE")) continue;
 239
 240                 var augments = symbol.augments;
 241                 for(var ii = 0, il = augments.length; ii < il; ii++) {
 242                     var contributer = this.getSymbol(augments[ii]);
 243
 244
 245
 246                     if (contributer) {
 247                         contributer.childClasses.push(symbol.alias);
 248                         symbol.inheritsFrom.push(contributer.alias);
 249                         //if (!isUnique(symbol.inheritsFrom)) {
 250                         //    imports.BuildDocs.Options.LOG.warn("Can't resolve augments: Circular reference: "+symbol.alias+" inherits from "+contributer.alias+" more than once.");
 251                         //}
 252                         //else {
 253                             var cmethods = contributer.methods;
 254                             var cproperties = contributer.properties;
 255                             var cfgs = contributer.cfgs;
 256                             for (var ci = 0, cl = cmethods.length; ci < cl; ci++) {
 257                                 symbol.inherit(cmethods[ci]);
 258                             }
 259                             for (var ci = 0, cl = cproperties.length; ci < cl; ci++) {
 260                                 symbol.inherit(cproperties[ci]);
 261                             }
 262                             for (var ci in cfgs) {
 263                                 symbol.addConfig(cfgs[ci]);
 264                             }
 265
 266
 267                         //}
 268                     }
 269                     else {
 270
 271                         imports.BuildDocs.Options.LOG.warn("Can't augment contributer: '"+augments[ii]+"', not found. FOR: " + symbol.alias);
 272
 273                         //LOG.warn("We only have the following symbols: \n" +
 274                           //      this.keys().toSource().split(",").join(",    \n"));
 275                        }
 276
 277                 }
 278             }
 279         },
 280
 281         buildAugmentsList : function(symbol)
 282         {
 283             // basic idea is to add all the child extends to the parent.. without looping forever..
 284
 285             if (!symbol.augments.length) {
 286                 return;
 287             }
 288
 289             var _t = this;
 290             print("buildAugmentsList:" + symbol.alias);
 291             var addAugments = function (alist, forceit) { // returns number added..
 292                 if (!alist.length) {
 293                     return 0;
 294                 }
 295                 print("buildAugmentsList:addAugments" + alist.length);
 296                 var rval = 0;
 297                 for(var ii = 0; ii < alist.length; ii++) {
 298                     print("getAlias:" + alist[ii]);
 299                     if (alist[ii] == symbol.alias) {
 300                         continue;
 301                     }
 302                     var contributer = _t.getSymbol(alist[ii]);
 303                     if (!contributer) {
 304                         continue;
 305                     }
 306
 307                     if (!forceit && symbol.augments.indexOf(alist[ii]) > -1) {
 308                         continue;
 309                     }
 310                     if (symbol.augments.indexOf(alist[ii]) < 0) {
 311                         symbol.augments.push(alist[ii]);
 312                     }
 313
 314
 315                     addAugments(contributer.augments,false);
 316
 317                     rval++;
 318                 }
 319                 print("buildAugmentsList: ADDED:" + rval);
 320                 return rval;
 321             }
 322             addAugments(symbol.augments, true);
 323             //while(addAugments(symbol.augments) >  0) { }
 324
 325         }
 326
 327 })
 328
 329 SymbolSet.isBuiltin = function(name) {
 330     return (SymbolSet.isBuiltin.coreObjects.indexOf(name) > -1);
 331 }
 332 SymbolSet.isBuiltin .coreObjects = [
 333     '_global_', 'Array', 'Boolean', 'Date', 'Function',
 334     'Math', 'Number', 'Object', 'RegExp', 'String'
 335 ];