xmlgen.cpp

doxygen(一个自动从源代码生成文档的工具)的源代码

/******************************************************************************
 *
 * $Id: xml.cpp,v 1.2 2001/01/01 10:15:18 root Exp $
 *
 *
 * Copyright (C) 1997-2001 by Dimitri van Heesch.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */

#include <stdlib.h>

#include "qtbc.h"
#include "xmlgen.h"
#include "doxygen.h"
#include "message.h"
#include "config.h"
#include "classlist.h"
#include "util.h"
#include "defargs.h"
#include "outputgen.h"
#include "doc.h"
#include "dot.h"
#include "code.h"

#include <qdir.h>
#include <qfile.h>
#include <qtextstream.h>

#define XML_DB(x)

QCString sectionTypeToString(BaseOutputDocInterface::SectionTypes t)
{
  switch (t)
  {
    case BaseOutputDocInterface::See:         return "see";
    case BaseOutputDocInterface::Return:      return "return";
    case BaseOutputDocInterface::Author:      return "author";
    case BaseOutputDocInterface::Version:     return "version";
    case BaseOutputDocInterface::Since:       return "since";
    case BaseOutputDocInterface::Date:        return "date";
    case BaseOutputDocInterface::Bug:         return "bug";
    case BaseOutputDocInterface::Note:        return "note";
    case BaseOutputDocInterface::Warning:     return "warning";
    case BaseOutputDocInterface::Par:         return "par";
    case BaseOutputDocInterface::Deprecated:  return "deprecated";
    case BaseOutputDocInterface::Pre:         return "pre";
    case BaseOutputDocInterface::Post:        return "post";
    case BaseOutputDocInterface::Invar:       return "invariant";
    case BaseOutputDocInterface::Remark:      return "remark";
    case BaseOutputDocInterface::Attention:   return "attention";
    case BaseOutputDocInterface::Todo:        return "todo";
    case BaseOutputDocInterface::Test:        return "test";
    case BaseOutputDocInterface::RCS:         return "rcs";
    case BaseOutputDocInterface::EnumValues:  return "enumvalues";
    case BaseOutputDocInterface::Examples:    return "examples";
  }
  return "illegal";
}

inline void writeXMLString(QTextStream &t,const char *s)
{
  t << convertToXML(s);
}

void writeXMLLink(QTextStream &t,const char *extRef,const char *compoundId,
                  const char *anchorId,const char *text)
{
  t << "<ref idref=\"" << compoundId << "\"";
  if (extRef)
  {
    t << " external=\"" << extRef << "\"";
  }
  if (anchorId)
  {
    t << " anchor=\"" << anchorId << "\"";
  }
  t << ">";
  writeXMLString(t,text);
  t << "</ref>";
}

class TextGeneratorXMLImpl : public TextGeneratorIntf
{
  public:
    TextGeneratorXMLImpl(QTextStream &t): m_t(t) {}
    void writeString(const char *s) const
    {
      writeXMLString(m_t,s); 
    }
    void writeBreak() const {}
    void writeLink(const char *extRef,const char *file,
                   const char *anchor,const char *text
                  ) const
    {
      writeXMLLink(m_t,extRef,file,anchor,text);
    }
  private:
    QTextStream &m_t;
};

template<class T> class ValStack
{
  public:
    ValStack() : m_values(10), m_sp(0), m_size(10) {}
    virtual ~ValStack() {}
    ValStack(const ValStack &s)
    {
      m_values=s.m_values.copy();
      m_sp=s.m_sp;
      m_size=s.m_size;
    }
    ValStack &operator=(const ValStack &s)
    {
      m_values=s.m_values.copy();
      m_sp=s.m_sp;
      m_size=s.m_size;
      return *this;
    }
    void push(T v)
    {
      m_sp++;
      if (m_sp>=m_size)
      {
        m_size+=10;
        m_values.resize(m_size);
      }
      m_values[m_sp]=v;
    }
    T pop()
    {
      ASSERT(m_sp!=0);
      return m_values[m_sp--];
    }
    T& top()
    {
      ASSERT(m_sp!=0);
      return m_values[m_sp];
    }
    bool isEmpty()
    {
      return m_sp==0;
    }
    uint count() const
    {
      return m_sp;
    }
    
  private:
    QArray<T> m_values;
    int m_sp;
    int m_size;
};

/*! This class is used by the documentation parser.
 *  Its methods are called when some XML text or markup
 *  needs to be written.
 */
class XMLGenerator : public OutputDocInterface
{
  public:

    // helper functions
    
    void startParMode()
    {
      if (!m_inParStack.isEmpty() && !m_inParStack.top())
      {
        m_inParStack.top() = TRUE;
        m_t << "<para>" << endl;
        XML_DB(("start par at level=%d\n",m_inParStack.count());)
      }
      else if (m_inParStack.isEmpty())
      {
        m_inParStack.push(TRUE);
        m_t << "<para>" << endl;
        XML_DB(("start par at level=%d\n",m_inParStack.count());)
      }
    }
    void endParMode()
    {
      if (!m_inParStack.isEmpty() && m_inParStack.top())
      {
        m_inParStack.top() = FALSE;
        m_t << "</para>" << endl;
        XML_DB(("end par at level=%d\n",m_inParStack.count());)
      }
    }
    void startNestedPar()
    {
      m_inParStack.push(FALSE);
      XML_DB(("enter par level=%d\n",m_inParStack.count());)
    }
    void endNestedPar()
    {
      XML_DB(("leave par level=%d\n",m_inParStack.count());)
      if (m_inParStack.pop())
      {
        m_t << "</para>" << endl;
      }
      else
      {
        XML_DB(("ILLEGAL par level!\n");)
      }
    }
  
    // Standard generator functions to be implemented by all generators

    void docify(const char *s) 
    {
      startParMode();
      writeXMLString(m_t,s);
    }
    void writeChar(char c) 
    {
      startParMode();
      char s[2];s[0]=c;s[1]=0;
      docify(s);
    }
    void writeString(const char *text) 
    {
      startParMode();
      m_t << text;
    }
    void startItemList()       
    { 
      startParMode();
      m_t << "<itemizedlist>" << endl;; 
      m_inListStack.push(TRUE);
    }
    void startEnumList()       
    { 
      startParMode();
      m_t << "<orderedlist>"; 
      m_inListStack.push(TRUE);
    }
    void writeListItem()       
    { 
      if (!m_inListStack.isEmpty() && m_inListStack.top()) // first element
      {
        m_inListStack.top()=FALSE;
      }
      else // not first element, end previous element first
      {
        endParMode();
        endNestedPar();
        m_t << "</listitem>" << endl; 
      }
      m_t << "<listitem>"; 
      startNestedPar();
    }
    void endItemList()         
    {
      if (!m_inListStack.isEmpty() && !m_inListStack.pop()) // first element
      {
        endParMode(); 
        endNestedPar();
        m_t << "</listitem>" << endl; 
      }
      m_t << "</itemizedlist>" << endl; 
    }
    void endEnumList()         
    { 
      if (!m_inListStack.isEmpty() && !m_inListStack.pop()) // first element
      {
        endParMode(); 
        m_t << "</listitem>" << endl; 
        endNestedPar(); 
      }
      m_t << "</orderedlist>" << endl; 
    }
    void newParagraph()        
    { 
      endParMode();
      startParMode();
    }
    void startBold()           
    { 
      startParMode();
      m_t << "<bold>"; // non DocBook
    }
    void endBold()             
    { 
      m_t << "</bold>"; // non DocBook
    }
    void startTypewriter()     
    { 
      startParMode();
      m_t << "<computeroutput>";
    }
    void endTypewriter()       
    { 
      m_t << "</computeroutput>";
    }
    void startEmphasis()       
    { 
      startParMode();
      m_t << "<emphasis>";
    }
    void endEmphasis()         
    { 
      m_t << "</emphasis>";
    }
    void startCodeFragment()   
    { 
      m_t << "<programlisting>";
    }
    void endCodeFragment()     
    { 
      m_t << "</programlisting>"; 
    }
    void startPreFragment()    
    { 
      m_t << "<programlisting>";
    }
    void endPreFragment()      
    { 
      m_t << "</programlisting>"; 
    }
    void writeRuler()          
    { 
      startParMode();
      m_t << "<hruler/>"; 
    }
    void startDescription()    
    { 
      startParMode();
      m_t << "<variablelist>"; 
      m_inListStack.push(TRUE);
    }
    void endDescription()      
    { 
      if (!m_inListStack.isEmpty() && !m_inListStack.pop()) // first element
      {
        endNestedPar(); 
        m_t << "</listitem>" << endl; 
      }
      m_t << "</variablelist>"; 
      if (!m_inListStack.isEmpty()) m_inListStack.pop();
    }
    void startDescItem()       
    { 
      if (!m_inListStack.isEmpty() && m_inListStack.top()) // first element
      {
        m_inListStack.top()=FALSE;
      }
      else // not first element, end previous element first
      {
        endNestedPar();
        m_t << "</listitem>"; 
      }
      m_t << "<varlistentry><term>"; 
    }
    void endDescItem()         
    { 
      m_t << "</term></varlistentry><listitem>"; 
      startNestedPar();
    }
    void startDescList(SectionTypes st)       
    { 
      startParMode();
      m_t << "<simplesect kind=\"" << sectionTypeToString(st);
      m_t << "\"><title>"; 
    }
    void endDescList()         
    { 
      endNestedPar();
      m_t << "</simplesect>";
    }
    void startParamList(ParamListTypes t)      
    { 
      startParMode();
      QCString kind;
      switch(t)
      {
        case Param:       kind="param";     break;
        case RetVal:      kind="retval";    break;
        case Exception:   kind="exception"; break;
      }
      m_t << "<parameterlist kind=\"" << kind << "\"><title>"; // non DocBook
      m_inParamList = TRUE;
    }
    void endParamList()        
    { 
      m_inParamList = FALSE;
      m_t << "</parameterlist>";
    }
    void endDescTitle()        
    { 
      m_t << "</title>"; 
      if (!m_inParamList) startNestedPar();
    }
    void writeDescItem()       { }
    void startDescTable()      { }
    void endDescTable()        { }
    void startDescTableTitle() 
    { 
      m_t << "<parametername>"; // non docbook
    }
    void endDescTableTitle()   
    { 
      m_t << "</parametername>"; // non docbook
    }
    void startDescTableData()  
    { 
      m_t << "<parameterdescription>"; // non docbook
      startNestedPar();
    }
    void endDescTableData()    
    { 
      endNestedPar();
      m_t << "</parameterdescription>"; // non docbook
    }
    void lineBreak()           
    { 
      startParMode();
      m_t << "<linebreak/>"; // non docbook
    }
    void writeNonBreakableSpace(int num) 
    { 
      int i;for (i=0;i<num;i++) m_t << "&nbsp;"; 
    }
    
    void writeObjectLink(const char *ref,const char *file,
                         const char *anchor, const char *text) 
    {
      startParMode();
      writeXMLLink(m_t,ref,file,anchor,text);
    }
    void writeCodeLink(const char *ref,const char *file,
                               const char *anchor,const char *text) 
    {
      writeXMLLink(m_t,ref,file,anchor,text);
    }
    void startHtmlLink(const char *url)
    {
      startParMode();
      m_t << "<ulink url=\"" << url << "\">";
    }
    void endHtmlLink()
    {
      m_t << "</ulink>";
    }
    void writeMailLink(const char *url) 
    {
      startParMode();
      m_t << "<email>";
      docify(url); 
      m_t << "</email>";
    }
    void startSection(const char *id,const char *,bool)