tools/qdoc3/node.h

   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