1 XObject = imports.XObject.XObject;
4 console = imports.console.console;
6 Symbol = imports.Symbol.Symbol;
10 * @extends JSDOC.Collapse
12 * The point of this class is to iterate through the Collapsed tree
13 * and add the property 'scopedName' to the tokens.
18 After spending some time looking at this, a few conclusions...
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
23 scopes are normally changed when these things occur:
26 globalScope(stmts) => statementsScope($global$, stmts)
30 objectScope(sname, props )
31 a = { .... } << scope is a $this$={a}
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..
42 functionScope(sname, stmts )
43 function a() { .... } << scope is a $this$={a}
44 a = function() { } << scope might be a $this$={a}
51 XX.yy(a,b, { .... }) << scope might be a or b.. $this$={a}
52 aa = XX.yy(a,b, { .... }) << scope might aa $this$={a}
54 callscope(name, pref, args)
59 foo = new (function() { }
61 RETURN function(...) {
72 * sn = new ScopeName({
73 tokens : ... result from tokenizer,
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.
83 ScopeNamer = XObject.define(
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 || [];
96 imports.JSDOC.Collapse.Collapse,
102 * add/remove ';' after return to configure at present..
103 * @param {String} str String to output
105 debugCall : function(str) {
108 // if (this.filename.match(/Date\.js/)) return print(str);
114 buildSymbols : function()
116 if (!this.statements) {
117 this.statements = this.collapse(this.tokens);
118 //print(JSON.stringify(this.s, null,4));
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));
126 this.walkStatements(this.global, this.statements)
138 walkStatements: function(scope, statements)
140 this.debugCall("walkStatements :" + scope + '@' + statements[0][0].line) ;
143 var isGlobal = scope == this.global;
147 statements.some(function(st ) {
148 // handle change of scope..
151 st[0].jsdoc.getTag('scope').length
155 scope = st[0].jsdoc.getTag('scope');
156 // might be an array..
157 if (typeof(scope) != 'String') {
158 scope = scope[0].desc;
161 print("SCOPE CHANGE TO:" + scope);
162 _this.global = scope;
166 res = _this.walkStatement(scope, st);
174 walkStatement: function(scope, stmt)
178 this.debugCall("walkStatement :" + this.global +'/' +scope + '@' + this.tokens[0].line );
184 var isGlobal = scope == this.global;
188 //if (this.filename.match(/pack\.js/) && isGlobal) {
189 // print(JSON.stringify(stmt , null,4));
191 // @ignore stops the parser..
194 stmt[0].jsdoc.getTag('ignore').length
196 this.debugCall("walkStatement : ignore found - " + scope + '@' + this.tokens[0].line );
197 print("GOT ignore?");
202 while (null != (token = this.next())) {
210 //walkFunction(scope, name , args, stmts )
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 : '';
217 this.walkFunctionDef(scope, name, this.lookTok(2).args, this.lookTok(3).items, token);
223 //a = function() { } << scope might be a $this$={a}
224 if (this.lookTok(-1).data == '=' &&
225 this.lookTok(-2).is('NAME')
228 name = this.lookTok(-2).data;
232 if (this.lookTok(-3).name == 'VAR') {
235 if (name.match(/^this\./) && scope.match(/\.prototype$/)) {
236 name = name.substring(5);
238 if (name.split('.').length > 1) {
245 this.walkFunctionDef(scope, name, this.lookTok(1).args, this.lookTok(2).items, this.lookTok(-2));
252 print("+++ FUNCTION unusual context" + token.file + ':' + token.line);
262 // XX.yy(a,b, { .... }) << scope might be a or b.. $this$={a}
263 // aa = XX.yy(a,b, { .... }) << scope might aa $this$={a}
265 if (token.is('NAME') && this.lookTok(1).data =='(') {
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;
272 this.walkCall(scope, assign, token.data, this.lookTok(1).items, jsdoc);
279 // a = { .... } << scope is a $this$={a}
280 if (token.data == '{' && this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
282 // could be var x = ..
283 var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
285 var isVar = this.lookTok(-3).name == 'VAR';
287 // only register names of objects if
288 var name = this.lookTok(-2).data;
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) {
297 // wipe out the children..
301 print(JSON.stringify({
311 if (name && this.locals.indexOf(name) < 0) {
312 this.locals.push(name);
317 if (this.locals.indexOf(name) > -1 ) {
322 if (name && !name.match(/^this\./)) {
325 if (name && name.match(/^this\./) ) {
326 // see if scope ends in prototype..
327 //print("q" + JSON.stringify(scope));
329 (scope.split('.').pop() == 'prototype') &&
330 (name.split('.').length == 2)
332 name = name.split('.').pop();
342 //print(JSON.stringify(token,null,4));
343 this.walkObject(scope, name, token.props, jd);
349 // it's done on the third element to enable object assignment to work above..
351 // including ... aaa = new BBB({
352 if (this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
356 // could be var x = ..
357 var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
359 var isVar = this.lookTok(-3).name == 'VAR';
361 // only register names of objects if
362 var name = this.lookTok(-2).data;
364 // some a = {} can be hidden
365 // using @type {string} for example.
366 // FIXME - they should be registered as a property...
367 if (jd && jd.jsdoc && jd.jsdoc.getTag('type').length) {
371 // wipe out the children..
375 print(JSON.stringify({
383 if (token.data.match(/imports\./)) {
391 if (name && this.locals.indexOf(name) < 0) {
392 this.locals.push(name);
397 if (this.locals.indexOf(name) > -1 ) {
401 if (name && !name.match(/^this\./)) {
406 if (name && name.match(/^this\./) ) {
407 // see if scope ends in prototype..
408 //print("SCOPE:" + JSON.stringify(scope));
410 (scope.split('.').pop() == 'prototype') &&
411 (name.split('.').length == 2)
413 name = name.split('.').pop();
421 // should not happen...
422 if (name && name.match(/^this\./)) {
429 var symbol = new Symbol( scope +'.'+ name , false , "PROPERTY" , jd.jsdoc);
430 symbol._token = this.lookTok(-2);
432 this.addSymbol(symbol, jd.jsdoc);
441 // this.xxxx = (with jsdoc...)
447 // standard flow... - ignore opening {.
448 if (token.data == '{') {
449 sn = new ScopeNamer(this);
450 //print("GOT { - walkings statuements;}");
452 continue; // object..!?!?!? = ignore ???
453 print(JSON.stringify(token,null,4));
457 //print ("GOT { = running walk statemengs on children?} @" + this.cursor);
458 sn.walkStatements(scope, token.items);
461 if (this.filename.match(/Roo\.js/) && token.data == '(') {
462 //print(JSON.stringify(token,null,4));
466 if ((token.data == '(') && (token.items[0][0].data == 'function')) {
467 sn = new ScopeNamer(this);
468 sn.walkStatements('_private_', token.items[0][2].items);
477 this.debugCall("walkStatement (END):" + this.global +'/' +scope + '@' + this.tokens[0].line );
481 walkFunctionDef : function (inscope, name, args, stmts, jsdocTok)
483 this.debugCall("wallkFuncDef: " + inscope + '#' + name + '@' + this.look(0).line );
484 var scope = name.length ? (inscope + '.' + name) : inscope;
486 var symbol = new Symbol( scope , args || [] , "FUNCTION" , jsdocTok.jsdoc);
487 symbol._token = jsdocTok;
488 this.addSymbol(symbol, jsdocTok.jsdoc);
490 var sn = new ScopeNamer(this);
492 sn.walkStatements(scope, stmts);
493 this.debugCall("wallkFuncDef: (END)" + inscope + '#' + name + '@' + this.look(0).line );
498 walkCall : function (inscope, assign, callname, items, jsdocTok)
500 this.debugCall("walkCall : " + inscope +':' + assign + '@' + this.look(0).line + ' ' + callname );
501 var scope = inscope + ( assign ? ('.' + assign) : '' );
502 //scope = scope.replace(/\^_global\$\./, '');
507 // add the handers for differnt methods in here....
510 // somecall(BASE, { .. object ..})
511 // or... x = somecall(BASE, { ... object..})
512 case 'XObject.extend':
515 //print(JSON.stringify(items,null,4));
516 // SHOULD WE ADD SCOPE HERE???
518 var arg0 = items[0][0].data;
520 var topscope = scope.split('.').pop();
522 scope = (topscope == arg0) ? arg0 : scope + '.' + arg0;
524 // see if arg0 is defined has a symbol..
525 if (this.haveSymbol(arg0)) {
530 // 2nd arg is a object def
531 if (items[1][0].data != '{') {
535 if (assign != false && !scope.match(/\.prototype$/)) {
536 var symbol = new Symbol( scope , false , "OBJECT" , jsdocTok);
537 symbol._token = jsdocTok;
538 this.addSymbol(symbol, jsdocTok.jsdoc);
543 var sn = new ScopeNamer(this);
545 //print(JSON.stringify(items,null,4));
546 sn.walkObject(scope , false, items[1][0].props, jsdocTok );
547 this.debugCall("walkCall(END): " + inscope +':' + assign + '@' + this.look(0).line + ' ' + callname );
554 case 'XObject.define':
555 // func, extends, props.
557 var symbol = new Symbol( scope , items[0][1].args || [] , "CONSTRUCTOR" , jsdocTok);
558 symbol._token = jsdocTok;
561 this.addSymbol(symbol, jsdocTok.jsdoc);
562 var sn = new ScopeNamer(this);
563 //print(JSON.stringify(items, null,4));
565 sn.walkStatements(scope + '.prototype', items[0][2].items);
568 sn.walkObject(scope + '.prototype', false, items[2][0].props );
569 this.debugCall("walkCall(END): " + inscope +':' + assign + '@' + this.look(0).line + ' ' + callname );
577 this.debugCall("walkCall(END): " + inscope +':' + assign + '@' + this.look(0).line + ' ' + callname );
582 walkObject : function(inscope, name, items, jsdocTok)
584 var scope = inscope + (( name === false) ? '' : ('.' + name));
586 if (name !== false) {
588 var symbol = new Symbol( scope , false , "OBJECT" , jsdocTok.jsdoc);
589 symbol._token = jsdocTok;
590 this.addSymbol(symbol, jsdocTok.jsdoc);
593 // items can be false in this scenaro: a = {};
597 // our other scenario is where something is flagged as private, we will not investigate further
598 // we do add it however..
599 if (jsdocTok && jsdocTok.jsdoc && jsdocTok.jsdoc.getTag('private').length) {
603 //print(typeof(items));
604 this.debugCall("wallkObject : " + scope + '#' + name + '@' + items[Object.keys(items)[0]].key.line);
605 for( var k in items) {
606 var key = items[k].key;
607 var val = items[k].val;
610 // x : function(....)
611 if (val[0].name == 'FUNCTION' ) {
614 this.walkFunctionDef (scope, k, val[1].args, val[2].items, key)
620 // x: ( .... ) conditional properties? maybe detect function?
623 // x : something else - not a function..
626 var symbol = new Symbol( scope +'.'+ k , val[1].args || [] , "PROPERTY" , key.jsdoc);
629 this.addSymbol(symbol, key.jsdoc);
643 addSymbol: function(symbol, comment)
645 //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
646 //print("PARSER addSYMBOL : " + symbol.alias);
648 // if a symbol alias is documented more than once the last one with the user docs wins
650 // dumpe some invalid symbols..
651 var ptype_ar = symbol.alias.split(/#/);
652 if (ptype_ar.length > 2) {
656 if (ptype_ar.length > 1 && ptype_ar[1].split(/\./).length > 1) {
657 // multiple . after #
661 ScopeNamer.prototype.debugCall("addSymbol : " + symbol.alias );
663 if (ScopeNamer.symbols.hasSymbol(symbol.alias)) {
665 if (!comment) { // we do not have a comment, and it's registered.
668 var oldSymbol = ScopeNamer.symbols.getSymbol(symbol.alias);
670 if (oldSymbol.comment && oldSymbol.comment.isUserComment && !oldSymbol.comment.hasTags) {
671 if (symbol.comment.isUserComment) { // old and new are both documented
672 this.LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
674 else { // old is documented but new isn't
680 // we don't document anonymous things
681 //if (this.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
683 // uderscored things may be treated as if they were marked private, this cascades
684 //if (this.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
685 // symbol.isPrivate = true;
687 if (ScopeNamer.builder.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
688 symbol.isPrivate = true;
690 // -p flag is required to document private things
691 //if ((symbol.isInner || symbol.isPrivate) && !this.docPrivate) return;
693 // ignored things are not documented, this doesn't cascade
694 if (symbol.isIgnored) return;
696 //print("ADD symbol: " + symbol.isa + ' => ' + symbol.alias );
697 //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
699 // add it to the file's list... (for dumping later..)
701 ScopeNamer.filesSymbols[Symbol.srcFile].addSymbol(symbol);
704 ScopeNamer.symbols.addSymbol(symbol);
707 haveSymbol: function(name)
709 return ScopeNamer.symbols.hasSymbol(name);
712 addBuiltin : function(name) {
714 var builtin = new Symbol(name, [], "CONSTRUCTOR", new imports.DocComment.DocComment(""));
715 builtin.isNamespace = false;
716 builtin.srcFile = "";
717 builtin.isPrivate = false;
718 this.addSymbol(builtin);
727 ScopeNamer.symbols = new imports.SymbolSet.SymbolSet();
733 ScopeNamer.addSymbol = ScopeNamer.prototype.addSymbol;
734 ScopeNamer.addBuiltin = ScopeNamer.prototype.addBuiltin;