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

     2 **

     3 ** Copyright (C) 2010 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         Image,

    93         Group,

    94         Module,

    95         Page,

    96 #ifdef QDOC_QML

    97         ExternalPage,

    98         QmlClass,

    99         QmlPropertyGroup

   100 #else

   101         ExternalPage

   102 #endif

   103     };

   104     

   105     enum Access { Public, Protected, Private };

   106     

   107     enum Status { 

   108         Compat, 

   109         Obsolete, 

   110         Deprecated, 

   111         Preliminary, 

   112         Commendable, 

   113         Main, 

   114         Internal 

   115     }; // don't reorder thisw enum

   116     

   117     enum ThreadSafeness { 

   118         UnspecifiedSafeness, 

   119         NonReentrant, 

   120         Reentrant, 

   121         ThreadSafe 

   122     };

   123     

   124     enum LinkType { 

   125         StartLink, 

   126         NextLink, 

   127         PreviousLink,

   128         ContentsLink, 

   129         IndexLink,

   130         InheritsLink /*, 

   131         GlossaryLink, 

   132         CopyrightLink,

   133         ChapterLink, 

   134         SectionLink, 

   135         SubsectionLink, 

   136         AppendixLink */ 

   137     };

   138 

   139     virtual ~Node();

   140 

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

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

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

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

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

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

   147     void setRelates(InnerNode *pseudoParent);

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

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

   150     void setUrl(const QString &url);

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

   152 

   153     virtual bool isInnerNode() const = 0;

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

   155     virtual bool isFunction() const { return false; }

   156     Type type() const { return typ; }

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

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

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

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

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

   162     QString moduleName() const;

   163     QString url() const;

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

   165 

   166     Access access() const { return acc; }

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

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

   169     Status status() const { return sta; }

   170     Status inheritedStatus() const;

   171     ThreadSafeness threadSafeness() const;

   172     ThreadSafeness inheritedThreadSafeness() const;

   173     QString since() const { return sinc; }

   174     QString templateStuff() const { return tpl; }

   175 

   176     void clearRelated() { rel = 0; }

   177 

   178     virtual QString fileBase() const;

   179 

   180  protected:

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

   182 

   183  private:

   184 

   185 #ifdef Q_WS_WIN

   186     Type typ;

   187     Access acc;

   188     Status sta;

   189     ThreadSafeness saf;

   190 #else

   191     Type typ : 4;

   192     Access acc : 2;

   193     Status sta : 3;

   194     ThreadSafeness saf : 2;

   195 #endif

   196     InnerNode *par;

   197     InnerNode *rel;

   198     QString nam;

   199     Location loc;

   200     Doc d;

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

   202     QString mod;

   203     QString u;

   204     QString sinc;

   205     QString tpl;

   206 };

   207 

   208 class FunctionNode;

   209 class EnumNode;

   210 

   211 typedef QList<Node *> NodeList;

   212 

   213 class InnerNode : public Node

   214 {

   215  public:

   216     virtual ~InnerNode();

   217 

   218     Node *findNode(const QString& name);

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

   220     FunctionNode *findFunctionNode(const QString& name);

   221     FunctionNode *findFunctionNode(const FunctionNode *clone);

   222     void addInclude(const QString &include);

   223     void setIncludes(const QStringList &includes);

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

   225     void normalizeOverloads();

   226     void makeUndocumentedChildrenInternal();

   227     void deleteChildren();

   228     void removeFromRelated();

   229 

   230     virtual bool isInnerNode() const;

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

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

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

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

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

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

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

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

   239     int overloadNumber(const FunctionNode *func) const;

   240     int numOverloads(const QString& funcName) const;

   241     NodeList overloads(const QString &funcName) const;

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

   243 

   244     QStringList primaryKeys();

   245     QStringList secondaryKeys();

   246 

   247  protected:

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

   249 

   250  private:

   251     friend class Node;

   252 

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

   254     void addChild(Node *child);

   255     void removeChild(Node *child);

   256     void removeRelated(Node *pseudoChild);

   257 

   258     QStringList inc;

   259     NodeList children;

   260     NodeList enumChildren;

   261     NodeList related;

   262     QMap<QString, Node *> childMap;

   263     QMap<QString, Node *> primaryFunctionMap;

   264     QMap<QString, NodeList> secondaryFunctionMap;

   265 };

   266 

   267 class LeafNode : public Node

   268 {

   269  public:

   270     LeafNode();

   271     virtual ~LeafNode() { }

   272 

   273     virtual bool isInnerNode() const;

   274 

   275  protected:

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

   277 };

   278 

   279 class NamespaceNode : public InnerNode

   280 {

   281  public:

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

   283     virtual ~NamespaceNode() { }

   284 };

   285 

   286 class ClassNode;

   287 

   288 struct RelatedClass

   289 {

   290     RelatedClass() { }

   291     RelatedClass(Node::Access access0, 

   292                  ClassNode* node0,

   293                  const QString& dataTypeWithTemplateArgs0 = "")

   294       : access(access0), 

   295         node(node0),

   296         dataTypeWithTemplateArgs(dataTypeWithTemplateArgs0) { }

   297 

   298     Node::Access        access;

   299     ClassNode*          node;

   300     QString             dataTypeWithTemplateArgs;

   301 };

   302 

   303 class ClassNode : public InnerNode

   304 {

   305  public:

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

   307     virtual ~ClassNode() { }

   308 

   309     void addBaseClass(Access access, 

   310                       ClassNode *node, 

   311                       const QString &dataTypeWithTemplateArgs = "");

   312     void fixBaseClasses();

   313 

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

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

   316 

   317     bool hideFromMainList() const { return hidden; }

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

   319 

   320     QString serviceName() const { return sname; }

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

   322     QString qmlElement() const { return qmlelement; }

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

   324 

   325  private:

   326     QList<RelatedClass> bas;

   327     QList<RelatedClass> der;

   328     bool hidden;

   329     QString sname;

   330     QString qmlelement;

   331 };

   332 

   333 class FakeNode : public InnerNode

   334 {

   335  public:

   336 

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

   338     virtual ~FakeNode() { }

   339 

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

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

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

   343 

   344     SubType subType() const { return sub; }

   345     QString title() const { return tle; }

   346     QString fullTitle() const;

   347     QString subTitle() const;

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

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

   350 

   351  private:

   352     SubType sub;

   353     QString tle;

   354     QString stle;

   355     NodeList gr;

   356 };

   357 

   358 #ifdef QDOC_QML

   359 class QmlClassNode : public FakeNode

   360 {

   361  public:

   362     QmlClassNode(InnerNode *parent, 

   363                  const QString& name, 

   364                  const ClassNode* cn);

   365     virtual ~QmlClassNode() { }

   366 

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

   368     virtual QString fileBase() const;

   369 

   370     static bool qmlOnly;

   371 

   372  private:

   373     const ClassNode* cnode;

   374 };

   375 

   376 class QmlPropGroupNode : public FakeNode

   377 {

   378  public:

   379     QmlPropGroupNode(QmlClassNode* parent, 

   380                      const QString& name,

   381                      bool attached);

   382     virtual ~QmlPropGroupNode() { }

   383 

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

   385     void setDefault() { isdefault = true; }

   386     bool isDefault() const { return isdefault; }

   387     bool isAttached() const { return att; }

   388 

   389  private:

   390     bool    isdefault;

   391     bool    att;

   392 };

   393 

   394 class QmlPropertyNode : public LeafNode

   395 {

   396  public:

   397     QmlPropertyNode(QmlPropGroupNode* parent, 

   398                     const QString& name,

   399                     const QString& type,

   400                     bool attached);

   401     virtual ~QmlPropertyNode() { }

   402 

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

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

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

   406     void setWritable(bool writable) { wri = toTrool(writable); }

   407 

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

   409     QString qualifiedDataType() const { return dt; }

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

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

   412     bool isWritable() const { return fromTrool(wri,true); }

   413     bool isAttached() const { return att; }

   414 

   415     const QString& element() const { return static_cast<QmlPropGroupNode*>(parent())->element(); }

   416 

   417  private:

   418     enum Trool { Trool_True, Trool_False, Trool_Default };

   419 

   420     static Trool toTrool(bool boolean);

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

   422 

   423     QString dt;

   424     Trool   sto;

   425     Trool   des;

   426     Trool   wri;

   427     bool    att;

   428 };

   429 #endif

   430 

   431 class EnumItem

   432 {

   433  public:

   434     EnumItem() { }

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

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

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

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

   439 

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

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

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

   443 

   444  private:

   445     QString nam;

   446     QString val;

   447     Text txt;

   448 };

   449 

   450 class TypedefNode;

   451 

   452 class EnumNode : public LeafNode

   453 {

   454  public:

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

   456     virtual ~EnumNode() { }

   457 

   458     void addItem(const EnumItem& item);

   459     void setFlagsType(TypedefNode *typedeff);

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

   461 

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

   463     Access itemAccess(const QString& name) const;

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

   465     QString itemValue(const QString &name) const;

   466 

   467  private:

   468     QList<EnumItem> itms;

   469     QSet<QString> names;

   470     const TypedefNode *ft;

   471 };

   472 

   473 class TypedefNode : public LeafNode

   474 {

   475  public:

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

   477     virtual ~TypedefNode() { }

   478 

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

   480 

   481  private:

   482     void setAssociatedEnum(const EnumNode *enume);

   483 

   484     friend class EnumNode;

   485 

   486     const EnumNode *ae;

   487 };

   488 

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

   490 {

   491     ft = typedeff;

   492     typedeff->setAssociatedEnum(this);

   493 }

   494 

   495 

   496 class Parameter

   497 {

   498  public:

   499     Parameter() {}

   500     Parameter(const QString& leftType, 

   501               const QString& rightType = "",

   502               const QString& name = "", 

   503               const QString& defaultValue = "");

   504     Parameter(const Parameter& p);

   505 

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

   507 

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

   509 

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

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

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

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

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

   515 

   516     QString reconstruct(bool value = false) const;

   517 

   518  private:

   519     QString lef;

   520     QString rig;

   521     QString nam;

   522     QString def;

   523 };

   524 

   525 class PropertyNode;

   526 

   527 class FunctionNode : public LeafNode

   528 {

   529  public:

   530     enum Metaness { 

   531         Plain, 

   532         Signal, 

   533         Slot,

   534         Ctor,

   535         Dtor, 

   536         MacroWithParams,

   537         MacroWithoutParams, 

   538         Native };

   539     enum Virtualness { NonVirtual, ImpureVirtual, PureVirtual };

   540 

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

   542     FunctionNode(Type type, InnerNode *parent, const QString &name, bool attached);

   543     virtual ~FunctionNode() { }

   544 

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

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

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

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

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

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

   551     void setOverload(bool overlode);

   552     void setReimp(bool r);

   553     void addParameter(const Parameter& parameter);

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

   555     void borrowParameterNames(const FunctionNode *source);

   556     void setReimplementedFrom(FunctionNode *from);

   557 

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

   559     Metaness metaness() const { return met; }

   560     bool isMacro() const { 

   561         return met == MacroWithParams || met == MacroWithoutParams; 

   562     }

   563     Virtualness virtualness() const { return vir; }

   564     bool isConst() const { return con; }

   565     bool isStatic() const { return sta; }

   566     bool isOverload() const { return ove; }

   567     bool isReimp() const { return reimp; }

   568     bool isFunction() const { return true; }

   569     int overloadNumber() const;

   570     int numOverloads() const;

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

   572     QStringList parameterNames() const;

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

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

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

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

   577 

   578     QStringList reconstructParams(bool values = false) const;

   579     QString signature(bool values = false) const;

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

   581     bool isAttached() const { return att; }

   582 

   583     void debug() const;

   584 

   585  private:

   586     void setAssociatedProperty(PropertyNode *property);

   587 

   588     friend class InnerNode;

   589     friend class PropertyNode;

   590 

   591     QString     rt;

   592     QStringList pp;

   593 #ifdef Q_WS_WIN

   594     Metaness    met;

   595     Virtualness vir;

   596 #else

   597     Metaness met : 4;

   598     Virtualness vir : 2;

   599 #endif

   600     bool con : 1;

   601     bool sta : 1;

   602     bool ove : 1;

   603     bool reimp: 1; 

   604     bool att: 1;

   605     QList<Parameter> params;

   606     const FunctionNode *rf;

   607     const PropertyNode *ap;

   608     QList<FunctionNode *> rb;

   609 };

   610 

   611 class PropertyNode : public LeafNode

   612 {

   613  public:

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

   615     enum { NumFunctionRoles = Notifier + 1 };

   616 

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

   618     virtual ~PropertyNode() { }

   619 

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

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

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

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

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

   625     void setWritable(bool writable) { wri = toTrool(writable); }

   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     bool isWritable() const { return fromTrool(wri, writableDefault()); }

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

   640 

   641  private:

   642     enum Trool { Trool_True, Trool_False, Trool_Default };

   643 

   644     static Trool toTrool(bool boolean);

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

   646 

   647     bool storedDefault() const { return true; }

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

   649     bool writableDefault() const { return !setters().isEmpty(); }

   650 

   651     QString dt;

   652     NodeList funcs[NumFunctionRoles];

   653     Trool sto;

   654     Trool des;

   655     Trool wri;

   656     const PropertyNode *overrides;

   657 };

   658 

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

   660 {

   661     params = parameters;

   662 }

   663 

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

   665 {

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

   667     function->setAssociatedProperty(this);

   668 }

   669 

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

   671 {

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

   673 }

   674 

   675 inline NodeList PropertyNode::functions() const

   676 {

   677     NodeList list;

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

   679 	list += funcs[i];

   680     return list;

   681 }

   682 

   683 class VariableNode : public LeafNode

   684 {

   685  public:

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

   687     virtual ~VariableNode() { }

   688 

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

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

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

   692 

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

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

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

   696     bool isStatic() const { return sta; }

   697 

   698  private:

   699     QString lt;

   700     QString rt;

   701     bool sta;

   702 };

   703 

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

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

   706 {

   707 }

   708 

   709 class TargetNode : public LeafNode

   710 {

   711  public:

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

   713     virtual ~TargetNode() { }

   714 

   715     virtual bool isInnerNode() const;

   716 };

   717 

   718 QT_END_NAMESPACE

   719 

   720 #endif