1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the tools applications of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*

    43   node.h

    44 */

    45 

    46 #ifndef NODE_H

    47 #define NODE_H

    48 

    49 #include <qdir.h>

    50 #include <qmap.h>

    51 #include <qpair.h>

    52 #include <qstringlist.h>

    53 

    54 #include "codechunk.h"

    55 #include "doc.h"

    56 #include "location.h"

    57 #include "text.h"

    58 

    59 QT_BEGIN_NAMESPACE

    60 

    61 class InnerNode;

    62 

    63 class Node

    64 {

    65  public:

    66     enum Type { 

    67         Namespace, 

    68         Class, 

    69         Fake, 

    70         Enum, 

    71         Typedef, 

    72         Function, 

    73         Property,

    74         Variable, 

    75 #ifdef QDOC_QML

    76         Target,

    77         QmlProperty,

    78         QmlSignal,

    79         QmlMethod,

    80         LastType

    81 #else

    82         Target,

    83         LastType

    84 #endif

    85     };

    86 

    87     enum SubType { 

    88         NoSubType,

    89         Example, 

    90         HeaderFile, 

    91         File,

    92         Group,

    93         Module,

    94         Page,

    95 #ifdef QDOC_QML

    96         ExternalPage,

    97         QmlClass,

    98         QmlPropertyGroup

    99 #else

   100         ExternalPage

   101 #endif

   102     };

   103     

   104     enum Access { Public, Protected, Private };

   105     

   106     enum Status { 

   107         Compat, 

   108         Obsolete, 

   109         Deprecated, 

   110         Preliminary, 

   111         Commendable, 

   112         Main, 

   113         Internal 

   114     }; // don't reorder thisw enum

   115     

   116     enum ThreadSafeness { 

   117         UnspecifiedSafeness, 

   118         NonReentrant, 

   119         Reentrant, 

   120         ThreadSafe 

   121     };

   122     

   123     enum LinkType { 

   124         StartLink, 

   125         NextLink, 

   126         PreviousLink,

   127         ContentsLink, 

   128         IndexLink,

   129         InheritsLink /*, 

   130         GlossaryLink, 

   131         CopyrightLink,

   132         ChapterLink, 

   133         SectionLink, 

   134         SubsectionLink, 

   135         AppendixLink */ 

   136     };

   137 

   138     virtual ~Node();

   139 

   140     void setAccess(Access access) { acc = access; }

   141     void setLocation(const Location& location) { loc = location; }

   142     void setDoc(const Doc& doc, bool replace = false);

   143     void setStatus(Status status) { sta = status; }

   144     void setThreadSafeness(ThreadSafeness safeness) { saf = safeness; }

   145     void setSince(const QString &since) { sinc = since; }

   146     void setRelates(InnerNode *pseudoParent);

   147     void setModuleName(const QString &module) { mod = module; }

   148     void setLink(LinkType linkType, const QString &link, const QString &desc);

   149     void setUrl(const QString &url);

   150     void setTemplateStuff(const QString &templateStuff) { tpl = templateStuff; }

   151 

   152     virtual bool isInnerNode() const = 0;

   153     virtual bool isReimp() const { return false; }

   154     Type type() const { return typ; }

   155     virtual SubType subType() const { return NoSubType; }

   156     InnerNode *parent() const { return par; }

   157     InnerNode *relates() const { return rel; }

   158     const QString& name() const { return nam; }

   159     QMap<LinkType, QPair<QString,QString> > links() const { return linkMap; }

   160     QString moduleName() const;

   161     QString url() const;

   162     virtual QString nameForLists() const { return nam; }

   163 

   164     Access access() const { return acc; }

   165     const Location& location() const { return loc; }

   166     const Doc& doc() const { return d; }

   167     Status status() const { return sta; }

   168     Status inheritedStatus() const;

   169     ThreadSafeness threadSafeness() const;

   170     ThreadSafeness inheritedThreadSafeness() const;

   171     QString since() const { return sinc; }

   172     QString templateStuff() const { return tpl; }

   173 

   174     void clearRelated() { rel = 0; }

   175 

   176     virtual QString fileBase() const;

   177 

   178  protected:

   179     Node(Type type, InnerNode *parent, const QString& name);

   180 

   181  private:

   182 

   183 #ifdef Q_WS_WIN

   184     Type typ;

   185     Access acc;

   186     Status sta;

   187     ThreadSafeness saf;

   188 #else

   189     Type typ : 4;

   190     Access acc : 2;

   191     Status sta : 3;

   192     ThreadSafeness saf : 2;

   193 #endif

   194     InnerNode *par;

   195     InnerNode *rel;

   196     QString nam;

   197     Location loc;

   198     Doc d;

   199     QMap<LinkType, QPair<QString, QString> > linkMap;

   200     QString mod;

   201     QString u;

   202     QString sinc;

   203     QString tpl;

   204 };

   205 

   206 class FunctionNode;

   207 class EnumNode;

   208 

   209 typedef QList<Node *> NodeList;

   210 

   211 class InnerNode : public Node

   212 {

   213  public:

   214     virtual ~InnerNode();

   215 

   216     Node *findNode(const QString& name);

   217     Node *findNode(const QString& name, Type type);

   218     FunctionNode *findFunctionNode(const QString& name);

   219     FunctionNode *findFunctionNode(const FunctionNode *clone);

   220     void addInclude(const QString &include);

   221     void setIncludes(const QStringList &includes);

   222     void setOverload(const FunctionNode *func, bool overlode);

   223     void normalizeOverloads();

   224     void makeUndocumentedChildrenInternal();

   225     void deleteChildren();

   226     void removeFromRelated();

   227 

   228     virtual bool isInnerNode() const;

   229     const Node *findNode(const QString& name) const;

   230     const Node *findNode(const QString& name, Type type) const;

   231     const FunctionNode *findFunctionNode(const QString& name) const;

   232     const FunctionNode *findFunctionNode(const FunctionNode *clone) const;

   233     const EnumNode *findEnumNodeForValue(const QString &enumValue) const;

   234     const NodeList & childNodes() const { return children; }

   235     const NodeList & relatedNodes() const { return related; }

   236     int count() const { return children.size(); }

   237     int overloadNumber(const FunctionNode *func) const;

   238     int numOverloads(const QString& funcName) const;

   239     NodeList overloads(const QString &funcName) const;

   240     const QStringList& includes() const { return inc; }

   241 

   242  protected:

   243     InnerNode(Type type, InnerNode *parent, const QString& name);

   244 

   245  private:

   246     friend class Node;

   247 

   248     static bool isSameSignature(const FunctionNode *f1, const FunctionNode *f2);

   249     void addChild(Node *child);

   250     void removeChild(Node *child);

   251     void removeRelated(Node *pseudoChild);

   252 

   253     QStringList inc;

   254     NodeList children;

   255     NodeList enumChildren;

   256     NodeList related;

   257     QMap<QString, Node *> childMap;

   258     QMap<QString, Node *> primaryFunctionMap;

   259     QMap<QString, NodeList> secondaryFunctionMap;

   260 };

   261 

   262 class LeafNode : public Node

   263 {

   264  public:

   265     LeafNode();

   266     virtual ~LeafNode() { }

   267 

   268     virtual bool isInnerNode() const;

   269 

   270  protected:

   271     LeafNode(Type type, InnerNode* parent, const QString& name);

   272 };

   273 

   274 class NamespaceNode : public InnerNode

   275 {

   276  public:

   277     NamespaceNode(InnerNode *parent, const QString& name);

   278     virtual ~NamespaceNode() { }

   279 };

   280 

   281 class ClassNode;

   282 

   283 struct RelatedClass

   284 {

   285     RelatedClass() { }

   286     RelatedClass(Node::Access access0, 

   287                  ClassNode* node0,

   288                  const QString& dataTypeWithTemplateArgs0 = "")

   289       : access(access0), 

   290         node(node0),

   291         dataTypeWithTemplateArgs(dataTypeWithTemplateArgs0) { }

   292 

   293     Node::Access        access;

   294     ClassNode*          node;

   295     QString             dataTypeWithTemplateArgs;

   296 };

   297 

   298 class ClassNode : public InnerNode

   299 {

   300  public:

   301     ClassNode(InnerNode *parent, const QString& name);

   302     virtual ~ClassNode() { }

   303 

   304     void addBaseClass(Access access, 

   305                       ClassNode *node, 

   306                       const QString &dataTypeWithTemplateArgs = "");

   307     void fixBaseClasses();

   308 

   309     const QList<RelatedClass> &baseClasses() const { return bas; }

   310     const QList<RelatedClass> &derivedClasses() const { return der; }

   311 

   312     bool hideFromMainList() const { return hidden; }

   313     void setHideFromMainList(bool value) { hidden = value; }

   314 

   315     QString serviceName() const { return sname; }

   316     void setServiceName(const QString& value) { sname = value; }

   317     QString qmlElement() const { return qmlelement; }

   318     void setQmlElement(const QString& value) { qmlelement = value; }

   319 

   320  private:

   321     QList<RelatedClass> bas;

   322     QList<RelatedClass> der;

   323     bool hidden;

   324     QString sname;

   325     QString qmlelement;

   326 };

   327 

   328 class FakeNode : public InnerNode

   329 {

   330  public:

   331 

   332     FakeNode(InnerNode *parent, const QString& name, SubType subType);

   333     virtual ~FakeNode() { }

   334 

   335     void setTitle(const QString &title) { tle = title; }

   336     void setSubTitle(const QString &subTitle) { stle = subTitle; }

   337     void addGroupMember(Node *node) { gr.append(node); }

   338 

   339     SubType subType() const { return sub; }

   340     QString title() const { return tle; }

   341     QString fullTitle() const;

   342     QString subTitle() const;

   343     const NodeList &groupMembers() const { return gr; }

   344     virtual QString nameForLists() const { return title(); }

   345 

   346  private:

   347     SubType sub;

   348     QString tle;

   349     QString stle;

   350     NodeList gr;

   351 };

   352 

   353 #ifdef QDOC_QML

   354 class QmlClassNode : public FakeNode

   355 {

   356  public:

   357     QmlClassNode(InnerNode *parent, 

   358                  const QString& name, 

   359                  const ClassNode* cn);

   360     virtual ~QmlClassNode() { }

   361 

   362     const ClassNode* classNode() const { return cnode; }

   363     virtual QString fileBase() const;

   364 

   365  private:

   366     const ClassNode* cnode;

   367 };

   368 

   369 class QmlPropGroupNode : public FakeNode

   370 {

   371  public:

   372     QmlPropGroupNode(QmlClassNode* parent, 

   373                      const QString& name,

   374                      bool attached);

   375     virtual ~QmlPropGroupNode() { }

   376 

   377     const QString& element() const { return name(); }

   378     void setDefault() { isdefault = true; }

   379     bool isDefault() const { return isdefault; }

   380     bool isAttached() const { return att; }

   381 

   382  private:

   383     bool    isdefault;

   384     bool    att;

   385 };

   386 

   387 class QmlPropertyNode : public LeafNode

   388 {

   389  public:

   390     QmlPropertyNode(QmlPropGroupNode* parent, 

   391                     const QString& name,

   392                     const QString& type,

   393                     bool attached);

   394     virtual ~QmlPropertyNode() { }

   395 

   396     void setDataType(const QString& dataType) { dt = dataType; }

   397     void setStored(bool stored) { sto = toTrool(stored); }

   398     void setDesignable(bool designable) { des = toTrool(designable); }

   399 

   400     const QString &dataType() const { return dt; }

   401     QString qualifiedDataType() const { return dt; }

   402     bool isStored() const { return fromTrool(sto,true); }

   403     bool isDesignable() const { return fromTrool(des,false); }

   404     bool isAttached() const { return att; }

   405 

   406     const QString& element() const { return parent()->name(); }

   407 

   408  private:

   409     enum Trool { Trool_True, Trool_False, Trool_Default };

   410 

   411     static Trool toTrool(bool boolean);

   412     static bool fromTrool(Trool troolean, bool defaultValue);

   413 

   414     QString dt;

   415     Trool   sto;

   416     Trool   des;

   417     bool    att;

   418 };

   419 

   420 class QmlSignalNode : public LeafNode

   421 {

   422  public:

   423     QmlSignalNode(QmlClassNode* parent, const QString& name);

   424     virtual ~QmlSignalNode() { }

   425 

   426     const QString& element() const { return parent()->name(); }

   427 };

   428 

   429 class QmlMethodNode : public LeafNode

   430 {

   431  public:

   432     QmlMethodNode(QmlClassNode* parent, const QString& name);

   433     virtual ~QmlMethodNode() { }

   434 

   435     const QString& element() const { return parent()->name(); }

   436 };

   437 #endif

   438 

   439 class EnumItem

   440 {

   441  public:

   442     EnumItem() { }

   443     EnumItem(const QString& name, const QString& value)

   444 	: nam(name), val(value) { }

   445     EnumItem(const QString& name, const QString& value, const Text &txt)

   446 	: nam(name), val(value), txt(txt) { }

   447 

   448     const QString& name() const { return nam; }

   449     const QString& value() const { return val; }

   450     const Text &text() const { return txt; }

   451 

   452  private:

   453     QString nam;

   454     QString val;

   455     Text txt;

   456 };

   457 

   458 class TypedefNode;

   459 

   460 class EnumNode : public LeafNode

   461 {

   462  public:

   463     EnumNode(InnerNode *parent, const QString& name);

   464     virtual ~EnumNode() { }

   465 

   466     void addItem(const EnumItem& item);

   467     void setFlagsType(TypedefNode *typedeff);

   468     bool hasItem(const QString &name) const { return names.contains(name); }

   469 

   470     const QList<EnumItem>& items() const { return itms; }

   471     Access itemAccess(const QString& name) const;

   472     const TypedefNode *flagsType() const { return ft; }

   473     QString itemValue(const QString &name) const;

   474 

   475  private:

   476     QList<EnumItem> itms;

   477     QSet<QString> names;

   478     const TypedefNode *ft;

   479 };

   480 

   481 class TypedefNode : public LeafNode

   482 {

   483  public:

   484     TypedefNode(InnerNode *parent, const QString& name);

   485     virtual ~TypedefNode() { }

   486 

   487     const EnumNode *associatedEnum() const { return ae; }

   488 

   489  private:

   490     void setAssociatedEnum(const EnumNode *enume);

   491 

   492     friend class EnumNode;

   493 

   494     const EnumNode *ae;

   495 };

   496 

   497 inline void EnumNode::setFlagsType(TypedefNode *typedeff)

   498 {

   499     ft = typedeff;

   500     typedeff->setAssociatedEnum(this);

   501 }

   502 

   503 

   504 class Parameter

   505 {

   506  public:

   507     Parameter() {}

   508     Parameter(const QString& leftType, 

   509               const QString& rightType = "",

   510               const QString& name = "", 

   511               const QString& defaultValue = "");

   512     Parameter(const Parameter& p);

   513 

   514     Parameter& operator=(const Parameter& p);

   515 

   516     void setName(const QString& name) { nam = name; }

   517 

   518     bool hasType() const { return lef.length() + rig.length() > 0; }

   519     const QString& leftType() const { return lef; }

   520     const QString& rightType() const { return rig; }

   521     const QString& name() const { return nam; }

   522     const QString& defaultValue() const { return def; }

   523 

   524     QString reconstruct(bool value = false) const;

   525 

   526  private:

   527     QString lef;

   528     QString rig;

   529     QString nam;

   530     QString def;

   531 };

   532 

   533 class PropertyNode;

   534 

   535 class FunctionNode : public LeafNode

   536 {

   537  public:

   538     enum Metaness { 

   539         Plain, 

   540         Signal, 

   541         Slot,

   542         Ctor,

   543         Dtor, 

   544         MacroWithParams,

   545         MacroWithoutParams, 

   546         Native };

   547     enum Virtualness { NonVirtual, ImpureVirtual, PureVirtual };

   548 

   549     FunctionNode(InnerNode *parent, const QString &name);

   550     virtual ~FunctionNode() { }

   551 

   552     void setReturnType(const QString& returnType) { rt = returnType; }

   553     void setParentPath(const QStringList& parentPath) { pp = parentPath; }

   554     void setMetaness(Metaness metaness) { met = metaness; }

   555     void setVirtualness(Virtualness virtualness) { vir = virtualness; }

   556     void setConst(bool conste) { con = conste; }

   557     void setStatic(bool statique) { sta = statique; }

   558     void setOverload(bool overlode);

   559     void setReimp(bool r);

   560     void addParameter(const Parameter& parameter);

   561     inline void setParameters(const QList<Parameter>& parameters);

   562     void borrowParameterNames(const FunctionNode *source);

   563     void setReimplementedFrom(FunctionNode *from);

   564 

   565     const QString& returnType() const { return rt; }

   566     Metaness metaness() const { return met; }

   567     bool isMacro() const { 

   568         return met == MacroWithParams || met == MacroWithoutParams; 

   569     }

   570     Virtualness virtualness() const { return vir; }

   571     bool isConst() const { return con; }

   572     bool isStatic() const { return sta; }

   573     bool isOverload() const { return ove; }

   574     bool isReimp() const { return reimp; }

   575     int overloadNumber() const;

   576     int numOverloads() const;

   577     const QList<Parameter>& parameters() const { return params; }

   578     QStringList parameterNames() const;

   579     const FunctionNode *reimplementedFrom() const { return rf; }

   580     const QList<FunctionNode *> &reimplementedBy() const { return rb; }

   581     const PropertyNode *associatedProperty() const { return ap; }

   582     const QStringList& parentPath() const { return pp; }

   583 

   584     QStringList reconstructParams(bool values = false) const;

   585     QString signature(bool values = false) const;

   586 

   587  private:

   588     void setAssociatedProperty(PropertyNode *property);

   589 

   590     friend class InnerNode;

   591     friend class PropertyNode;

   592 

   593     QString     rt;

   594     QStringList pp;

   595 #ifdef Q_WS_WIN

   596     Metaness    met;

   597     Virtualness vir;

   598 #else

   599     Metaness met : 4;

   600     Virtualness vir : 2;

   601 #endif

   602     bool con : 1;

   603     bool sta : 1;

   604     bool ove : 1;

   605     bool reimp: 1; 

   606     QList<Parameter> params;

   607     const FunctionNode *rf;

   608     const PropertyNode *ap;

   609     QList<FunctionNode *> rb;

   610 };

   611 

   612 class PropertyNode : public LeafNode

   613 {

   614  public:

   615     enum FunctionRole { Getter, Setter, Resetter, Notifier };

   616     enum { NumFunctionRoles = Notifier + 1 };

   617 

   618     PropertyNode(InnerNode *parent, const QString& name);

   619     virtual ~PropertyNode() { }

   620 

   621     void setDataType(const QString& dataType) { dt = dataType; }

   622     void addFunction(FunctionNode *function, FunctionRole role);

   623     void addSignal(FunctionNode *function, FunctionRole role);

   624     void setStored(bool stored) { sto = toTrool(stored); }

   625     void setDesignable(bool designable) { des = toTrool(designable); }

   626     void setOverriddenFrom(const PropertyNode *baseProperty);

   627 

   628     const QString &dataType() const { return dt; }

   629     QString qualifiedDataType() const;

   630     NodeList functions() const;

   631     NodeList functions(FunctionRole role) const { return funcs[(int)role]; }

   632     NodeList getters() const { return functions(Getter); }

   633     NodeList setters() const { return functions(Setter); }

   634     NodeList resetters() const { return functions(Resetter); }

   635     NodeList notifiers() const { return functions(Notifier); }

   636     bool isStored() const { return fromTrool(sto, storedDefault()); }

   637     bool isDesignable() const { return fromTrool(des, designableDefault()); }

   638     const PropertyNode *overriddenFrom() const { return overrides; }

   639 

   640  private:

   641     enum Trool { Trool_True, Trool_False, Trool_Default };

   642 

   643     static Trool toTrool(bool boolean);

   644     static bool fromTrool(Trool troolean, bool defaultValue);

   645 

   646     bool storedDefault() const { return true; }

   647     bool designableDefault() const { return !setters().isEmpty(); }

   648 

   649     QString dt;

   650     NodeList funcs[NumFunctionRoles];

   651     Trool sto;

   652     Trool des;

   653     const PropertyNode *overrides;

   654 };

   655 

   656 inline void FunctionNode::setParameters(const QList<Parameter> &parameters)

   657 {

   658     params = parameters;

   659 }

   660 

   661 inline void PropertyNode::addFunction(FunctionNode *function, FunctionRole role)

   662 {

   663     funcs[(int)role].append(function);

   664     function->setAssociatedProperty(this);

   665 }

   666 

   667 inline void PropertyNode::addSignal(FunctionNode *function, FunctionRole role)

   668 {

   669     funcs[(int)role].append(function);

   670 }

   671 

   672 inline NodeList PropertyNode::functions() const

   673 {

   674     NodeList list;

   675     for (int i = 0; i < NumFunctionRoles; ++i)

   676 	list += funcs[i];

   677     return list;

   678 }

   679 

   680 class VariableNode : public LeafNode

   681 {

   682  public:

   683     VariableNode(InnerNode *parent, const QString &name);

   684     virtual ~VariableNode() { }

   685 

   686     void setLeftType(const QString &leftType) { lt = leftType; }

   687     void setRightType(const QString &rightType) { rt = rightType; }

   688     void setStatic(bool statique) { sta = statique; }

   689 

   690     const QString &leftType() const { return lt; }

   691     const QString &rightType() const { return rt; }

   692     QString dataType() const { return lt + rt; }

   693     bool isStatic() const { return sta; }

   694 

   695  private:

   696     QString lt;

   697     QString rt;

   698     bool sta;

   699 };

   700 

   701 inline VariableNode::VariableNode(InnerNode *parent, const QString &name)

   702     : LeafNode(Variable, parent, name), sta(false)

   703 {

   704 }

   705 

   706 class TargetNode : public LeafNode

   707 {

   708  public:

   709     TargetNode(InnerNode *parent, const QString& name);

   710     virtual ~TargetNode() { }

   711 

   712     virtual bool isInnerNode() const;

   713 };

   714 

   715 QT_END_NAMESPACE

   716 

   717 #endif