git.roojs.org Git - app.jsdoc/blob - JSDOC/ScopeNamer.js

   1 XObject = imports.XObject.XObject;
   2
   3
   4 console     = imports.console.console;
   5
   6 Symbol = imports.Symbol.Symbol;
   7
   8 /**
   9  * @class ScopeNamer
  10  * @extends Collapse
  11  * @scope JSDOC
  12  * The point of this class is to iterate through the Collapsed tree
  13  * and add the property 'scopedName' to the tokens.
  14  *
  15  *
  16  *
  17
  18   After spending some time looking at this, a few conclusions...
  19
  20   - this will have to be the base class of specific implementations.
  21   - each implementation will have to decide how to declare a new scope
  22
  23   scopes are normally changed when these things occur:
  24
  25
  26   globalScope(stmts) => statementsScope($global$, stmts)
  27
  28
  29   'object'
  30   objectScope(sname, props  )
  31   a = { .... } << scope is a  $this$={a}
  32
  33      // property scopes???
  34     foo: function() {} $this$={object scope}
  35     foo : ( xxx ? function()  { } ? function() { ...} << conditional properties types
  36     foo : (function() { return x })() << a property or function??? << depends on notes
  37     foo : [ ] << a property.. do not drill down?
  38     foo : xxxxx << a property..
  39
  40
  41   'function'
  42   functionScope(sname,  stmts  )
  43   function a() { .... } << scope is a  $this$={a}
  44   a = function() { } << scope might be a  $this$={a}
  45
  46   // registers 'this.*'
  47
  48
  49
  50   'call' scopes
  51   XX.yy(a,b, { .... }) << scope might be a or b..  $this$={a}
  52   aa = XX.yy(a,b, { .... }) << scope might aa   $this$={a}
  53
  54   callscope(name, pref, args)
  55
  56   can do losts ofthings
  57
  58    ?? classify me...
  59       foo = new (function() { }
  60      (function() { }
  61     RETURN function(...) {
  62
  63
  64
  65
  66
  67
  68
  69  *
  70  *
  71  * usage  :
  72  * sn = new ScopeName({
  73     tokens : ... result from tokenizer,
  74
  75  })
  76    sn.buildSymbols();
  77  *
  78  * @param {Array} tokens array of tokens (from collapse)
  79  * @param {String} srcFile the original file
  80  * @param {Array} args Local variables which do not need to be added to scope.
  81  */
  82
  83 ScopeNamer = XObject.define(
  84     function (cfg)
  85     {
  86
  87         ScopeNamer.superclass.constructor.call(this, cfg);
  88         this.args = this.args ? this.args.slice(0)  : [];
  89         Symbol.srcFile = this.filename;
  90         this.createJSDOC = true;
  91         this.global = '_global_';
  92        // console.dump(ar);
  93
  94     },
  95     imports.JSDOC.Collapse.Collapse,
  96     {
  97
  98         global : false,
  99         /**
 100          * Call debugging
 101          * add/remove ';' after return to configure at present..
 102          * @param {String} str String to output
 103          */
 104         debugCall : function(str)  {
 105
 106
 107             //if (this.filename.match(/Scope\.js/)) return print(str);
 108             return;
 109         },
 110
 111         collapseTop : true,
 112
 113         buildSymbols : function()
 114         {
 115             if (!this.statements) {
 116                 this.statements = this.collapse(this.tokens);
 117                 //print(JSON.stringify(this.s, null,4));
 118             }
 119
 120             //this.globalScope(this.statements);
 121             this.debugCall("build Symbols");
 122             //print (this.statements);
 123             //print (JSON.stringify(this.statements, null,2));
 124
 125             this.walkStatements(this.global, this.statements)
 126
 127
 128
 129         },
 130
 131
 132         ignore : false,
 133
 134
 135
 136
 137         walkStatements: function(scope, statements)
 138         {
 139             this.debugCall("walkStatements :" + scope ) ;
 140             var _this = this;
 141             var res = false;
 142             var isGlobal = scope == this.global;
 143
 144             statements.some(function(st ) {
 145                 // handle change of scope..
 146                 if (isGlobal &&
 147                         st[0].jsdoc &&
 148                         st[0].jsdoc.getTag('scope').length
 149                    ) {
 150                     //print(st[0].jsdoc.getTag('scope'));
 151                     scope = st[0].jsdoc.getTag('scope');
 152                     // might be an array..
 153                     if (typeof(scope) != 'String') {
 154                         scope = scope[0].desc;
 155
 156                     }
 157                     _this.global = scope;
 158                 }
 159
 160
 161                 res = _this.walkStatement(scope, st);
 162                 if (res === true) {
 163                     return true;
 164                 }
 165                 return false;
 166             });
 167         },
 168
 169         walkStatement: function(scope, stmt)
 170         {
 171             this.tokens = stmt;
 172             this.rewind();
 173             this.debugCall("walkStatement :" + this.global +'/' +scope + '@' + this.tokens[0].line );
 174
 175             var name;
 176             var sn;
 177
 178             var isGlobal = scope == this.global;
 179
 180
 181
 182             //if (this.filename.match(/pack\.js/) && isGlobal) {
 183             //    print(JSON.stringify(stmt , null,4));
 184             //}
 185             // @ignore stops the parser..
 186             if (isGlobal &&
 187                     stmt[0].jsdoc &&
 188                     stmt[0].jsdoc.getTag('ignore').length
 189                ) {
 190                 this.debugCall("walkStatement : ignore found - " + scope + '@' + this.tokens[0].line );
 191                 print("GOT ignore?");
 192                 return true;
 193             }
 194
 195
 196             while (null != (token = this.next())) {
 197
 198                 //'function'
 199                 //walkFunction(scope, name , args,  stmts  )
 200                 //
 201                 if (token.name == "FUNCTION") {
 202                     // function a() { .... } << scope is a  $this$={a}
 203                     if (this.lookTok(1).is('NAME')) {
 204                         name = isGlobal ? this.lookTok(1).data : '';
 205
 206                         this.walkFunctionDef(scope, name, this.lookTok(2).args, this.lookTok(3).items, token);
 207                         continue;
 208                     }
 209                      //a = function() { } << scope might be a  $this$={a}
 210                     if (this.lookTok(-1).data == '=' &&
 211                         this.lookTok(-2).is('NAME')
 212                     ) {
 213
 214                         name = this.lookTok(-2).data;
 215
 216                         if (!isGlobal) {
 217                             // only this.*
 218                             if (this.lookTok(-3).name == 'VAR') {
 219                                 name = '';
 220                             }
 221                             if (name.match(/^this\./) && scope.match(/\.prototype$/)) {
 222                                 name = name.substring(5);
 223                             }
 224                             if (name.split('.').length > 1) {
 225                                 name = '';
 226                             }
 227
 228                         }
 229
 230
 231                         this.walkFunctionDef(scope, name, this.lookTok(1).args, this.lookTok(2).items, this.lookTok(-2));
 232                         continue;
 233                     }
 234
 235
 236                     print("+++ FUNCTION unusual context" + token.file + ':' + token.line);
 237                     continue;
 238
 239                 }
 240
 241                 // control flow ...
 242
 243
 244
 245                 // 'call' scopes
 246                 // XX.yy(a,b, { .... }) << scope might be a or b..  $this$={a}
 247                 // aa = XX.yy(a,b, { .... }) << scope might aa   $this$={a}
 248
 249                 if (token.is('NAME') && this.lookTok(1).data =='(') {
 250                     var assign = false;
 251                     var jsdoc = token.jsdoc;
 252                     if ((this.lookTok(-1).data == '=') && this.lookTok(-2).is('NAME')) {
 253                         assign = this.lookTok(-2).data
 254                         jsdoc = jsdoc || this.lookTok(-2).jsdoc;
 255                     }
 256                     this.walkCall(scope, assign, token.data, this.lookTok(1).items, jsdoc);
 257                     continue;
 258                 }
 259
 260                 //  'object'
 261                 //   a = { .... } << scope is a  $this$={a}
 262                 if (token.data == '{' && this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
 263
 264                     // could be var x = ..
 265                     var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
 266
 267                     var isVar = this.lookTok(-3).name == 'VAR';
 268
 269                     // only register names of objects if
 270                     var name = this.lookTok(-2).data;
 271
 272                     // some a = {} can be hidden
 273                     // using @type {string} for example.
 274                     // FIXME - they should be registered as a property...
 275                     if (jd && jd.jsdoc && jd.jsdoc.getTag('type').length) {
 276
 277
 278                         name = false;
 279                     }
 280
 281
 282
 283
 284                     if (!isGlobal) {
 285                         // not global.
 286                         if (isVar) {
 287                             name = false;
 288                         }
 289                         if (name && !name.match(/^this\./)) {
 290                             name = false;
 291                         }
 292                         if (name && name.match(/^this\./) ) {
 293                             // see if scope ends in prototype..
 294                             print("SCOPE:" + JSON.stringify(scope));
 295                             if (
 296                                 (scope.split('.').pop() == 'prototype') &&
 297                                 (name.split('.').length == 2)
 298                             ){
 299                                 name = name.split('.').pop();
 300                             } else {
 301                                 name = false;
 302                             }
 303
 304                         }
 305
 306                     }
 307
 308
 309                     //print(JSON.stringify(token,null,4));
 310                     this.walkObject(scope, name, token.props, jd);
 311                     continue;
 312                 }
 313
 314                 // this.xxxx = (with jsdoc...)
 315
 316
 317
 318
 319                 // standard flow....
 320                 if (token.data == '{') {
 321                     sn = new ScopeNamer(this);
 322                     //print("GOT { - walkings statuements;}");
 323                     if (!token.items) {
 324                         continue; // object..!?!?!? = ignore ???
 325                         print(JSON.stringify(token,null,4));
 326                     }
 327                     sn.walkStatements(scope, token.items);
 328                     continue;
 329                 }
 330             }
 331         },
 332
 333         walkFunctionDef : function (inscope, name, args, stmts, jsdocTok)
 334         {
 335             this.debugCall("wallkFuncDef: " + inscope + '#' + name + '@' + this.look(0).line );
 336             var scope = name.length ? (inscope + '.' + name) : inscope;
 337             if (name.length) {
 338                 var symbol = new Symbol( scope , args || [] , "FUNCTION" ,  jsdocTok.jsdoc);
 339                 symbol._token = jsdocTok;
 340                 this.addSymbol(symbol, jsdocTok.jsdoc);
 341             }
 342             var sn = new ScopeNamer(this);
 343             sn.walkStatements(scope, stmts);
 344
 345         },
 346
 347
 348
 349         walkCall : function (inscope, assign, callname, items, jsdocTok)
 350         {
 351             this.debugCall("walkCall : " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 352             var scope = inscope + ( assign ? ('.' + assign) : '' );
 353             //scope = scope.replace(/\^_global\$\./, '');
 354
 355
 356
 357
 358             // add the handers for differnt methods in here....
 359             switch (callname) {
 360
 361                 // somecall(BASE, { .. object ..})
 362                 // or... x = somecall(BASE, { ... object..})
 363                 case 'XObject.extend':
 364                 case 'Roo.apply':
 365                     //print(JSON.stringify(items,null,4));
 366                     // SHOULD WE ADD SCOPE HERE???
 367                     var topscope = scope.split('.').pop();
 368
 369                     scope = (topscope == items[0][0].data) ?
 370                         items[0][0].data :
 371                         scope + '.' + items[0][0].data;
 372                     // 2nd arg is a object def
 373                     if (items[1][0].data != '{') {
 374                         return;
 375                     }
 376
 377                     if (assign != false   && !scope.match(/\.prototype$/)) {
 378                         var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok);
 379                         symbol._token = jsdocTok;
 380                         this.addSymbol(symbol, jsdocTok.jsdoc);
 381
 382                     }
 383
 384
 385                     var sn = new ScopeNamer(this);
 386
 387                     //print(JSON.stringify(items,null,4));
 388                     sn.walkObject(scope , false, items[1][0].props, jsdocTok );
 389
 390                     return;
 391
 392
 393
 394
 395                 case 'XObject.define':
 396                     // func, extends, props.
 397
 398                     var symbol = new Symbol( scope , items[0][1].args || [] , "CONSTRUCTOR" ,  jsdocTok);
 399                     symbol._token = jsdocTok;
 400                     // extends = arg[1]
 401
 402                     this.addSymbol(symbol, jsdocTok.jsdoc);
 403                     var sn = new ScopeNamer(this);
 404                     //print(JSON.stringify(items, null,4));
 405                     // ctr statements.
 406                     sn.walkStatements(scope + '.prototype', items[0][2].items);
 407
 408
 409                     sn.walkObject(scope + '.prototype', false, items[2][0].props );
 410                     return;
 411
 412
 413
 414             }
 415
 416
 417
 418         },
 419
 420         walkObject : function(inscope, name, items, jsdocTok)
 421         {
 422             var scope = inscope + (( name === false) ? '' : ('.' + name));
 423
 424             if (name !== false) {
 425
 426                 var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok.jsdoc);
 427                 symbol._token = jsdocTok;
 428                 this.addSymbol(symbol, jsdocTok.jsdoc);
 429
 430             }
 431             // items can be false in this scenaro: a = {};
 432             if (!items) {
 433                 return;
 434             }
 435             print(typeof(items));
 436             this.debugCall("wallkObject : " + scope + '#' + name + '@' + items[Object.keys(items)[0]].key.line);
 437             for( var k in items) {
 438                 var key = items[k].key;
 439                 var val = items[k].val;
 440
 441
 442                 // x : function(....)
 443                 if (val[0].name == 'FUNCTION' ) {
 444
 445
 446                     this.walkFunctionDef (scope, k, val[1].args, val[2].items, key)
 447
 448
 449                     continue;
 450                 }
 451
 452                 // x: ( .... ) conditional  properties? maybe detect function?
 453
 454
 455                 // x : something else - not a function..
 456
 457
 458                 var symbol = new Symbol( scope +'.'+ k , val[1].args || [] , "PROPERTY" ,  key.jsdoc);
 459                 symbol._token = key;
 460
 461                 this.addSymbol(symbol, key.jsdoc);
 462                 continue;
 463
 464
 465             }
 466
 467
 468         },
 469
 470
 471
 472
 473
 474
 475         addSymbol: function(symbol, comment)
 476         {
 477               //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 478               //print("PARSER addSYMBOL : " + symbol.alias);
 479
 480             // if a symbol alias is documented more than once the last one with the user docs wins
 481
 482             // dumpe some invalid symbols..
 483             var ptype_ar = symbol.alias.split(/#/);
 484             if (ptype_ar.length > 2) {
 485                 // multiple #
 486                 return;
 487             }
 488             if (ptype_ar.length > 1 && ptype_ar[1].split(/\./).length > 1) {
 489                 // multiple . after #
 490                 return;
 491             }
 492
 493             ScopeNamer.prototype.debugCall("addSymbol : " + symbol.alias );
 494
 495             if (ScopeNamer.symbols.hasSymbol(symbol.alias)) {
 496
 497                 if (!comment) { // we do not have a comment, and it's registered.
 498                     return;
 499                 }
 500                 var oldSymbol = ScopeNamer.symbols.getSymbol(symbol.alias);
 501
 502                 if (oldSymbol.comment && oldSymbol.comment.isUserComment && !oldSymbol.comment.hasTags) {
 503                     if (symbol.comment.isUserComment) { // old and new are both documented
 504                         this.LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
 505                     }
 506                     else { // old is documented but new isn't
 507                         return;
 508                     }
 509                 }
 510             }
 511
 512             // we don't document anonymous things
 513             //if (this.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
 514
 515             // uderscored things may be treated as if they were marked private, this cascades
 516             //if (this.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 517             //    symbol.isPrivate = true;
 518             //}
 519
 520             // -p flag is required to document private things
 521             if ((symbol.isInner || symbol.isPrivate) && !this.docPrivate) return;
 522
 523             // ignored things are not documented, this doesn't cascade
 524             if (symbol.isIgnored) return;
 525
 526
 527             //print("ADD symbol: " + symbol.isa + ' => ' + symbol.alias );
 528             //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 529
 530             // add it to the file's list... (for dumping later..)
 531             if (this.srcFile) {
 532                 ScopeNamer.filesSymbols[Symbol.srcFile].addSymbol(symbol);
 533             }
 534
 535             ScopeNamer.symbols.addSymbol(symbol);
 536         },
 537         addBuiltin : function(name) {
 538
 539             var builtin = new Symbol(name, [], "CONSTRUCTOR", new imports.DocComment.DocComment(""));
 540             builtin.isNamespace = false;
 541             builtin.srcFile = "";
 542             builtin.isPrivate = false;
 543             this.addSymbol(builtin);
 544             return builtin;
 545         }
 546
 547
 548
 549     }
 550 );
 551
 552 ScopeNamer.symbols =  new  imports.SymbolSet.SymbolSet();
 553
 554
 555
 556
 557
 558 ScopeNamer.addSymbol = ScopeNamer.prototype.addSymbol;
 559 ScopeNamer.addBuiltin = ScopeNamer.prototype.addBuiltin;