Back to home page

EIC code displayed by LXR
 
 

    

File indexing completed on 2025-01-18 10:12:10 

0001 // @(#)root/html:$Id$
0002 // Author: Nenad Buncic   18/10/95
0003 
0004 /*************************************************************************
0005  * Copyright (C) 1995-2000, Rene Brun and Fons Rademakers.               *
0006  * All rights reserved.                                                  *
0007  *                                                                       *
0008  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0009  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0010  *************************************************************************/
0011 
0012 #ifndef ROOT_THtml
0013 #define ROOT_THtml
0014 
0015 
0016 ////////////////////////////////////////////////////////////////////////////
0017 //                                                                        //
0018 // THtml                                                                  //
0019 //                                                                        //
0020 // Html generates documentation for all ROOT classes                      //
0021 // using XHTML 1.0 transitional                                           //
0022 //                                                                        //
0023 ////////////////////////////////////////////////////////////////////////////
0024 
0025 #include "THashList.h"
0026 
0027 #include "THashTable.h"
0028 
0029 #include "TExMap.h"
0030 
0031 #include "TROOT.h"
0032 
0033 #include <map>
0034 
0035 class TClass;
0036 class TClassDocInfo;
0037 class TGClient;
0038 class TVirtualMutex;
0039 
0040 class THtml: public TObject {
0041 public:
0042    //______________________________________________________________
0043    // Helper base class.
0044    class THelperBase: public TObject {
0045    public:
0046       THelperBase(): fHtml(0) {}
0047       ~THelperBase() override;
0048       void    SetOwner(THtml* html);
0049       THtml*  GetOwner() const { return fHtml; }
0050    private:
0051       THtml*  fHtml; // object owning the helper
0052       ClassDefOverride(THelperBase, 0); // a helper object's base class
0053    };
0054 
0055    class TFileSysEntry;
0056 
0057    //______________________________________________________________
0058    // Helper class to translate between classes and their
0059    // modules. Can be derived from and thus replaced by
0060    // the user; see THtml::SetModuleDefinition().
0061    class TModuleDefinition: public THelperBase {
0062    public:
0063       virtual bool GetModule(TClass* cl, TFileSysEntry* fse, TString& out_modulename) const;
0064       ClassDefOverride(TModuleDefinition, 0); // helper class to determine a class's module
0065    };
0066 
0067    //______________________________________________________________
0068    // Helper class to translate between classes and their
0069    // filenames. Can be derived from and thus replaced by
0070    // the user; see THtml::SetFileDefinition().
0071    class TFileDefinition: public THelperBase {
0072    public:
0073       virtual bool GetDeclFileName(const TClass* cl, TString& out_filename, TString& out_fsys,
0074                                    TFileSysEntry** fse = 0) const;
0075       virtual bool GetImplFileName(const TClass* cl, TString& out_filename, TString& out_fsys,
0076                                    TFileSysEntry** fse = 0) const;
0077    protected:
0078       virtual bool GetFileName(const TClass* cl, bool decl, TString& out_filename, TString& out_fsys,
0079                                TFileSysEntry** fse = 0) const;
0080       TString MatchFileSysName(TString& filename, TFileSysEntry** fse = 0) const;
0081 
0082       void SplitClassIntoDirFile(const TString& clname, TString& dir, TString& filename) const;
0083       void NormalizePath(TString& path) const;
0084       void ExpandSearchPath(TString& path) const;
0085       ClassDefOverride(TFileDefinition, 0); // helper class to determine a class's source files
0086    };
0087 
0088    //______________________________________________________________
0089    // Helper class to translate between file names and their
0090    // version used for documentation. Can be derived from and thus
0091    // replaced by the user; see THtml::SetPathDefinition().
0092    class TPathDefinition: public THelperBase {
0093    public:
0094       virtual bool GetMacroPath(const TString& module, TString& out_dir) const;
0095       virtual bool GetIncludeAs(TClass* cl, TString& out_include_as) const;
0096       virtual bool GetFileNameFromInclude(const char* included, TString& out_fsname) const;
0097       virtual bool GetDocDir(const TString& module, TString& doc_dir) const;
0098    protected:
0099       ClassDefOverride(TPathDefinition, 0); // helper class to determine directory layouts
0100    };
0101 
0102    class TFileSysDir;
0103    class TFileSysDB;
0104    //______________________________________________________________
0105    // Utility class representing a directory entry
0106    class TFileSysEntry: public TObject {
0107    public:
0108       TFileSysEntry(const char* name, TFileSysDir* parent):
0109          fName(name), fParent(parent), fLevel(parent ? parent->GetLevel() + 1 : 0) {}
0110       ~TFileSysEntry() override
0111       {
0112          // Required since we overload TObject::Hash.
0113          ROOT::CallRecursiveRemoveIfNeeded(*this);
0114       }
0115       const char* GetName() const override { return fName; }
0116       ULong_t Hash() const override { return fName.Hash(); }
0117       virtual void GetFullName(TString& fullname, Bool_t asIncluded) const {
0118          if (fParent) {
0119             fParent->GetFullName(fullname, asIncluded);
0120             if (fullname[0])
0121                fullname += "/";
0122          } else
0123             fullname = "";
0124          fullname += fName;
0125       }
0126 
0127       TFileSysDir* GetParent() const { return fParent; }
0128       Int_t GetLevel() const { return fLevel; }
0129    protected:
0130       TString      fName; // name of the element
0131       TFileSysDir* fParent; // parent directory
0132       Int_t        fLevel; // level of directory
0133       ClassDefOverride(TFileSysEntry, 0); // an entry of the local file system
0134    };
0135 
0136    //______________________________________________________________
0137    // Utility class representing a directory
0138    class TFileSysDir: public TFileSysEntry {
0139    public:
0140       TFileSysDir(const char* name, TFileSysDir* parent):
0141          TFileSysEntry(name, parent)
0142       { fFiles.SetOwner(); fDirs.SetOwner(); }
0143       const TList* GetFiles() const { return &fFiles; }
0144       const TList* GetSubDirs() const { return &fDirs; }
0145 
0146       void Recurse(TFileSysDB* db, const char* path);
0147 
0148    protected:
0149       TList fFiles;
0150       TList fDirs;
0151       ClassDefOverride(TFileSysDir, 0); // an directory of the local file system
0152    };
0153 
0154    //______________________________________________________________
0155    // Utility class representing a root directory as specified in
0156    // THtml::GetInputPath()
0157    class TFileSysRoot: public TFileSysDir {
0158    public:
0159       TFileSysRoot(const char* name, TFileSysDB* parent):
0160          TFileSysDir(name, parent) {}
0161       void GetFullName(TString& fullname, Bool_t asIncluded) const override {
0162          // prepend directory part of THtml::GetInputPath() only
0163          // if !asIncluded
0164          fullname = "";
0165          if (!asIncluded)
0166             fullname += fName;
0167       }
0168 
0169       ClassDefOverride(TFileSysRoot, 0); // an root directory of the local file system
0170    };
0171 
0172    //______________________________________________________________
0173    // Utility class representing a directory
0174    class TFileSysDB: public TFileSysDir {
0175    public:
0176       TFileSysDB(const char* path, const char* ignorePath, Int_t maxdirlevel):
0177          TFileSysDir(path, 0), fEntries(1009, 5), fIgnorePath(ignorePath), fMaxLevel(maxdirlevel)
0178       { Fill(); }
0179 
0180       TExMap& GetMapIno() { return fMapIno; }
0181       THashTable& GetEntries() { return fEntries; }
0182       const TString& GetIgnore() const { return fIgnorePath; }
0183       Int_t   GetMaxLevel() const { return fMaxLevel; }
0184 
0185    protected:
0186       void Fill();
0187 
0188    private:
0189       TExMap   fMapIno; // inode to TFileSysDir map, to detect softlinks
0190       THashTable fEntries; // hash map of all filenames without paths
0191       TString  fIgnorePath; // regexp of path to ignore while building entry tree
0192       Int_t    fMaxLevel; // maximum level of directory nesting
0193       ClassDefOverride(TFileSysDB, 0); // instance of file system data
0194    };
0195 
0196 
0197    //______________________________________________________________
0198    // Configuration holder for path related settings
0199    struct PathInfo_t {
0200       enum EDotAccess {
0201          kDotUnknown,
0202          kDotFound,
0203          kDotNotFound
0204       };
0205 
0206       PathInfo_t():
0207          fFoundDot(kDotUnknown),
0208 #ifdef R__WIN32
0209          fInputPath("./;src/;include/"),
0210 #else
0211          fInputPath("./:src/:include/"),
0212 #endif
0213          fIncludePath("include"),
0214          // .whatever implicitly ignored, no need to add .svn!
0215          fIgnorePath("\\b(include|CVS|test|tutorials|doc|lib|python|demo|freetype-|gdk|libAfterImage|etc|config|build|bin)\\b"),
0216          fDocPath("doc"),
0217          fMacroPath("macros:."),
0218          fOutputDir("htmldoc") {}
0219 
0220       EDotAccess     fFoundDot;        // whether dot is accessible
0221       TString        fInputPath;       // directories to look for classes; prepended to Decl/ImplFileName()
0222       TString        fIncludePath;     // directory prefixes (":" delimited) to remove when quoting include files
0223       TString        fIgnorePath;      // regexp pattern for directories to ignore ("\b(CVS|\.svn)\b") for ROOT
0224       TString        fDocPath;         // subdir to check for module documentation ("doc" for ROOT)
0225       TString        fMacroPath;       // subdir of fDocPath for macros run via the Begin/End Macro directive; ("macros" for ROOT)
0226       TString        fDotDir;          // directory of GraphViz's dot binary
0227       TString        fEtcDir;          // directory containing auxiliary files
0228       TString        fOutputDir;       // output directory
0229    };
0230 
0231 
0232 public:
0233    enum EConvertOutput {
0234       kNoOutput, // do not run the source, do not show its output
0235       kInterpretedOutput, // interpret the source and show output
0236       kCompiledOutput, // run the source through ACLiC and show output
0237       kForceOutput = 0x10, // re-generate the output files (canvas PNGs)
0238       kSeparateProcessOutput = 0x20 // run the script in a separate process
0239    };
0240 
0241    THtml();
0242    ~THtml() override;
0243 
0244    static void   LoadAllLibs();
0245 
0246    // Functions to generate documentation
0247    void          Convert(const char *filename, const char *title,
0248                          const char *dirname = "", const char *relpath="../",
0249                          Int_t includeOutput = kNoOutput,
0250                          const char* context = "");
0251    void          CreateHierarchy();
0252    void          MakeAll(Bool_t force=kFALSE, const char *filter="*",
0253                          int numthreads = 1);
0254    void          MakeClass(const char *className, Bool_t force=kFALSE);
0255    void          MakeIndex(const char *filter="*");
0256    void          MakeTree(const char *className, Bool_t force=kFALSE);
0257 
0258    // Configuration setters
0259    void          SetModuleDefinition(const TModuleDefinition& md);
0260    void          SetFileDefinition(const TFileDefinition& fd);
0261    void          SetPathDefinition(const TPathDefinition& pd);
0262    void          SetProductName(const char* product) { fProductName = product; }
0263    void          SetOutputDir(const char *dir);
0264    void          SetInputDir(const char *dir);
0265    void          SetSourceDir(const char *dir) { SetInputDir(dir); }
0266    void          SetIncludePath(const char* dir) { fPathInfo.fIncludePath = dir; }
0267    void          SetEtcDir(const char* dir) { fPathInfo.fEtcDir = dir; }
0268    void          SetDocPath(const char* path) { fPathInfo.fDocPath = path; }
0269    void          SetDotDir(const char* dir) { fPathInfo.fDotDir = dir; fPathInfo.fFoundDot = PathInfo_t::kDotUnknown; }
0270    void          SetRootURL(const char* url) { fLinkInfo.fROOTURL = url; }
0271    void          SetLibURL(const char* lib, const char* url) { fLinkInfo.fLibURLs[lib] = url; }
0272    void          SetXwho(const char *xwho) { fLinkInfo.fXwho = xwho; }
0273    void          SetMacroPath(const char* path) {fPathInfo.fMacroPath = path;}
0274    void          AddMacroPath(const char* path);
0275    void          SetCounterFormat(const char* format) { fCounterFormat = format; }
0276    void          SetClassDocTag(const char* tag) { fDocSyntax.fClassDocTag = tag; }
0277    void          SetAuthorTag(const char* tag) { fDocSyntax.fAuthorTag = tag; }
0278    void          SetLastUpdateTag(const char* tag) { fDocSyntax.fLastUpdateTag = tag; }
0279    void          SetCopyrightTag(const char* tag) { fDocSyntax.fCopyrightTag = tag; }
0280    void          SetHeader(const char* file) { fOutputStyle.fHeader = file; }
0281    void          SetFooter(const char* file) { fOutputStyle.fFooter = file; }
0282    void          SetHomepage(const char* url) { fLinkInfo.fHomepage = url; }
0283    void          SetSearchStemURL(const char* url) { fLinkInfo.fSearchStemURL = url; }
0284    void          SetSearchEngine(const char* url) { fLinkInfo.fSearchEngine = url; }
0285    void          SetViewCVS(const char* url) { fLinkInfo.fViewCVS = url; }
0286    void          SetWikiURL(const char* url) { fLinkInfo.fWikiURL = url; }
0287    void          SetCharset(const char* charset) { fOutputStyle.fCharset = charset; }
0288    void          SetDocStyle(const char* style) { fDocSyntax.fDocStyle = style; }
0289 
0290    // Configuration getters
0291    const TModuleDefinition& GetModuleDefinition() const;
0292    const TFileDefinition&   GetFileDefinition() const;
0293    const TPathDefinition&   GetPathDefinition() const;
0294    const TString&      GetProductName() const { return fProductName; }
0295    const TString&      GetInputPath() const { return fPathInfo.fInputPath; }
0296    const TString&      GetOutputDir(Bool_t createDir = kTRUE) const;
0297    virtual const char* GetEtcDir() const;
0298    const TString&      GetModuleDocPath() const { return fPathInfo.fDocPath; }
0299    const TString&      GetDotDir() const { return fPathInfo.fDotDir; }
0300    const char*         GetURL(const char* lib = 0) const;
0301    const TString&      GetXwho() const { return fLinkInfo.fXwho; }
0302    const TString&      GetMacroPath() const { return fPathInfo.fMacroPath; }
0303    const char*         GetCounterFormat() const { return fCounterFormat; }
0304    const TString&      GetClassDocTag() const { return fDocSyntax.fClassDocTag; }
0305    const TString&      GetAuthorTag() const { return fDocSyntax.fAuthorTag; }
0306    const TString&      GetLastUpdateTag() const { return fDocSyntax.fLastUpdateTag; }
0307    const TString&      GetCopyrightTag() const { return fDocSyntax.fCopyrightTag; }
0308    const TString&      GetHeader() const { return fOutputStyle.fHeader; }
0309    const TString&      GetFooter() const { return fOutputStyle.fFooter; }
0310    const TString&      GetHomepage() const { return fLinkInfo.fHomepage; }
0311    const TString&      GetSearchStemURL() const { return fLinkInfo.fSearchStemURL; }
0312    const TString&      GetSearchEngine() const { return fLinkInfo.fSearchEngine; }
0313    const TString&      GetViewCVS() const { return fLinkInfo.fViewCVS; }
0314    const TString&      GetWikiURL() const { return fLinkInfo.fWikiURL; }
0315    const TString&      GetCharset() const { return fOutputStyle.fCharset; }
0316    const TString&      GetDocStyle() const { return fDocSyntax.fDocStyle; }
0317 
0318    // Functions that should only be used by TDocOutput etc.
0319    Bool_t              CopyFileFromEtcDir(const char* filename) const;
0320    virtual void        CreateAuxiliaryFiles() const;
0321    virtual TClass*     GetClass(const char *name) const;
0322    const char*         ShortType(const char *name) const;
0323    const char*         GetCounter() const { return fCounter; }
0324    void                GetModuleMacroPath(const TString& module, TString& out_path) const { GetPathDefinition().GetMacroPath(module, out_path); }
0325    virtual bool        GetDeclFileName(TClass* cl, Bool_t filesys, TString& out_name) const;
0326    void                GetDerivedClasses(TClass* cl, std::map<TClass*, Int_t>& derived) const;
0327    static const char*  GetDirDelimiter() {
0328       // ";" on windows, ":" everywhere else
0329 #ifdef R__WIN32
0330       return ";";
0331 #else
0332       return ":";
0333 #endif
0334    }
0335    virtual bool        GetImplFileName(TClass* cl, Bool_t filesys, TString& out_name) const;
0336    virtual void        GetHtmlFileName(TClass *classPtr, TString& filename) const;
0337    virtual const char* GetHtmlFileName(const char* classname) const;
0338    TList*              GetLibraryDependencies() { return &fDocEntityInfo.fLibDeps; }
0339    void                SortListOfModules() { fDocEntityInfo.fModules.Sort(); }
0340    const TList*        GetListOfModules() const { return &fDocEntityInfo.fModules; }
0341    const TList*        GetListOfClasses() const { return &fDocEntityInfo.fClasses; }
0342    TFileSysDB*         GetLocalFiles() const { if (!fLocalFiles) SetLocalFiles(); return fLocalFiles; }
0343    TVirtualMutex*      GetMakeClassMutex() const { return  fMakeClassMutex; }
0344    virtual void        GetModuleNameForClass(TString& module, TClass* cl) const;
0345    const PathInfo_t&    GetPathInfo() const { return fPathInfo; }
0346    Bool_t              HaveDot();
0347    void                HelperDeleted(THelperBase* who);
0348    static Bool_t       IsNamespace(const TClass*cl);
0349    void                SetDeclFileName(TClass* cl, const char* filename);
0350    void                SetFoundDot(Bool_t found = kTRUE);
0351    void                SetImplFileName(TClass* cl, const char* filename);
0352    void                SetBatch(Bool_t batch = kTRUE) { fBatch = batch; }
0353    Bool_t              IsBatch() const { return fBatch; }
0354    // unused
0355    void                ReplaceSpecialChars(std::ostream&, const char*) {
0356       Error("ReplaceSpecialChars",
0357             "Removed, call TDocOutput::ReplaceSpecialChars() instead!"); }
0358    void                SetEscape(char /*esc*/ ='\\') {} // for backward comp
0359 
0360 protected:
0361    struct DocSyntax_t {
0362       TString        fClassDocTag;     // tag for class documentation
0363       TString        fAuthorTag;       // tag for author
0364       TString        fLastUpdateTag;   // tag for last update
0365       TString        fCopyrightTag;    // tag for copyright
0366       TString        fDocStyle;        // doc style (only "Doc++" has special treatment)
0367    };
0368 
0369    struct LinkInfo_t {
0370       TString        fXwho;            // URL for name lookup
0371       TString        fROOTURL;         // Root URL for ROOT's reference guide for libs that are not in fLibURLs
0372       std::map<std::string, TString> fLibURLs; // URL for documentation of external libraries
0373       TString        fHomepage;        // URL of homepage
0374       TString        fSearchStemURL;   // URL stem used to build search URL
0375       TString        fSearchEngine;    // link to search engine
0376       TString        fViewCVS;         // link to ViewCVS; %f is replaced by the filename (no %f: it's appended)
0377       TString        fWikiURL;         // URL stem of class's wiki page, %c replaced by mangled class name (no %c: appended)
0378    };
0379 
0380    struct OutputStyle_t {
0381       TString        fHeader;          // header file name
0382       TString        fFooter;          // footerer file name
0383       TString        fCharset;         // Charset for doc pages
0384    };
0385 
0386    struct DocEntityInfo_t {
0387       DocEntityInfo_t(): fClasses(503, 3) {}
0388       TString        fClassFilter;     // filter used for buidling known classes
0389       THashList      fClasses;         // known classes
0390       mutable THashList fShortClassNames; // class names with default template args replaced
0391       THashList      fModules;         // known modules
0392       THashList      fLibDeps;         // Library dependencies
0393    };
0394 
0395 protected:
0396    virtual void    CreateJavascript() const;
0397    virtual void    CreateStyleSheet() const;
0398    void            CreateListOfTypes();
0399    void            CreateListOfClasses(const char* filter);
0400    virtual bool    GetDeclImplFileName(TClass* cl, bool filesys, bool decl, TString& out_name) const;
0401    void            MakeClass(void* cdi, Bool_t force=kFALSE);
0402    TClassDocInfo  *GetNextClass();
0403    void            SetLocalFiles() const;
0404 
0405    static void    *MakeClassThreaded(void* info);
0406 
0407 protected:
0408    TString        fCounter;         // counter string
0409    TString        fCounterFormat;   // counter printf-like format
0410    TString        fProductName;     // name of the product to document
0411    TIter         *fThreadedClassIter; // fClasses iterator for MakeClassThreaded
0412    Int_t          fThreadedClassCount; // counter of processed classes for MakeClassThreaded
0413    TVirtualMutex *fMakeClassMutex; // Mutex for MakeClassThreaded
0414    TGClient      *fGClient; // gClient, cached and queried through CINT
0415    DocSyntax_t     fDocSyntax;      // doc syntax configuration
0416    LinkInfo_t      fLinkInfo;       // link (URL) configuration
0417    OutputStyle_t   fOutputStyle;    // output style configuration
0418    mutable PathInfo_t fPathInfo;       // path configuration
0419    DocEntityInfo_t fDocEntityInfo;  // data for documented entities
0420    mutable TPathDefinition *fPathDef; // object translating classes to module names
0421    mutable TModuleDefinition *fModuleDef; // object translating classes to module names
0422    mutable TFileDefinition* fFileDef; // object translating classes to file names
0423    mutable TFileSysDB    *fLocalFiles; // files found locally for a given source path
0424    Bool_t  fBatch; // Whether to enable GUI output
0425 
0426    ClassDefOverride(THtml,0)  //Convert class(es) into HTML file(s)
0427 };
0428 
0429 R__EXTERN THtml *gHtml;
0430 
0431 #endif
[ Source navigation ] [ Diff markup ] [ Identifier search ] [ general search ]

This page was automatically generated by the 2.3.7 LXR engine.

The LXR team
Valid CSS 2.1! Valid HTML 4.01!