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 JSDOC.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         this.locals = this.locals || [];
  93        // console.dump(ar);
  94
  95     },
  96     imports.JSDOC.Collapse.Collapse,
  97     {
  98
  99         global : false,
 100         /**
 101          * Call debugging
 102          * add/remove ';' after return to configure at present..
 103          * @param {String} str String to output
 104          */
 105         debugCall : function(str)  {
 106
 107
 108            // if (this.filename.match(/Date\.js/)) return print(str);
 109             return;
 110         },
 111
 112         collapseTop : true,
 113
 114         buildSymbols : function()
 115         {
 116             if (!this.statements) {
 117                 this.statements = this.collapse(this.tokens);
 118                 //print(JSON.stringify(this.s, null,4));
 119             }
 120             //if (this.filename.match(/Roo\.js/)) print(JSON.stringify(this.statements, null,4));
 121             //this.globalScope(this.statements);
 122             this.debugCall("build Symbols");
 123             //print (this.statements);
 124             //print (JSON.stringify(this.statements, null,2));
 125
 126             this.walkStatements(this.global, this.statements)
 127
 128
 129
 130         },
 131
 132
 133         ignore : false,
 134
 135
 136
 137
 138         walkStatements: function(scope, statements)
 139         {
 140             this.debugCall("walkStatements :" + scope + '@' + statements[0][0].line) ;
 141             var _this = this;
 142             var res = false;
 143             var isGlobal = scope == this.global;
 144
 145
 146
 147             statements.some(function(st ) {
 148                 // handle change of scope..
 149                 if (isGlobal &&
 150                         st[0].jsdoc &&
 151                         st[0].jsdoc.getTag('scope').length
 152                    ) {
 153
 154
 155                     scope = st[0].jsdoc.getTag('scope');
 156                     // might be an array..
 157                     if (typeof(scope) != 'String') {
 158                         scope = scope[0].desc;
 159
 160                     }
 161                     print("SCOPE CHANGE TO:" + scope);
 162                     _this.global = scope;
 163                 }
 164
 165
 166                 res = _this.walkStatement(scope, st);
 167                 if (res === true) {
 168                     return true;
 169                 }
 170                 return false;
 171             });
 172         },
 173
 174         walkStatement: function(scope, stmt)
 175         {
 176             this.tokens = stmt;
 177             this.rewind();
 178             this.debugCall("walkStatement :" + this.global +'/' +scope + '@' + this.tokens[0].line );
 179
 180             var name;
 181             var sn;
 182             var token = false;
 183
 184             var isGlobal = scope ==   this.global;
 185
 186
 187
 188             //if (this.filename.match(/pack\.js/) && isGlobal) {
 189             //    print(JSON.stringify(stmt , null,4));
 190             //}
 191             // @ignore stops the parser..
 192             if (isGlobal &&
 193                     stmt[0].jsdoc &&
 194                     stmt[0].jsdoc.getTag('ignore').length
 195                ) {
 196                 this.debugCall("walkStatement : ignore found - " + scope + '@' + this.tokens[0].line );
 197                 print("GOT ignore?");
 198                 return true;
 199             }
 200
 201
 202             while (null != (token = this.next())) {
 203
 204
 205                 // var xx =
 206
 207
 208
 209                 //'function'
 210                 //walkFunction(scope, name , args,  stmts  )
 211                 //
 212                 if (token.name == "FUNCTION") {
 213                     // function a() { .... } << scope is a  $this$={a}
 214                     if (this.lookTok(1).is('NAME')) {
 215                         name = isGlobal ? this.lookTok(1).data : '';
 216
 217                         this.walkFunctionDef(scope, name, this.lookTok(2).args, this.lookTok(3).items, token);
 218                         this.next();
 219                         this.next();
 220                         this.next();
 221                         continue;
 222                     }
 223                      //a = function() { } << scope might be a  $this$={a}
 224                     if (this.lookTok(-1).data == '=' &&
 225                         this.lookTok(-2).is('NAME')
 226                     ) {
 227
 228                         name = this.lookTok(-2).data;
 229
 230                         if (!isGlobal) {
 231                             // only this.*
 232                             if (this.lookTok(-3).name == 'VAR') {
 233                                 name = '';
 234                             }
 235                             if (name.match(/^this\./) && scope.match(/\.prototype$/)) {
 236                                 name = name.substring(5);
 237                             }
 238                             if (name.split('.').length > 1) {
 239                                 name = '';
 240                             }
 241
 242                         }
 243
 244
 245                         this.walkFunctionDef(scope, name, this.lookTok(1).args, this.lookTok(2).items, this.lookTok(-2));
 246                         this.next();
 247                         this.next();
 248                         continue;
 249                     }
 250
 251
 252                     print("+++ FUNCTION unusual context" + token.file + ':' + token.line);
 253                     continue;
 254
 255                 }
 256
 257                 // control flow ...
 258
 259
 260
 261                 // 'call' scopes
 262                 // XX.yy(a,b, { .... }) << scope might be a or b..  $this$={a}
 263                 // aa = XX.yy(a,b, { .... }) << scope might aa   $this$={a}
 264
 265                 if (token.is('NAME') && this.lookTok(1).data =='(') {
 266                     var assign = false;
 267                     var jsdoc = token.jsdoc;
 268                     if ((this.lookTok(-1).data == '=') && this.lookTok(-2).is('NAME')) {
 269                         assign = this.lookTok(-2).data
 270                         jsdoc = jsdoc || this.lookTok(-2).jsdoc;
 271                     }
 272                     this.walkCall(scope, assign, token.data, this.lookTok(1).items, jsdoc);
 273                     this.next();
 274
 275                     continue;
 276                 }
 277
 278                 //  'object'
 279                 //   a = { .... } << scope is a  $this$={a}
 280                 if (token.data == '{' && this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
 281
 282                     // could be var x = ..
 283                     var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
 284
 285                     var isVar = this.lookTok(-3).name == 'VAR';
 286
 287                     // only register names of objects if
 288                     var name = this.lookTok(-2).data;
 289
 290                     // some a = {} can be hidden
 291                     // using @type {string} for example.
 292                     // FIXME - they should be registered as a property...
 293                     if (jd && jd.jsdoc && jd.jsdoc.getTag('type').length) {
 294
 295                         //name = false;
 296                         //continue;
 297                         // wipe out the children..
 298                         token.props = false;
 299                     }
 300                     /*
 301                     print(JSON.stringify({
 302                         name : name,
 303                         isGlobal : isGlobal,
 304                         isVar : isVar
 305                     }, null,4));
 306                     */
 307
 308                     if (!isGlobal) {
 309                         // not global.
 310                         if (isVar) {
 311                             if (name && this.locals.indexOf(name) < 0) {
 312                                 this.locals.push(name);
 313                             }
 314                             name = false;
 315                             continue;
 316                         }
 317                         if (this.locals.indexOf(name) > -1 ) {
 318                             continue;
 319                         }
 320
 321
 322                         if (name && !name.match(/^this\./)) {
 323                             name = false;
 324                         }
 325                         if (name && name.match(/^this\./) ) {
 326                             // see if scope ends in prototype..
 327                             //print("q" + JSON.stringify(scope));
 328                             if (
 329                                 (scope.split('.').pop() == 'prototype') &&
 330                                 (name.split('.').length == 2)
 331                             ){
 332                                 name = name.split('.').pop();
 333                             } else {
 334                                 name = false;
 335                             }
 336
 337                         }
 338
 339                     }
 340
 341
 342                     //print(JSON.stringify(token,null,4));
 343                     this.walkObject(scope, name, token.props, jd);
 344                     continue;
 345                 }
 346
 347
 348
 349
 350
 351                  //  'assignment..'
 352                  // it's done on the third element to enable object assignment to work above..
 353                 //   a = .....
 354
 355                 if (this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
 356
 357
 358
 359                     // could be var x = ..
 360                     var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
 361
 362                     var isVar = this.lookTok(-3).name == 'VAR';
 363
 364                     // only register names of objects if
 365                     var name = this.lookTok(-2).data;
 366
 367                     // some a = {} can be hidden
 368                     // using @type {string} for example.
 369                     // FIXME - they should be registered as a property...
 370                     if (jd && jd.jsdoc && jd.jsdoc.getTag('type').length) {
 371
 372                         //name = false;
 373                         //continue;
 374                         // wipe out the children..
 375                         token.props = false;
 376                     }
 377                     /*
 378                     print(JSON.stringify({
 379                         name : name,
 380                         isGlobal : isGlobal,
 381                         isVar : isVar
 382                     }, null,4));
 383                     */
 384
 385                     // skip imports.
 386                     if (token.data.match(/imports\./)) {
 387                         name = false;
 388                     }
 389
 390
 391                     if (!isGlobal) {
 392                         // not global.
 393                         if (isVar) {
 394                             if (name && this.locals.indexOf(name) < 0) {
 395                                 this.locals.push(name);
 396                             }
 397                             name = false;
 398                             continue;
 399                         }
 400                         if (this.locals.indexOf(name) > -1 ) {
 401                             continue;
 402                         }
 403
 404                         if (name && !name.match(/^this\./)) {
 405                             name = false;
 406                         }
 407
 408
 409                         if (name && name.match(/^this\./) ) {
 410                             // see if scope ends in prototype..
 411                             //print("SCOPE:" + JSON.stringify(scope));
 412                             if (
 413                                 (scope.split('.').pop() == 'prototype') &&
 414                                 (name.split('.').length == 2)
 415                             ){
 416                                 name = name.split('.').pop();
 417                             } else {
 418                                 name = false;
 419                             }
 420
 421                         }
 422
 423                     } else {
 424                         // should not happen...
 425                         if (name && name.match(/^this\./)) {
 426                             name = false;
 427                         }
 428                     }
 429
 430
 431                     if (name) {
 432                         var symbol = new Symbol( scope +'.'+ name , false , "PROPERTY" ,  jd.jsdoc);
 433                         symbol._token = this.lookTok(-2);
 434
 435                         this.addSymbol(symbol, jd.jsdoc);
 436
 437                     }
 438                     // including ... aaa = new BBB({
 439
 440                     if (token.data == 'new' && !isVar && name) {
 441                         var mname = this.lookTok(1).data;
 442                         var args = this.lookTok(2).items; // (
 443
 444                         if (args[0].data == '{') {
 445
 446                             this.walkObject( scope +'.'+ name, false, args[0].props, false);
 447
 448                             // have a go at applying the properties..
 449
 450                         }
 451                         this.next();
 452                         this.next();
 453
 454
 455                     }
 456
 457                     continue;
 458
 459                 }
 460
 461                 // TODO:
 462                 // this.xxxx = (with jsdoc...)
 463
 464
 465
 466
 467
 468                 // standard flow... - ignore opening {.
 469                 if (token.data == '{') {
 470                     sn = new ScopeNamer(this);
 471                     //print("GOT { - walkings statuements;}");
 472                     if (!token.items) {
 473                         continue; // object..!?!?!? = ignore ???
 474                         print(JSON.stringify(token,null,4));
 475                     }
 476
 477
 478                     //print ("GOT { = running walk statemengs on children?} @" + this.cursor);
 479                     sn.walkStatements(scope, token.items);
 480                     continue;
 481                 }
 482                   if (this.filename.match(/Roo\.js/)   && token.data == '(')  {
 483                     //print(JSON.stringify(token,null,4));
 484
 485                   }
 486                 // ( function() {
 487                 if ((token.data == '(') && (token.items[0][0].data == 'function')) {
 488                     sn = new ScopeNamer(this);
 489                     sn.walkStatements('_private_', token.items[0][2].items);
 490                     continue;
 491
 492                 }
 493
 494
 495
 496             }
 497
 498              this.debugCall("walkStatement (END):" + this.global +'/' +scope + '@' + this.tokens[0].line );
 499
 500         },
 501
 502         walkFunctionDef : function (inscope, name, args, stmts, jsdocTok)
 503         {
 504             this.debugCall("wallkFuncDef: " + inscope + '#' + name + '@' + this.look(0).line );
 505             var scope = name.length ? (inscope + '.' + name) : inscope;
 506             if (name.length) {
 507                 var symbol = new Symbol( scope , args || [] , "FUNCTION" ,  jsdocTok.jsdoc);
 508                 symbol._token = jsdocTok;
 509                 this.addSymbol(symbol, jsdocTok.jsdoc);
 510             }
 511             var sn = new ScopeNamer(this);
 512
 513             sn.walkStatements(scope, stmts);
 514             this.debugCall("wallkFuncDef:  (END)" + inscope + '#' + name + '@' + this.look(0).line );
 515         },
 516
 517
 518
 519         walkCall : function (inscope, assign, callname, items, jsdocTok)
 520         {
 521             this.debugCall("walkCall : " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 522             var scope = inscope + ( assign ? ('.' + assign) : '' );
 523             //scope = scope.replace(/\^_global\$\./, '');
 524
 525
 526
 527
 528             // add the handers for differnt methods in here....
 529             switch (callname) {
 530
 531                 // somecall(BASE, { .. object ..})
 532                 // or... x = somecall(BASE, { ... object..})
 533                 case 'XObject.extend':
 534                 case 'Roo.apply':
 535                 case 'Roo.applyIf':
 536                     //print(JSON.stringify(items,null,4));
 537                     // SHOULD WE ADD SCOPE HERE???
 538
 539                     var arg0 = items[0][0].data;
 540
 541                     var topscope = scope.split('.').pop();
 542
 543                     scope = (topscope == arg0) ? arg0 : scope + '.' + arg0;
 544
 545                     // see if arg0 is defined has a symbol..
 546                     if (this.haveSymbol(arg0)) {
 547                         scope = arg0;
 548                     }
 549
 550
 551                     // 2nd arg is a object def
 552                     if (items[1][0].data != '{') {
 553                         return;
 554                     }
 555
 556                     if (assign != false   && !scope.match(/\.prototype$/)) {
 557                         var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok);
 558                         symbol._token = jsdocTok;
 559                         this.addSymbol(symbol, jsdocTok.jsdoc);
 560
 561                     }
 562
 563
 564                     var sn = new ScopeNamer(this);
 565
 566                     //print(JSON.stringify(items,null,4));
 567                     sn.walkObject(scope , false, items[1][0].props, jsdocTok );
 568                     this.debugCall("walkCall(END): " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 569
 570                     return;
 571
 572
 573
 574
 575                 case 'XObject.define':
 576                     // func, extends, props.
 577
 578                     var symbol = new Symbol( scope , items[0][1].args || [] , "CONSTRUCTOR" ,  jsdocTok);
 579                     symbol._token = jsdocTok;
 580                     // extends = arg[1]
 581
 582                     this.addSymbol(symbol, jsdocTok.jsdoc);
 583                     var sn = new ScopeNamer(this);
 584                     //print(JSON.stringify(items, null,4));
 585                     // ctr statements.
 586                     sn.walkStatements(scope + '.prototype', items[0][2].items);
 587
 588
 589                     sn.walkObject(scope + '.prototype', false, items[2][0].props );
 590                     this.debugCall("walkCall(END): " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 591
 592                     return;
 593
 594
 595
 596             }
 597
 598             this.debugCall("walkCall(END): " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 599
 600
 601         },
 602
 603         walkObject : function(inscope, name, items, jsdocTok)
 604         {
 605             var scope = inscope + (( name === false) ? '' : ('.' + name));
 606
 607             if (name !== false) {
 608
 609                 var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok.jsdoc);
 610                 symbol._token = jsdocTok;
 611                 this.addSymbol(symbol, jsdocTok.jsdoc);
 612
 613             }
 614             // items can be false in this scenaro: a = {};
 615             if (!items) {
 616                 return;
 617             }
 618             // our other scenario is where something is flagged as private, we will not investigate further
 619             // we do add it however..
 620             if (jsdocTok && jsdocTok.jsdoc && jsdocTok.jsdoc.getTag('private').length) {
 621                 return;
 622             }
 623
 624             //print(typeof(items));
 625             this.debugCall("wallkObject : " + scope + '#' + name + '@' + items[Object.keys(items)[0]].key.line);
 626             for( var k in items) {
 627                 var key = items[k].key;
 628                 var val = items[k].val;
 629
 630
 631                 // x : function(....)
 632                 if (val[0].name == 'FUNCTION' ) {
 633
 634
 635                     this.walkFunctionDef (scope, k, val[1].args, val[2].items, key)
 636
 637
 638                     continue;
 639                 }
 640
 641                 // x: ( .... ) conditional  properties? maybe detect function?
 642
 643
 644                 // x : something else - not a function..
 645
 646
 647                 var symbol = new Symbol( scope +'.'+ k , val[1].args || [] , "PROPERTY" ,  key.jsdoc);
 648                 symbol._token = key;
 649
 650                 this.addSymbol(symbol, key.jsdoc);
 651                 continue;
 652
 653
 654             }
 655
 656
 657         },
 658
 659
 660
 661
 662
 663
 664         addSymbol: function(symbol, comment)
 665         {
 666               //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 667               //print("PARSER addSYMBOL : " + symbol.alias);
 668
 669             // if a symbol alias is documented more than once the last one with the user docs wins
 670
 671             // dumpe some invalid symbols..
 672             var ptype_ar = symbol.alias.split(/#/);
 673             if (ptype_ar.length > 2) {
 674                 // multiple #
 675                 return;
 676             }
 677             if (ptype_ar.length > 1 && ptype_ar[1].split(/\./).length > 1) {
 678                 // multiple . after #
 679                 return;
 680             }
 681
 682             ScopeNamer.prototype.debugCall("addSymbol : " + symbol.alias );
 683
 684             if (ScopeNamer.symbols.hasSymbol(symbol.alias)) {
 685
 686                 if (!comment) { // we do not have a comment, and it's registered.
 687                     return;
 688                 }
 689                 var oldSymbol = ScopeNamer.symbols.getSymbol(symbol.alias);
 690
 691                 if (oldSymbol.comment && oldSymbol.comment.isUserComment && !oldSymbol.comment.hasTags) {
 692                     if (symbol.comment.isUserComment) { // old and new are both documented
 693                         this.LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
 694                     }
 695                     else { // old is documented but new isn't
 696                         return;
 697                     }
 698                 }
 699             }
 700
 701             // we don't document anonymous things
 702             //if (this.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
 703
 704             // uderscored things may be treated as if they were marked private, this cascades
 705             //if (this.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 706             //    symbol.isPrivate = true;
 707             //}
 708             if (ScopeNamer.builder.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 709                 symbol.isPrivate = true;
 710             }
 711             // -p flag is required to document private things
 712             //if ((symbol.isInner || symbol.isPrivate) && !this.docPrivate) return;
 713
 714             // ignored things are not documented, this doesn't cascade
 715             if (symbol.isIgnored) return;
 716
 717             //print("ADD symbol: " + symbol.isa + ' => ' + symbol.alias );
 718             //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 719
 720             // add it to the file's list... (for dumping later..)
 721             if (this.srcFile) {
 722                 ScopeNamer.filesSymbols[Symbol.srcFile].addSymbol(symbol);
 723             }
 724
 725             ScopeNamer.symbols.addSymbol(symbol);
 726         },
 727
 728         haveSymbol: function(name)
 729         {
 730             return ScopeNamer.symbols.hasSymbol(name);
 731         },
 732
 733         addBuiltin : function(name) {
 734
 735             var builtin = new Symbol(name, [], "CONSTRUCTOR", new imports.DocComment.DocComment(""));
 736             builtin.isNamespace = false;
 737             builtin.srcFile = "";
 738             builtin.isPrivate = false;
 739             this.addSymbol(builtin);
 740             return builtin;
 741         }
 742
 743
 744
 745     }
 746 );
 747
 748 ScopeNamer.symbols =  new  imports.SymbolSet.SymbolSet();
 749
 750
 751
 752
 753
 754 ScopeNamer.addSymbol = ScopeNamer.prototype.addSymbol;
 755 ScopeNamer.addBuiltin = ScopeNamer.prototype.addBuiltin;