/******************************************************************************

 *

 * 

 *

 *

 * Copyright (C) 1997-2008 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 <stdio.h>

#include <stdlib.h>

#include <qfile.h>

#include <qfileinfo.h>

#include <qcstring.h>

#include <qstack.h>

#include <qdict.h>

#include <qregexp.h>

#include <ctype.h>

#include "doxygen.h"

#include "debug.h"

#include "util.h"

#include "pagedef.h"

#include "docparser.h"

#include "doctokenizer.h"

#include "cmdmapper.h"

#include "printdocvisitor.h"

#include "message.h"

#include "section.h"

#include "searchindex.h"

#include "language.h"

#include "portable.h"

// debug off

#define DBG(x) do {} while(0)

// debug to stdout

//#define DBG(x) printf x

// debug to stderr

//#define myprintf(x...) fprintf(stderr,x)

//#define DBG(x) myprintf x

#define INTERNAL_ASSERT(x) do {} while(0)

//#define INTERNAL_ASSERT(x) if (!(x)) DBG(("INTERNAL_ASSERT(%s) failed retval=0x%x: file=%s line=%d\n",#x,retval,__FILE__,__LINE__)); 

//---------------------------------------------------------------------------

static const char *sectionLevelToName[] = 

{

  "page",

  "section",

  "subsection",

  "subsubsection",

  "paragraph"

};

//---------------------------------------------------------------------------

// Parser state: global variables during a call to validatingParseDoc

static Definition *           g_scope;

static QString                g_context;

static bool                   g_inSeeBlock;

static bool                   g_insideHtmlLink;

static QStack<DocNode>        g_nodeStack;

static QStack<DocStyleChange> g_styleStack;

static QStack<DocStyleChange> g_initialStyleStack;

static QList<Definition>      g_copyStack;

static QString                g_fileName;

static QString                g_relPath;

static bool                   g_hasParamCommand;

static bool                   g_hasReturnCommand;

static QDict<void>            g_paramsFound;

static MemberDef *            g_memberDef;

static bool                   g_isExample;

static QCString               g_exampleName;

static SectionDict *          g_sectionDict;

static QCString               g_searchUrl;

static QString                g_includeFileText;

static uint                   g_includeFileOffset;

static uint                   g_includeFileLength;

// parser's context to store all global variables

struct DocParserContext

{

  Definition *scope;

  QString context;

  bool inSeeBlock;

  bool insideHtmlLink;

  QStack<DocNode> nodeStack;

  QStack<DocStyleChange> styleStack;

  QStack<DocStyleChange> initialStyleStack;

  QList<Definition> copyStack;

  QString fileName;

  QString relPath;

  bool         hasParamCommand;

  bool         hasReturnCommand;

  MemberDef *  memberDef;

  QDict<void>  paramsFound;

  bool         isExample;

  QCString     exampleName;

  SectionDict *sectionDict;

  QCString     searchUrl;

  QString  includeFileText;

  uint     includeFileOffset;

  uint     includeFileLength;

  TokenInfo *token;

};

static QStack<DocParserContext> g_parserStack;

//---------------------------------------------------------------------------

static void docParserPushContext(bool saveParamInfo=TRUE)

{

  //QCString indent;

  //indent.fill(' ',g_parserStack.count()*2+2);

  //printf("%sdocParserPushContext() count=%d\n",indent.data(),g_nodeStack.count());

  doctokenizerYYpushContext();

  DocParserContext *ctx   = new DocParserContext;

  ctx->scope              = g_scope;

  ctx->context            = g_context;

  ctx->inSeeBlock         = g_inSeeBlock;

  ctx->insideHtmlLink     = g_insideHtmlLink;

  ctx->nodeStack          = g_nodeStack;

  ctx->styleStack         = g_styleStack;

  ctx->initialStyleStack  = g_initialStyleStack;

  ctx->copyStack          = g_copyStack;

  ctx->fileName           = g_fileName;

  ctx->relPath            = g_relPath;

  if (saveParamInfo)

  {

    ctx->hasParamCommand    = g_hasParamCommand;

    ctx->hasReturnCommand   = g_hasReturnCommand;

    ctx->paramsFound        = g_paramsFound;

  }

  ctx->memberDef          = g_memberDef;

  ctx->isExample          = g_isExample;

  ctx->exampleName        = g_exampleName;

  ctx->sectionDict        = g_sectionDict;

  ctx->searchUrl          = g_searchUrl;

  ctx->includeFileText    = g_includeFileText;

  ctx->includeFileOffset  = g_includeFileOffset;

  ctx->includeFileLength  = g_includeFileLength;

  ctx->token              = g_token;

  g_token = new TokenInfo;

  g_parserStack.push(ctx);

}

static void docParserPopContext(bool keepParamInfo=FALSE)

{

  DocParserContext *ctx = g_parserStack.pop();

  g_scope               = ctx->scope;

  g_context             = ctx->context;

  g_inSeeBlock          = ctx->inSeeBlock;

  g_insideHtmlLink      = ctx->insideHtmlLink;

  g_nodeStack           = ctx->nodeStack;

  g_styleStack          = ctx->styleStack;

  g_initialStyleStack   = ctx->initialStyleStack;

  g_copyStack           = ctx->copyStack;

  g_fileName            = ctx->fileName;

  g_relPath             = ctx->relPath;

  if (!keepParamInfo)

  {

    g_hasParamCommand     = ctx->hasParamCommand;

    g_hasReturnCommand    = ctx->hasReturnCommand;

    g_paramsFound         = ctx->paramsFound;

  }

  g_memberDef           = ctx->memberDef;

  g_isExample           = ctx->isExample;

  g_exampleName         = ctx->exampleName;

  g_sectionDict         = ctx->sectionDict;

  g_searchUrl           = ctx->searchUrl;

  g_includeFileText     = ctx->includeFileText;

  g_includeFileOffset   = ctx->includeFileOffset;

  g_includeFileLength   = ctx->includeFileLength;

  delete g_token;

  g_token               = ctx->token;

  delete ctx;

  doctokenizerYYpopContext();

  //QCString indent;

  //indent.fill(' ',g_parserStack.count()*2+2);

  //printf("%sdocParserPopContext() count=%d\n",indent.data(),g_nodeStack.count());

}

//---------------------------------------------------------------------------

/*! search for an image in the imageNameDict and if found

 * copies the image to the output directory (which depends on the \a type

 * parameter).

 */

static QCString findAndCopyImage(const char *fileName,DocImage::Type type)

{

  QCString result;

  bool ambig;

  FileDef *fd;

  //printf("Search for %s\n",fileName);

  if ((fd=findFileDef(Doxygen::imageNameDict,fileName,ambig)))

  {

    QCString inputFile = fd->absFilePath();

    QFile inImage(inputFile);

    if (inImage.open(IO_ReadOnly))

    {

      result = fileName;

      int i;

      if ((i=result.findRev('/'))!=-1 || (i=result.findRev('\\'))!=-1)

      {

	result = result.right(result.length()-i-1);

      }

      //printf("fileName=%s result=%s\n",fileName,result.data());

      QCString outputDir;

      switch(type)

      {

        case DocImage::Html: 

	  if (!Config_getBool("GENERATE_HTML")) return result;

	  outputDir = Config_getString("HTML_OUTPUT");

	  break;

        case DocImage::Latex: 

	  if (!Config_getBool("GENERATE_LATEX")) return result;

	  outputDir = Config_getString("LATEX_OUTPUT");

	  break;

        case DocImage::Rtf:

	  if (!Config_getBool("GENERATE_RTF")) return result;

	  outputDir = Config_getString("RTF_OUTPUT");

	  break;

      }

      QCString outputFile = outputDir+"/"+result;

      if (outputFile!=inputFile) // prevent copying to ourself

      {

        QFile outImage(outputFile.data());

        if (outImage.open(IO_WriteOnly)) // copy the image

        {

          char *buffer = new char[inImage.size()];

          inImage.readBlock(buffer,inImage.size());

          outImage.writeBlock(buffer,inImage.size());

          outImage.flush();

          delete[] buffer;

          if (type==DocImage::Html) Doxygen::indexList.addImageFile(result);

        }

        else

        {

          warn_doc_error(g_fileName,doctokenizerYYlineno,

              "Warning: could not write output image %s",outputFile.data());

        }

      }

    }

    else

    {

      warn_doc_error(g_fileName,doctokenizerYYlineno,

	  "Warning: could not open image %s",fileName);

    }

    if (type==DocImage::Latex && Config_getBool("USE_PDFLATEX") && 

	fd->name().right(4)==".eps"

       )

    { // we have an .eps image in pdflatex mode => convert it to a pdf.

      QCString outputDir = Config_getString("LATEX_OUTPUT");

      QCString baseName  = fd->name().left(fd->name().length()-4);

      QCString epstopdfArgs(4096);

      epstopdfArgs.sprintf("\"%s/%s.eps\" --outfile=\"%s/%s.pdf\"",

                           outputDir.data(), baseName.data(),

			   outputDir.data(), baseName.data());

      if (portable_system("epstopdf",epstopdfArgs)!=0)

      {

	err("Error: Problems running epstopdf. Check your TeX installation!\n");

      }

      return baseName;

    }

  }

  else if (ambig)

  {

    QCString text;

    text.sprintf("Warning: image file name %s is ambigious.\n",fileName);

    text+="Possible candidates:\n";

    text+=showFileDefMatches(Doxygen::imageNameDict,fileName);

    warn_doc_error(g_fileName,doctokenizerYYlineno,text);

  }

  else

  {

    result=fileName;

    if (result.left(5)!="http:" && result.left(6)!="https:")

    {

      warn_doc_error(g_fileName,doctokenizerYYlineno,

           "Warning: image file %s is not found in IMAGE_PATH: "  

	   "assuming external image.",fileName

          );

    }

  }

  return result;

}

/*! Collects the parameters found with \@param or \@retval commands

 *  in a global list g_paramsFound. If \a isParam is set to TRUE

 *  and the parameter is not an actual parameter of the current

 *  member g_memberDef, then a warning is raised (unless warnings

 *  are disabled altogether).

 */

static void checkArgumentName(const QString &name,bool isParam)

{                

  if (!Config_getBool("WARN_IF_DOC_ERROR")) return;

  if (g_memberDef==0) return; // not a member

  LockingPtr<ArgumentList> al=g_memberDef->isDocsForDefinition() ? 

		   g_memberDef->argumentList() :

                   g_memberDef->declArgumentList();

  //printf("isDocsForDefinition()=%d\n",g_memberDef->isDocsForDefinition());

  if (al==0) return; // no argument list

  static QRegExp re("[a-zA-Z0-9_\\x80-\\xFF]+\\.*");

  int p=0,i=0,l;

  while ((i=re.match(name,p,&l))!=-1) // to handle @param x,y

  {

    QString aName=name.mid(i,l);

    //printf("aName=`%s'\n",aName.data());

    ArgumentListIterator ali(*al);

    Argument *a;

    bool found=FALSE;

    for (ali.toFirst();(a=ali.current());++ali)

    {

      QString argName = g_memberDef->isDefine() ? a->type : a->name;

      argName=argName.stripWhiteSpace();

      //printf("argName=`%s'\n",argName.data());

      if (argName.right(3)=="...") argName=argName.left(argName.length()-3);

      if (aName==argName) 

      {

	//printf("adding `%s'\n",aName.data());

	g_paramsFound.insert(aName,(void *)(0x8));

	found=TRUE;

	break;

      }

    }

    if (!found && isParam)

    {

      //printf("member type=%d\n",memberDef->memberType());

      QString scope=g_memberDef->getScopeString();

      if (!scope.isEmpty()) scope+="::"; else scope="";

      QString inheritedFrom = "";

      QString docFile = g_memberDef->docFile();

      int docLine = g_memberDef->docLine();

      MemberDef *inheritedMd = g_memberDef->inheritsDocsFrom();

      if (inheritedMd) // documentation was inherited

      {

        inheritedFrom.sprintf(" inherited from member %s at line "

            "%d in file %s",inheritedMd->name().data(),

            inheritedMd->docLine(),inheritedMd->docFile().data());

        docFile = g_memberDef->getDefFileName();

        docLine = g_memberDef->getDefLine();

      }

      warn_doc_error(docFile,docLine,

	  "Warning: argument '%s' of command @param "

	  "is not found in the argument list of %s%s%s%s",

	  aName.data(),scope.data(),g_memberDef->name().data(),

	  argListToString(al.pointer()).data(),inheritedFrom.data());

    }

    p=i+l;

  }

}

/*! Checks if the parameters that have been specified using \@param are

 *  indeed all paramters.

 *  Must be called after checkArgumentName() has been called for each

 *  argument.

 */

static void checkUndocumentedParams()

{

  if (g_memberDef && g_hasParamCommand && Config_getBool("WARN_IF_DOC_ERROR"))

  {

    LockingPtr<ArgumentList> al=g_memberDef->isDocsForDefinition() ? 

      g_memberDef->argumentList() :

      g_memberDef->declArgumentList();

    if (al!=0)

    {

      ArgumentListIterator ali(*al);

      Argument *a;

      bool found=FALSE;

      for (ali.toFirst();(a=ali.current());++ali)

      {

        QString argName = g_memberDef->isDefine() ? a->type : a->name;

        argName=argName.stripWhiteSpace();

        if (argName.right(3)=="...") argName=argName.left(argName.length()-3);

        if (getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python && argName=="self")

        { 

          // allow undocumented self parameter for Python

        }

        else if (!argName.isEmpty() && g_paramsFound.find(argName)==0 && a->docs.isEmpty()) 

        {

          found = TRUE;

          break;

        }

      }

      if (found)

      {

        bool first=TRUE;

        QString errMsg=

            "Warning: The following parameters of "+

            QString(g_memberDef->qualifiedName()) + 

            QString(argListToString(al.pointer())) +

            " are not documented:\n";

        for (ali.toFirst();(a=ali.current());++ali)

        {

          QString argName = g_memberDef->isDefine() ? a->type : a->name;

          argName=argName.stripWhiteSpace();

          if (getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python && argName=="self")

          { 

            // allow undocumented self parameter for Python

          }

          else if (!argName.isEmpty() && g_paramsFound.find(argName)==0) 

          {

            if (!first)

            {

              errMsg+="\n";

            }

            else

            {

              first=FALSE;

            }

            errMsg+="  parameter '"+argName+"'";

          }

        }

        if (g_memberDef->inheritsDocsFrom())

        {

           warn_doc_error(g_memberDef->getDefFileName(),

                          g_memberDef->getDefLine(),

                          substitute(errMsg,"%","%%"));

        }

        else

        {

           warn_doc_error(g_memberDef->docFile(),

                          g_memberDef->docLine(),

                          substitute(errMsg,"%","%%"));

        }

      }

    }

  }

}

/*! Check if a member has documentation for its parameter and or return

 *  type, if applicable. If found this will be stored in the member, this

 *  is needed as a member can have brief and detailed documentation, while

 *  only one of these needs to document the parameters.

 */

static void detectNoDocumentedParams()

{

  if (g_memberDef && Config_getBool("WARN_NO_PARAMDOC"))

  {

    LockingPtr<ArgumentList> al     = g_memberDef->argumentList();

    LockingPtr<ArgumentList> declAl = g_memberDef->declArgumentList();

    QString returnType   = g_memberDef->typeString();

    bool isPython = getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python;

    if (!g_memberDef->hasDocumentedParams() &&

        g_hasParamCommand)

    {

      //printf("%s->setHasDocumentedParams(TRUE);\n",g_memberDef->name().data());

      g_memberDef->setHasDocumentedParams(TRUE);

    }

    else if (!g_memberDef->hasDocumentedParams())

    {

      bool allDoc=TRUE; // no paramater => all parameters are documented

      if ( // member has parameters

             al!=0 &&       // but the member has a parameter list

             al->count()>0  // with at least one parameter (that is not void)

         )

      {

        ArgumentListIterator ali(*al);

        Argument *a;

        // see if all parameters have documentation

        for (ali.toFirst();(a=ali.current()) && allDoc;++ali)

        {

          if (!a->name.isEmpty() && a->type!="void" &&

              !(isPython && a->name=="self")

             )

          {

            allDoc = !a->docs.isEmpty();

          }

          //printf("a->type=%s a->name=%s doc=%s\n",

          //        a->type.data(),a->name.data(),a->docs.data());

        }

        if (!allDoc && declAl!=0) // try declaration arguments as well

        {

          allDoc=TRUE;

          ArgumentListIterator ali(*declAl);

          Argument *a;

          for (ali.toFirst();(a=ali.current()) && allDoc;++ali)

          {

            if (!a->name.isEmpty() && a->type!="void" &&

                !(isPython && a->name=="self")

               )

            {

              allDoc = !a->docs.isEmpty();

            }

            //printf("a->name=%s doc=%s\n",a->name.data(),a->docs.data());

          }

        }

      }

      if (allDoc) 

      {

        //printf("%s->setHasDocumentedParams(TRUE);\n",g_memberDef->name().data());

        g_memberDef->setHasDocumentedParams(TRUE);

      }