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

     2  *

     3  * Copyright (C) 1997-2008 by Dimitri van Heesch.

     4  *

     5  * Permission to use, copy, modify, and distribute this software and its

     6  * documentation under the terms of the GNU General Public License is hereby 

     7  * granted. No representations are made about the suitability of this software 

     8  * for any purpose. It is provided "as is" without express or implied warranty.

     9  * See the GNU General Public License for more details.

    10  *

    11  * Documents produced by Doxygen are derivative works derived from the

    12  * input used in their production; they are not affected by this license.

    13  *

    14  */

    15   

    16 %{

    17 

    18 /*

    19  *	includes

    20  */

    21 #include <stdio.h>

    22 #include <stdlib.h>

    23 #include <assert.h>

    24 #include <ctype.h>

    25 

    26 #include "qtbc.h"

    27 #include <qarray.h>

    28 #include <qstack.h>

    29 #include <qregexp.h>

    30 #include <unistd.h>

    31 #include <qfile.h>

    32   

    33 #include "scanner.h"

    34 #include "entry.h"

    35 #include "doxygen.h"

    36 #include "message.h"

    37 #include "config.h"

    38 #include "util.h"

    39 #include "index.h"

    40 #include "defargs.h"

    41 #include "language.h"

    42 #include "outputlist.h"

    43 #include "membergroup.h"

    44 #include "reflist.h"

    45 #include "debug.h"

    46 #include "parserintf.h"

    47 

    48 // forward declarations

    49 static bool handleBrief(const QCString &);

    50 static bool handleFn(const QCString &);

    51 static bool handleDef(const QCString &);

    52 static bool handleOverload(const QCString &);

    53 static bool handleEnum(const QCString &);

    54 static bool handleDefGroup(const QCString &);

    55 static bool handleAddToGroup(const QCString &);

    56 static bool handleWeakGroup(const QCString &);

    57 static bool handleNamespace(const QCString &);

    58 static bool handlePackage(const QCString &);

    59 static bool handleClass(const QCString &);

    60 static bool handleHeaderFile(const QCString &);

    61 static bool handleProtocol(const QCString &);

    62 static bool handleCategory(const QCString &);

    63 static bool handleUnion(const QCString &);

    64 static bool handleStruct(const QCString &);

    65 static bool handleInterface(const QCString &);

    66 static bool handleIdlException(const QCString &);

    67 static bool handlePage(const QCString &);

    68 static bool handleMainpage(const QCString &);

    69 static bool handleFile(const QCString &);

    70 static bool handleDir(const QCString &);

    71 static bool handleExample(const QCString &);

    72 static bool handleDetails(const QCString &);

    73 static bool handleName(const QCString &);

    74 static bool handleTodo(const QCString &);

    75 static bool handleTest(const QCString &);

    76 static bool handleBug(const QCString &);

    77 static bool handleSubpage(const QCString &s);

    78 static bool handleDeprecated(const QCString &);

    79 static bool handleXRefItem(const QCString &);

    80 static bool handleRelated(const QCString &);

    81 static bool handleRelatedAlso(const QCString &);

    82 static bool handleMemberOf(const QCString &);

    83 static bool handleRefItem(const QCString &);

    84 static bool handleSection(const QCString &);

    85 static bool handleAnchor(const QCString &);

    86 static bool handleFormatBlock(const QCString &);

    87 static bool handleAddIndex(const QCString &);

    88 static bool handleIf(const QCString &);

    89 static bool handleIfNot(const QCString &);

    90 static bool handleElseIf(const QCString &);

    91 static bool handleElse(const QCString &);

    92 static bool handleEndIf(const QCString &);

    93 static bool handleIngroup(const QCString &);

    94 static bool handleNoSubGrouping(const QCString &);

    95 static bool handleShowInitializer(const QCString &);

    96 static bool handleHideInitializer(const QCString &);

    97 static bool handleCallgraph(const QCString &);

    98 static bool handleCallergraph(const QCString &);

    99 static bool handleInternal(const QCString &);

   100 static bool handleLineBr(const QCString &);

   101 static bool handleStatic(const QCString &);

   102 static bool handlePure(const QCString &);

   103 static bool handlePrivate(const QCString &);

   104 static bool handlePrivateSection(const QCString &);

   105 static bool handleProtected(const QCString &);

   106 static bool handleProtectedSection(const QCString &);

   107 static bool handlePublic(const QCString &s);

   108 static bool handlePublicSection(const QCString &s);

   109 static bool handleInherit(const QCString &);

   110 static bool handleExtends(const QCString &);

   111 

   112 typedef bool (*DocCmdFunc)(const QCString &name);

   113 

   114 struct DocCmdMap

   115 {

   116   const char *cmdName;

   117   DocCmdFunc handler;

   118   bool endsBrief;

   119 };

   120 

   121 // map of command to handler function

   122 static DocCmdMap docCmdMap[] =

   123 {

   124   // command name      handler function         ends brief description

   125   { "brief",           &handleBrief,            FALSE },

   126   { "short",           &handleBrief,            FALSE },

   127   { "fn",              &handleFn,               FALSE },

   128   { "var",             &handleFn,               FALSE },

   129   { "typedef",         &handleFn,               FALSE },

   130   { "property",        &handleFn,               FALSE },

   131   { "def",             &handleDef,              FALSE },

   132   { "overload",        &handleOverload,         FALSE },

   133   { "enum",            &handleEnum,             FALSE },

   134   { "defgroup",        &handleDefGroup,         FALSE },

   135   { "addtogroup",      &handleAddToGroup,       FALSE },

   136   { "weakgroup",       &handleWeakGroup,        FALSE },

   137   { "namespace",       &handleNamespace,        FALSE },

   138   { "package",         &handlePackage,          FALSE },

   139   { "class",           &handleClass,            FALSE },

   140   { "headerfile",      &handleHeaderFile,       FALSE },

   141   { "protocol",        &handleProtocol,         FALSE },

   142   { "category",        &handleCategory,         FALSE },

   143   { "union",           &handleUnion,            FALSE },

   144   { "struct",          &handleStruct,           FALSE },

   145   { "interface",       &handleInterface,        FALSE },

   146   { "idlexcept",       &handleIdlException,     FALSE },

   147   { "page",            &handlePage,             FALSE },

   148   { "mainpage",        &handleMainpage,         FALSE },

   149   { "file",            &handleFile,             FALSE },

   150   { "dir",             &handleDir,              FALSE },

   151   { "example",         &handleExample,          FALSE },

   152   { "details",         &handleDetails,          TRUE  },

   153   { "name",            &handleName,             FALSE },

   154   { "todo",            &handleTodo,             FALSE }, // end brief will be done differently

   155   { "test",            &handleTest,             FALSE }, // end brief will be done differently

   156   { "bug",             &handleBug,              FALSE }, // end brief will be done differently

   157   { "deprecated",      &handleDeprecated,       FALSE }, // end brief will be done differently

   158   { "xrefitem",        &handleXRefItem,         FALSE }, // end brief will be done differently

   159   { "related",         &handleRelated,          TRUE  },

   160   { "relates",         &handleRelated,          TRUE  },

   161   { "relatedalso",     &handleRelatedAlso,      TRUE  },

   162   { "relatesalso",     &handleRelatedAlso,      TRUE  },

   163   { "refitem",         &handleRefItem,          TRUE  },

   164   { "subpage",         &handleSubpage,          TRUE  },

   165   { "section",         &handleSection,          TRUE  },

   166   { "subsection",      &handleSection,          TRUE  },

   167   { "subsubsection",   &handleSection,          TRUE  },

   168   { "paragraph",       &handleSection,          TRUE  },

   169   { "anchor",          &handleAnchor,           TRUE  },

   170   { "verbatim",        &handleFormatBlock,      TRUE },

   171   { "latexonly",       &handleFormatBlock,      FALSE },

   172   { "htmlonly",        &handleFormatBlock,      FALSE },

   173   { "xmlonly",         &handleFormatBlock,      FALSE },

   174   { "rtfonly",         &handleFormatBlock,      FALSE },

   175   { "manonly",         &handleFormatBlock,      FALSE },

   176   { "dot",             &handleFormatBlock,      TRUE  },

   177   { "msc",             &handleFormatBlock,      TRUE  },

   178   { "code",            &handleFormatBlock,      TRUE  },

   179   { "addindex",        &handleAddIndex,         FALSE },

   180   { "if",              &handleIf,               FALSE },

   181   { "ifnot",           &handleIfNot,            FALSE },

   182   { "elseif",          &handleElseIf,           FALSE },

   183   { "else",            &handleElse,             FALSE },

   184   { "endif",           &handleEndIf,            FALSE },

   185   { "ingroup",         &handleIngroup,          FALSE },

   186   { "nosubgrouping",   &handleNoSubGrouping,    FALSE },

   187   { "showinitializer", &handleShowInitializer,  FALSE },

   188   { "hideinitializer", &handleHideInitializer,  FALSE },

   189   { "callgraph",       &handleCallgraph,        FALSE },

   190   { "callergraph",     &handleCallergraph,      FALSE },

   191   { "internal",        &handleInternal,         TRUE  },

   192   { "_linebr",         &handleLineBr,           FALSE },

   193   { "static",          &handleStatic,           FALSE },

   194   { "pure",            &handlePure,             FALSE },

   195   { "private",         &handlePrivate,          FALSE },

   196   { "privatesection",  &handlePrivateSection,   FALSE },

   197   { "protected",       &handleProtected,        FALSE },

   198   { "protectedsection",&handleProtectedSection, FALSE },

   199   { "public",          &handlePublic,           FALSE },

   200   { "publicsection",   &handlePublicSection,    FALSE },

   201   { "inherit",         &handleInherit,          TRUE  },

   202   { "extends",         &handleExtends,          TRUE  },

   203   { "implements",      &handleExtends,          TRUE  },

   204   { "memberof",        &handleMemberOf,         TRUE  },

   205   { "arg",             0,                       TRUE  },

   206   { "attention",       0,                       TRUE  },

   207   { "author",          0,                       TRUE  },

   208   { "authors",         0,                       TRUE  },

   209   { "copydoc",         0,                       TRUE  },

   210   { "copybrief",       0,                       FALSE },

   211   { "copydetails",     0,                       TRUE  },

   212   { "date",            0,                       TRUE  },

   213   { "dotfile",         0,                       TRUE  },

   214   { "htmlinclude",     0,                       TRUE  },

   215   { "image",           0,                       TRUE  },

   216   { "include",         0,                       TRUE  },

   217   { "includelineno",   0,                       TRUE  },

   218   { "invariant",       0,                       TRUE  },

   219   { "li",              0,                       TRUE  },

   220   { "line",            0,                       TRUE  },

   221   { "note",            0,                       TRUE  },

   222   { "par",             0,                       TRUE  },

   223   { "param",           0,                       TRUE  },

   224   { "tparam",          0,                       TRUE  },

   225   { "post",            0,                       TRUE  },

   226   { "pre",             0,                       TRUE  },

   227   { "remark",          0,                       TRUE  },

   228   { "remarks",         0,                       TRUE  },

   229   { "result",          0,                       TRUE  },

   230   { "return",          0,                       TRUE  },

   231   { "returns",         0,                       TRUE  },

   232   { "retval",          0,                       TRUE  },

   233   { "sa",              0,                       TRUE  },

   234   { "see",             0,                       TRUE  },

   235   { "since",           0,                       TRUE  },

   236   { "throw",           0,                       TRUE  },

   237   { "throws",          0,                       TRUE  },

   238   { "until",           0,                       TRUE  },

   239   { "verbinclude",     0,                       TRUE  },

   240   { "version",         0,                       TRUE  },

   241   { "warning",         0,                       TRUE  },

   242   { 0, 0, FALSE }

   243 };

   244 

   245 /** @brief Command mapper.

   246  *

   247  *  Maps a command name (as found in a comment block) onto a

   248  *  specific handler function.

   249  */

   250 class DocCmdMapper

   251 {

   252   public:

   253     struct Cmd

   254     {

   255       DocCmdFunc func;

   256       bool endsBrief;

   257     };

   258 

   259     /** maps a command name to a handler function */

   260     static Cmd *map(const char *name)

   261     {

   262       return instance()->find(name);

   263     }

   264 

   265     /** release the singleton */

   266     static void freeInstance()

   267     {

   268       delete s_instance; s_instance=0;

   269     }

   270 

   271   private:

   272     static DocCmdMapper *instance()

   273     {

   274       if (s_instance==0) s_instance = new DocCmdMapper;

   275       return s_instance;

   276     }

   277 

   278     DocCmdMapper() : m_map(113)

   279     {

   280       m_map.setAutoDelete(TRUE);

   281       DocCmdMap *p = docCmdMap;

   282       while (p->cmdName)

   283       {

   284 	if (m_map.find(p->cmdName)!=0)

   285 	{

   286 	  printf("Error: DocCmdMapper: command %s already added\n",p->cmdName);

   287 	  exit(1);

   288 	}

   289 	Cmd *cmd = new Cmd;

   290 	cmd->func = p->handler;

   291 	cmd->endsBrief = p->endsBrief;

   292 	m_map.insert(p->cmdName,cmd);

   293 	p++;

   294       }

   295     }

   296 

   297     Cmd *find(const char *name)

   298     {

   299       return m_map.find(name);

   300     }

   301     QDict<Cmd> m_map;

   302     static DocCmdMapper *s_instance;

   303 };

   304 

   305 DocCmdMapper *DocCmdMapper::s_instance=0;

   306   

   307   

   308 #define YY_NEVER_INTERACTIVE 1

   309 

   310 enum XRefKind

   311 {

   312   XRef_Item,

   313   XRef_Todo,

   314   XRef_Test,

   315   XRef_Bug,

   316   XRef_Deprecated,

   317   XRef_None

   318 };

   319 

   320 enum OutputContext

   321 {

   322   OutputDoc,

   323   OutputBrief,

   324   OutputXRef,

   325   OutputInbody

   326 };

   327 

   328 enum GuardType

   329 {

   330   Guard_If,

   331   Guard_IfNot,

   332   Guard_Skip

   333 };

   334 

   335 class GuardedSection

   336 {

   337   public:

   338     GuardedSection(bool enabled,bool parentVisible) 

   339       : m_enabled(enabled),m_parentVisible(parentVisible) {}

   340     bool isEnabled() const { return m_enabled; }

   341     bool parentVisible() const { return m_parentVisible; }

   342   

   343   private:

   344     bool m_enabled;

   345     bool m_parentVisible;

   346 };

   347 

   348 void openGroup(Entry *e,const char *file,int line);

   349 void closeGroup(Entry *e,const char *file,int line);

   350 void initGroupInfo(Entry *e);

   351 static void groupAddDocs(Entry *e,const char *fileName);

   352 

   353 /* -----------------------------------------------------------------

   354  *

   355  *	statics

   356  */

   357 

   358 static ParserInterface *langParser;          // the language parser that is calling us

   359 static QCString         inputString;         // input string

   360 static int		inputPosition;       // read pointer

   361 static QCString		yyFileName;          // file name that is read from

   362 static int		yyLineNr;            // line number in the input

   363 static bool             inBody;              // was the comment found inside the body of a function?

   364 static OutputContext    inContext;           // are we inside the brief, details or xref part

   365 static bool             briefEndsAtDot;      // does the brief description stop at a dot?

   366 static QCString         formulaText;         // Running text of a formula

   367 static QCString         formulaEnv;          // environment name

   368 static int              formulaNewLines;     // amount of new lines in the formula

   369 static QCString        *pOutputString;       // pointer to string to which the output is appended.

   370 static QCString         outputXRef;          // temp argument of todo/test/../xrefitem commands

   371 static QCString         blockName;           // preformatted block name (e.g. verbatim, latexonly,...)

   372 static XRefKind         xrefKind;            // kind of cross-reference command

   373 static XRefKind         newXRefKind;         // 

   374 static GuardType        guardType;           // kind of guard for conditional section

   375 static bool             enabledSectionFound;

   376 static QCString         functionProto;       // function prototype

   377 static QStack<GuardedSection> guards;        // tracks nested conditional sections (if,ifnot,..)

   378 static Entry*		current      = 0 ;   // working entry

   379 //static Entry*		current_root = 0 ;   // parent of working entry

   380 

   381 

   382 //static Entry*		previous     = 0 ;   // TODO: remove need for this

   383 static bool             needNewEntry;

   384 

   385 static QCString         sectionLabel;

   386 static QCString		sectionTitle;

   387 static QCString         xrefItemKey;

   388 static QCString         newXRefItemKey;

   389 static QCString         xrefItemTitle;

   390 static QCString         xrefListTitle;

   391 static Protection	protection;

   392 

   393 static bool             xrefAppendFlag;

   394 static bool             inGroupParamFound;

   395 static int              braceCount;

   396 static bool             insidePre;

   397 static bool             parseMore;

   398 

   399 static int              g_commentCount;

   400 

   401 //-----------------------------------------------------------------------------

   402 

   403 static QStack<Grouping> g_autoGroupStack;

   404 static int              g_memberGroupId = DOX_NOGROUP;

   405 static QCString         g_memberGroupHeader;

   406 static QCString         g_memberGroupDocs;

   407 static QCString         g_memberGroupRelates;

   408 static QCString         g_compoundName;

   409 

   410 //-----------------------------------------------------------------------------

   411 

   412 static void initParser()

   413 {

   414   sectionLabel.resize(0);

   415   sectionTitle.resize(0);

   416   g_memberGroupHeader.resize(0);

   417 }

   418 

   419 //-----------------------------------------------------------------------------

   420 

   421 static QCString getDocSectionName(int s)

   422 {

   423   switch(s)

   424   {

   425     case Entry::CLASSDOC_SEC:       return "\\class";

   426     case Entry::STRUCTDOC_SEC:      return "\\struct";

   427     case Entry::UNIONDOC_SEC:       return "\\union";

   428     case Entry::EXCEPTIONDOC_SEC:   return "\\exception";

   429     case Entry::NAMESPACEDOC_SEC:   return "\\namespace";

   430     case Entry::PROTOCOLDOC_SEC:    return "\\protocol";

   431     case Entry::CATEGORYDOC_SEC:    return "\\category";

   432     case Entry::ENUMDOC_SEC:        return "\\enum";

   433     case Entry::PAGEDOC_SEC:        return "\\page";

   434     case Entry::MEMBERDOC_SEC:      return "\\fn";

   435     case Entry::OVERLOADDOC_SEC:    return "\\overload";

   436     case Entry::FILEDOC_SEC:        return "\\file";

   437     case Entry::DEFINEDOC_SEC:      return "\\def";

   438     case Entry::GROUPDOC_SEC:       return "\\defgroup";

   439     case Entry::MAINPAGEDOC_SEC:    return "\\mainpage";

   440     case Entry::PACKAGEDOC_SEC:     return "\\package";

   441     case Entry::DIRDOC_SEC:         return "\\dir";

   442     case Entry::EXAMPLE_SEC:        return "\\example";

   443     case Entry::MEMBERGRP_SEC:      return "\\name";

   444     default: return "";

   445   }

   446 }

   447 

   448 //-----------------------------------------------------------------------------

   449 

   450 static bool makeStructuralIndicator(Entry::Sections s)

   451 {

   452   if (!getDocSectionName(current->section).isEmpty())

   453   {

   454     return TRUE;

   455   }

   456   else

   457   {

   458     needNewEntry = TRUE;

   459     current->section = s;

   460     current->fileName = yyFileName;

   461     current->startLine = yyLineNr;

   462     return FALSE;

   463   }

   464 }

   465 

   466 static void lineCount()

   467 {

   468   for( const char* c = yytext ; *c ; ++c )

   469     yyLineNr += (*c == '\n') ;

   470 }

   471 

   472 

   473 static QCString stripQuotes(const char *s)

   474 {

   475   QCString name;

   476   if (s==0 || *s==0) return name;

   477   name=s;

   478   if (name.at(0)=='"' && name.at(name.length()-1)=='"')

   479   {

   480     name=name.mid(1,name.length()-2);

   481   }

   482   return name;

   483 }

   484 

   485 //-----------------------------------------------------------------

   486 

   487 static void addXRefItem(const char *listName,const char *itemTitle,

   488                         const char *listTitle,bool append)

   489 {

   490   Entry *docEntry = current; // inBody && previous ? previous : current;

   491   if (listName==0) return;

   492   //printf("addXRefItem(%s,%s,%s,%d)\n",listName,itemTitle,listTitle,append);

   493 

   494   ListItemInfo *lii=0;

   495   RefList *refList = Doxygen::xrefLists->find(listName);

   496   if (refList==0) // new list

   497   {

   498     refList = new RefList(listName,listTitle,itemTitle);

   499     Doxygen::xrefLists->insert(listName,refList);

   500     //printf("new list!\n");

   501   }

   502   if (docEntry->sli)

   503   {

   504     QListIterator<ListItemInfo> slii(*docEntry->sli);

   505     for (slii.toFirst();(lii=slii.current());++slii)

   506     {

   507       if (strcmp(lii->type,listName)==0) 

   508       {

   509         //printf("found %s lii->type=%s\n",listName,lii->type);

   510         break;

   511       }

   512     }

   513   }

   514   if (lii && append) // already found item of same type just before this one

   515   {

   516     //printf("listName=%s item id = %d existing\n",listName,lii->itemId);

   517     RefItem *item = refList->getRefItem(lii->itemId);

   518     ASSERT(item!=0);

   519     item->text += " <p>";

   520     item->text += outputXRef;

   521     //printf("%s: text +=%s\n",listName,item->text.data());

   522   }

   523   else // new item

   524   {

   525     int itemId  = refList->addRefItem();

   526     //printf("listName=%s item id = %d new current=%p\n",listName,itemId,current);

   527 

   528     // if we have already an item from the same list type (e.g. a second @todo)

   529     // in the same Entry (i.e. lii!=0) then we reuse its link anchor.

   530     char anchorLabel[1024];

   531     //sprintf(anchorLabel,"_%s%06d",listName,lii ? lii->itemId : itemId);

   532     sprintf(anchorLabel,"_%s%06d",listName,itemId);

   533     RefItem *item = refList->getRefItem(itemId);

   534     ASSERT(item!=0);

   535     item->text = outputXRef;

   536     item->listAnchor = anchorLabel;

   537     docEntry->addSpecialListItem(listName,itemId);

   538     QCString cmdString;

   539     cmdString.sprintf("\\xrefitem %s %d.",listName,itemId);

   540     if (inBody)

   541     {

   542       docEntry->inbodyDocs += cmdString;

   543     }

   544     else

   545     {

   546       docEntry->doc += cmdString;

   547     }

   548     SectionInfo *si=new SectionInfo(listName,anchorLabel,

   549 	                            sectionTitle,SectionInfo::Anchor);

   550     Doxygen::sectionDict.insert(anchorLabel,si);

   551     docEntry->anchors->append(si);

   552   }

   553   outputXRef.resize(0);

   554 }

   555 

   556 //-----------------------------------------------------------------------------

   557 

   558 // Adds a formula text to the list/dictionary of formulas if it was

   559 // not already added. Returns the label of the formula.

   560 static QCString addFormula()

   561 {

   562   QCString formLabel;

   563   QCString fText=formulaText.simplifyWhiteSpace();

   564   Formula *f=0;

   565   if ((f=Doxygen::formulaDict[fText])==0)

   566   {

   567     f = new Formula(fText);

   568     Doxygen::formulaList.append(f);

   569     Doxygen::formulaDict.insert(fText,f);

   570     formLabel.sprintf("\\form#%d",f->getId());

   571     Doxygen::formulaNameDict.insert(formLabel,f);

   572   }

   573   else

   574   {

   575     formLabel.sprintf("\\form#%d",f->getId());

   576   }

   577   int i;

   578   for (i=0;i<formulaNewLines;i++) formLabel+="\\_fakenl"; // add fake newlines to

   579                                                           // keep the warnings 

   580                                                           // correctly aligned.

   581   return formLabel;

   582 }

   583 

   584 //-----------------------------------------------------------------------------

   585 

   586 static void checkFormula();

   587 //-----------------------------------------------------------------------------

   588 

   589 static void addSection()

   590 {

   591   sectionTitle+=yytext;

   592   sectionTitle=sectionTitle.stripWhiteSpace();

   593   //printf("Adding new section file=%s label=%s title=%s\n",yyFileName,sectionLabel.data(),sectionTitle.data()); 

   594   SectionInfo *si = new SectionInfo(yyFileName,sectionLabel,sectionTitle,SectionInfo::Anchor);

   595   current->anchors->append(si);

   596   Doxygen::sectionDict.insert(yytext,si);

   597 }

   598 

   599 //-----------------------------------------------------------------------------

   600 

   601 // strip trailing whitespace (excluding newlines) from string s

   602 static void stripTrailingWhiteSpace(QCString &s)

   603 {

   604   uint len = s.length();

   605   int i = (int)len-1;

   606   char c;

   607   while (i>=0 && ((c = s.at(i))==' ' || c=='\t' || c=='\r')) i--;

   608   if (i!=(int)len-1) 

   609   {

   610     s.resize(i+2); // string upto and including char at pos i and \0 terminator

   611   }

   612 }

   613 

   614 // selects the output to write to

   615 static inline void setOutput(OutputContext ctx)

   616 {

   617   bool xrefAppendToPrev = xrefAppendFlag;

   618   // determine append flag for the next item (i.e. the end of this item)

   619   xrefAppendFlag = !inBody &&

   620                    inContext==OutputXRef && ctx==OutputXRef && // two consecutive xref items

   621                    newXRefKind==xrefKind &&                    // of the same kind

   622                    (xrefKind!=XRef_Item || 

   623 		    newXRefItemKey==xrefItemKey);              // with the same key if \xrefitem

   624   //printf("%d && %d && %d && (%d || %d)\n",

   625   //                 inContext==OutputXRef,

   626   //                 ctx==OutputXRef,

   627   //                 newXRefKind==xrefKind,

   628   //                 xrefKind!=XRef_Item,

   629   //	  	     newXRefItemKey==xrefItemKey);

   630       

   631   //printf("refKind=%d newXRefKind=%d xrefAppendToPrev=%d xrefAppendFlag=%d\n",

   632   //   	  xrefKind,newXRefKind,xrefAppendToPrev,xrefAppendFlag);

   633 

   634   //printf("setOutput(inContext=%d ctx=%d)\n",inContext,ctx);

   635   if (inContext==OutputXRef) // end of XRef section => add the item 

   636   {

   637     // See if we can append this new xref item to the previous one.

   638     // We know this at the start of the next item of the same

   639     // type and need to remember this until the end of that item.

   640     switch(xrefKind)

   641     {

   642       case XRef_Todo:

   643 	addXRefItem("todo",

   644 	            theTranslator->trTodo(),

   645 	            theTranslator->trTodoList(),

   646 		    xrefAppendToPrev

   647 		   );

   648 	break;

   649       case XRef_Test:

   650 	addXRefItem("test",

   651 	            theTranslator->trTest(),

   652 		    theTranslator->trTestList(),

   653 		    xrefAppendToPrev

   654 		   );

   655 	break;

   656       case XRef_Bug:

   657 	addXRefItem("bug",

   658 	            theTranslator->trBug(),

   659 		    theTranslator->trBugList(),

   660 		    xrefAppendToPrev

   661 		   );

   662 	break;

   663       case XRef_Deprecated:

   664 	addXRefItem("deprecated",

   665 	            theTranslator->trDeprecated(),

   666 		    theTranslator->trDeprecatedList(),

   667 		    xrefAppendToPrev

   668 		   );

   669 	break;

   670       case XRef_Item:  // user defined list

   671 	addXRefItem(xrefItemKey,

   672 	            xrefItemTitle,

   673 		    xrefListTitle,

   674 		    xrefAppendToPrev

   675 		   );

   676 	break;

   677       case XRef_None:

   678 	ASSERT(0);

   679 	break;

   680     }

   681   }

   682   xrefItemKey = newXRefItemKey;

   683 

   684   int oldContext = inContext;

   685   inContext = ctx;

   686   if (inContext!=OutputXRef && inBody) inContext=OutputInbody;

   687   switch(inContext)

   688   {

   689     case OutputDoc:

   690       if (oldContext!=inContext)

   691       {

   692         stripTrailingWhiteSpace(current->doc);

   693         if (current->docFile.isEmpty())

   694         {

   695           current->docFile = yyFileName;

   696           current->docLine = yyLineNr;

   697         }

   698       }

   699       pOutputString = &current->doc;

   700       break;

   701     case OutputBrief:

   702       if (oldContext!=inContext)

   703       {

   704 	if (current->briefFile.isEmpty())

   705 	{

   706 	  current->briefFile = yyFileName;

   707 	  current->briefLine = yyLineNr;

   708 	}

   709       }

   710       if (current->brief.stripWhiteSpace().isEmpty()) // we only want one brief

   711 	                                              // description even if multiple

   712 	                                              // are given...

   713       {

   714         pOutputString = &current->brief;

   715       }

   716       else

   717       {

   718         pOutputString = &current->doc;

   719       }

   720       break;

   721     case OutputXRef:

   722       pOutputString = &outputXRef;

   723       // first item found, so can't append to previous

   724       //xrefAppendFlag = FALSE;

   725       break;

   726     case OutputInbody:

   727       pOutputString = &current->inbodyDocs;

   728       break;

   729   }

   730 }

   731 

   732 // add a string to the output

   733 static inline void addOutput(const char *s)

   734 {

   735   *pOutputString+=s;

   736 }

   737 

   738 // add a character to the output

   739 static inline void addOutput(char c)

   740 {

   741   *pOutputString+=c;

   742 }

   743 

   744 static void endBrief(bool addToOutput=TRUE)

   745 {

   746   if (!current->brief.stripWhiteSpace().isEmpty())

   747   { // only go to the detailed description if we have

   748     // found some brief description and not just whitespace

   749     briefEndsAtDot=FALSE;

   750     setOutput(OutputDoc);

   751     if (addToOutput) addOutput(yytext);

   752   }

   753 }

   754 

   755 /* ----------------------------------------------------------------- */

   756 #undef	YY_INPUT

   757 #define	YY_INPUT(buf,result,max_size) result=yyread(buf,max_size);

   758 

   759 static int prevPosition=0;

   760 

   761 static int yyread(char *buf,int max_size)

   762 {

   763     prevPosition=inputPosition;

   764     int c=0;

   765     while( c < max_size && inputString[inputPosition] )

   766     {

   767 	*buf = inputString[inputPosition++] ;

   768 	//printf("%d (%c)\n",*buf,*buf);

   769 	c++; buf++;

   770     }

   771     return c;

   772 }

   773 

   774 %}

   775 

   776        /* start command character */

   777 CMD	  ("\\"|"@")

   778 DCMD1     ("arg"|"attention"|"author"|"code")

   779 DCMD2     ("date"|"dot"|"msc"|"dotfile"|"example")

   780 DCMD3     ("htmlinclude"|"htmlonly"|"image"|"include")

   781 DCMD4     ("includelineno"|"internal"|"invariant")

   782 DCMD5     ("latexonly"|"li"|"line"|"manonly"|"name") 

   783 DCMD6     ("note"|"par"|"paragraph"|"param"|"post")

   784 DCMD7     ("pre"|"remarks"|(("relate"[sd])("also")?))

   785 DCMD8     ("remarks"|("return"[s]?)|"retval"|"sa"|"section")

   786 DCMD9     ("see"|"since"|"subsection"|"subsubsection")

   787 DCMD10    ("throw"|"until"|"verbatim")

   788 DCMD11    ("verbinclude"|"version"|"warning")

   789 DETAILEDCMD {CMD}({DCMD1}|{DCMD2}|{DCMD3}|{DCMD4}|{DCMD5}|{DCMD6}|{DCMD7}|{DCMD8}|{DCMD9}|{DCMD10}|{DCMD11})

   790 XREFCMD   {CMD}("bug"|"deprecated"|"test"|"todo"|"xrefitem")  

   791 PRE       [pP][rR][eE]

   792 TABLE	  [tT][aA][bB][lL][eE]

   793 P	  [pP]

   794 UL        [uU][lL]

   795 OL	  [oO][lL]

   796 DL	  [dD][lL]

   797 IMG       [iI][mM][gG]

   798 HR        [hH][rR]

   799 DETAILEDHTML {PRE}|{UL}|{TABLE}|{OL}|{DL}|{P}|[Hh][1-6]|{IMG}|{HR}

   800 BN        [ \t\n\r]

   801 BL        [ \t\r]*"\n" 

   802 B         [ \t]

   803 BS        ^(({B}*"//")?)(({B}*"*"+)?){B}*

   804 ATTR      ({B}+[^>\n]*)?

   805 DOCNL     "\n"|"\\_linebr"

   806 LC        "\\"{B}*"\n"

   807 NW	  [^a-z_A-Z0-9]

   808 FILESCHAR [a-z_A-Z0-9\x80-\xFF\\:\\\/\-\+]

   809 FILEECHAR [a-z_A-Z0-9\x80-\xFF\-\+]

   810 FILE      ({FILESCHAR}*{FILEECHAR}+("."{FILESCHAR}*{FILEECHAR}+)*)|("\""[^\n\"]*"\"")

   811 ID        "$"?[a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF]*

   812 LABELID   [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*

   813 SCOPEID   {ID}({ID}*{BN}*"::"{BN}*)*({ID}?)

   814 SCOPENAME "$"?(({ID}?{BN}*("::"|"."){BN}*)*)((~{BN}*)?{ID})

   815 MAILADR   [a-z_A-Z0-9.+\-]+"@"[a-z_A-Z0-9\-]+("."[a-z_A-Z0-9\-]+)+[a-z_A-Z0-9\-]+ 

   816 RCSTAG    "$"{ID}":"[^\n$]+"$"

   817 

   818 %option noyywrap

   819 

   820   /* comment parsing states. */

   821 %x      Comment

   822 %x      PageDocArg1

   823 %x      PageDocArg2

   824 %x      RelatesParam1

   825 %x      ClassDocArg1

   826 %x      ClassDocArg2

   827 %x      ClassDocArg3

   828 %x      CategoryDocArg1

   829 %x      XRefItemParam1

   830 %x      XRefItemParam2

   831 %x      XRefItemParam3

   832 %x      FileDocArg1

   833 %x	EnumDocArg1

   834 %x	NameSpaceDocArg1

   835 %x	PackageDocArg1

   836 %x	GroupDocArg1

   837 %x	GroupDocArg2

   838 %x	SectionLabel

   839 %x	SectionTitle

   840 %x	SubpageLabel

   841 %x	SubpageTitle

   842 %x	FormatBlock

   843 %x	LineParam

   844 %x	GuardParam

   845 %x	SkipGuardedSection

   846 %x	SkipInternal

   847 %x      NameParam

   848 %x	InGroupParam

   849 %x	FnParam

   850 %x	OverloadParam

   851 %x	InheritParam

   852 %x	ExtendsParam

   853 %x      ReadFormulaShort

   854 %x	ReadFormulaLong

   855 %x	AnchorLabel

   856 %x      HtmlComment

   857 %x      SkipLang

   858 

   859 %%

   860 

   861   /* What can happen in while parsing a comment block:

   862    *   commands (e.g. @page, or \page)

   863    *   escaped commands (e.g. @@page or \\page).

   864    *   formulas (e.g. \f$ \f[ \f{..)

   865    *   directories (e.g. \doxygen\src\)

   866    *   autolist end. (e.g. a dot on an otherwise empty line)

   867    *   newlines.

   868    *   end of brief description due to blank line.

   869    *   end of brief description due to some command (@command, or <command>).

   870    *   words and whitespace and other characters (#,?!, etc).

   871    *   grouping commands (e.g. @{ and @})

   872    *   language switch (e.g. \~english or \~).

   873    *   mail adress (e.g. dimitri@stack.nl).

   874    *   quoted text, such as "foo@bar"

   875    *   XML commands, <summary></summary><remarks></remarks>

   876    */

   877 

   878 <Comment>{CMD}{CMD}[a-z_A-Z]+{B}*	{ // escaped command

   879   					  addOutput(yytext);

   880   					}

   881 <Comment>{CMD}{CMD}"~"[a-z_A-Z]*	{ // escaped command

   882   					  addOutput(yytext);

   883   					}

   884 <Comment>{MAILADR}			{ // mail adress

   885   					  addOutput(yytext);

   886   					}

   887 <Comment>"\""[^"\n]*"\""		{ // quoted text

   888                                           addOutput(yytext);

   889   					}

   890 <Comment>("\\"[a-z_A-Z]+)+"\\"		{ // directory (or chain of commands!)

   891   					  addOutput(yytext);

   892   					}

   893 <Comment>{XREFCMD}/[^a-z_A-Z]*		{ // xref command 

   894 					  if (inContext!=OutputXRef) 

   895 					  {

   896 					    briefEndsAtDot=FALSE;

   897 					    setOutput(OutputDoc);

   898 					  }

   899 					  // continue with the same input

   900                                           REJECT;

   901 					}

   902    /*

   903 <Comment>{DETAILEDCMD}/[^a-z_A-Z]*	{ // command that can end a brief description

   904 				          briefEndsAtDot=FALSE;

   905 				          setOutput(OutputDoc);

   906 					  // continue with the same input

   907                                           REJECT;

   908 					}

   909    */

   910 <Comment>"<"{DETAILEDHTML}{ATTR}">"	{ // HTML command that ends a brief description

   911 					  setOutput(OutputDoc);

   912 					  // continue with the same input

   913                                           REJECT;

   914 					}

   915 <Comment>"<summary>"			{ // start of a .NET XML style brief description

   916 					  setOutput(OutputBrief);

   917   					}

   918 <Comment>"<remarks>"|"</summary>"	{ // start of a .NET XML style detailed description

   919 					  setOutput(OutputDoc);

   920   					}

   921 <Comment>"</remarks>"			{ // end of a brief or detailed description

   922   					}

   923 <Comment>{RCSTAG}			{ // RCS tag which end a brief description

   924   					  setOutput(OutputDoc);

   925 					  REJECT;

   926   					}

   927 <Comment>"<!--"				{ 

   928   					  BEGIN(HtmlComment);

   929 					}

   930 <Comment>{CMD}[a-z_A-Z]+{B}*		{ // potentially interesting command

   931   					  QCString cmdName = QCString(&yytext[1]).stripWhiteSpace();

   932 					  DocCmdMapper::Cmd *cmdPtr = DocCmdMapper::map(cmdName);

   933 					  if (cmdPtr) // special action is required

   934 					  {

   935 					    if (cmdPtr->endsBrief)

   936 					    { 

   937 					      briefEndsAtDot=FALSE;

   938 					      // this command forces the end of brief description

   939 					      setOutput(OutputDoc);

   940 					    }

   941 					    if (cmdPtr->func && cmdPtr->func(cmdName))

   942 					    {

   943 					      // implicit split of the comment block into two

   944 					      // entries. Restart the next block at the start

   945 					      // of this command.

   946 					      parseMore=TRUE;

   947 

   948 					      // yuk, this is probably not very portable across lex implementations, 

   949 					      // but we need to know the position in the input buffer where this 

   950 					      // rule matched.

   951 					      // for flex 2.5.33+ we should use YY_CURRENT_BUFFER_LVALUE

   952 #if YY_FLEX_MINOR_VERSION>=5 && YY_FLEX_SUBMINOR_VERSION>=33

   953 					      inputPosition=prevPosition + yy_bp - YY_CURRENT_BUFFER_LVALUE->yy_ch_buf;

   954 #else

   955 					      inputPosition=prevPosition + yy_bp - yy_current_buffer->yy_ch_buf;

   956 #endif

   957 					      yyterminate();

   958 					    }

   959 					    else if (cmdPtr->func==0)

   960 					    {

   961 					      // command without handler, to be processed

   962 					      // later by parsedoc.cpp

   963 					      addOutput(yytext);

   964 					    }

   965 					  }

   966 					  else // command not relevant

   967 					  {

   968 					    addOutput(yytext);

   969 					  }

   970   					}

   971 <Comment>("\\\\"|"@@")"f"[$\[{]		{ // escaped formula command

   972   					  addOutput(yytext);

   973   					}

   974 <Comment>{CMD}"~"[a-z_A-Z]*		{ // language switch command

   975                                           QCString langId = &yytext[2];

   976 			       	          if (!langId.isEmpty() &&

   977 					      stricmp(Config_getEnum("OUTPUT_LANGUAGE"),langId)!=0)

   978 				          { // enable language specific section

   979 				            BEGIN(SkipLang);

   980 				          }

   981   					}

   982 <Comment>{CMD}"f{"[^}\n]+"}"("{"?)      { // start of a formula with custom environment

   983 					  formulaText="\\begin";

   984 					  formulaEnv=&yytext[2];

   985 					  if (formulaEnv.at(formulaEnv.length()-1)=='{')

   986 					  {

   987 					    // remove trailing open brace

   988 					    formulaEnv=formulaEnv.left(formulaEnv.length()-1);

   989 					  }

   990 					  formulaText+=formulaEnv;

   991 					  formulaNewLines=0;

   992 					  BEGIN(ReadFormulaLong);

   993   					}

   994 <Comment>{CMD}"f$"			{ // start of a inline formula

   995 					  formulaText="$";

   996 					  formulaNewLines=0;

   997 					  BEGIN(ReadFormulaShort);

   998   					}

   999 <Comment>{CMD}"f["			{ // start of a block formula

  1000 					  formulaText="\\[";

  1001 					  formulaNewLines=0;

  1002 					  BEGIN(ReadFormulaLong);

  1003   					}

  1004 <Comment>{CMD}"{"                       { // begin of a group

  1005                                           //langParser->handleGroupStartCommand(g_memberGroupHeader);

  1006                                           openGroup(current,yyFileName,yyLineNr);

  1007                                         }

  1008 <Comment>{CMD}"}"                       { // end of a group

  1009                                           //langParser->handleGroupEndCommand();

  1010                                           closeGroup(current,yyFileName,yyLineNr);

  1011                                           g_memberGroupHeader.resize(0);

  1012                                         }

  1013 <Comment>{CMD}[$@\\&~<>#%]		{ // escaped character

  1014   					  addOutput(yytext);

  1015   					}

  1016 <Comment>[a-z_A-Z]+			{ // normal word

  1017 					  addOutput(yytext);

  1018   					}

  1019 <Comment>^{B}*"."{B}*/\n                { // explicit end autolist: e.g "  ."

  1020   				          addOutput(yytext); 

  1021 					}

  1022 <Comment>("."+)[a-z_A-Z0-9]		{ // . at start or in the middle of a word, or ellipsis

  1023   					  addOutput(yytext);

  1024   					}

  1025 <Comment>".\\"[ \t]			{ // . with escaped space.

  1026   					  addOutput(yytext[0]);

  1027   					  addOutput(yytext[2]);

  1028   					}

  1029 <Comment>".,"				{ // . with comma such as "e.g.," 

  1030   					  addOutput(yytext);

  1031   					}

  1032 <Comment>(\n|\\_linebr)({B}*(\n|\\_linebr))+	{ // at least one blank line (or blank line command)

  1033   					  if (inContext!=OutputBrief)

  1034 					  {

  1035   					    addOutput("\n\n");

  1036 					    setOutput(OutputDoc);

  1037 					  }

  1038 					  else 

  1039 					  { // only go to the detailed description if we have

  1040 					    // found some brief description and not just whitespace

  1041 					    endBrief(FALSE);

  1042 					  }

  1043   					  lineCount();

  1044   					}

  1045 <Comment>"."				{ // potential end of a JavaDoc style comment

  1046   					  addOutput(*yytext);

  1047   					  if (briefEndsAtDot)

  1048 					  {

  1049 					    setOutput(OutputDoc);

  1050 					    briefEndsAtDot=FALSE;

  1051 					  }

  1052   					}

  1053 <Comment>\n				{ // newline

  1054   					  addOutput(*yytext);

  1055   					  yyLineNr++;

  1056   					}

  1057 <Comment>.				{ // catch-all for anything else

  1058   					  addOutput(*yytext);

  1059   					}

  1060 

  1061 

  1062  /* --------------   Rules for handling HTML comments ----------- */

  1063 

  1064 <HtmlComment>"--"[!]?">"{B}*		{ BEGIN( Comment ); }

  1065 <HtmlComment>{DOCNL}			{ 

  1066   					  if (*yytext=='\n') yyLineNr++;

  1067   					}

  1068 <HtmlComment>[^\\\n\-]+			{ // ignore unimportant characters

  1069   					}

  1070 <HtmlComment>.				{ // ignore every else

  1071   					}

  1072 

  1073  /* --------------   Rules for handling formulas ---------------- */

  1074  

  1075 <ReadFormulaShort>{CMD}"f$"		{ // end of inline formula

  1076   					  formulaText+="$";

  1077 					  addOutput(addFormula());

  1078 					  BEGIN(Comment);

  1079   					}

  1080 <ReadFormulaLong>{CMD}"f]"		{ // end of block formula

  1081 					  formulaText+="\\]";

  1082 					  addOutput(addFormula());

  1083 					  BEGIN(Comment);

  1084   					}

  1085 <ReadFormulaLong>{CMD}"f}"		{ // end of custom env formula

  1086 					  formulaText+="\\end";

  1087 					  formulaText+=formulaEnv;

  1088 					  addOutput(addFormula());

  1089 					  BEGIN(Comment);

  1090   					}

  1091 <ReadFormulaLong,ReadFormulaShort>[^\\@\n]+ { // any non-special character

  1092                                           formulaText+=yytext; 

  1093  					} 

  1094 <ReadFormulaLong,ReadFormulaShort>\n	{ // new line

  1095                                           formulaNewLines++;

  1096                                           formulaText+=*yytext; 

  1097 					  yyLineNr++; 

  1098 					}

  1099 <ReadFormulaLong,ReadFormulaShort>.     { // any othe character

  1100                                           formulaText+=*yytext; 

  1101 					}

  1102 

  1103   /* ------------ handle argument of enum command --------------- */

  1104 

  1105 <EnumDocArg1>{SCOPEID}			{ // handle argument

  1106   					  current->name = yytext;

  1107 					  BEGIN( Comment );

  1108   					}

  1109 <EnumDocArg1>{LC}			{ // line continuation

  1110   					  yyLineNr++;

  1111 					  addOutput('\n');

  1112                                         }

  1113 <EnumDocArg1>{DOCNL}			{ // missing argument

  1114   					  warn(yyFileName,yyLineNr,

  1115                                                "Warning: missing argument after \\enum."

  1116                                               );

  1117 					  addOutput('\n');

  1118   					  if (*yytext=='\n') yyLineNr++;

  1119 					  BEGIN( Comment );

  1120   					}

  1121 <EnumDocArg1>.				{ // ignore other stuff

  1122   					}

  1123 

  1124   /* ------------ handle argument of namespace command --------------- */

  1125 

  1126 <NameSpaceDocArg1>{SCOPENAME}		{ // handle argument

  1127   					  current->name = substitute(yytext,".","::");

  1128 					  BEGIN( Comment );

  1129   					}

  1130 <NameSpaceDocArg1>{LC}			{ // line continuation

  1131                                           yyLineNr++; 

  1132 					  addOutput('\n');

  1133                                         }

  1134 <NameSpaceDocArg1>{DOCNL}		{ // missing argument