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 		  //printf("Setting docFile to %s\n", yyFileName.data());

   696           current->docFile = yyFileName;

   697           current->docLine = yyLineNr;

   698         }

   699       }

   700       pOutputString = &current->doc;

   701       break;

   702     case OutputBrief:

   703       if (oldContext!=inContext)

   704       {

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

   706 	{

   707 	  current->briefFile = yyFileName;

   708 	  current->briefLine = yyLineNr;

   709 	}

   710       }

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

   712 	                                              // description even if multiple

   713 	                                              // are given...

   714       {

   715         pOutputString = &current->brief;

   716       }

   717       else

   718       {

   719         pOutputString = &current->doc;

   720       }

   721       break;

   722     case OutputXRef:

   723       pOutputString = &outputXRef;

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

   725       //xrefAppendFlag = FALSE;

   726       break;

   727     case OutputInbody:

   728       pOutputString = &current->inbodyDocs;

   729       break;

   730   }

   731 }

   732 

   733 // add a string to the output

   734 static inline void addOutput(const char *s)

   735 {

   736   *pOutputString+=s;

   737 }

   738 

   739 // add a character to the output

   740 static inline void addOutput(char c)

   741 {

   742   *pOutputString+=c;

   743 }

   744 

   745 static void endBrief(bool addToOutput=TRUE)

   746 {

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

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

   749     // found some brief description and not just whitespace

   750     briefEndsAtDot=FALSE;

   751     setOutput(OutputDoc);

   752     if (addToOutput) addOutput(yytext);

   753   }

   754 }

   755 

   756 /* ----------------------------------------------------------------- */

   757 #undef	YY_INPUT

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

   759 

   760 static int prevPosition=0;

   761 

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

   763 {

   764     prevPosition=inputPosition;

   765     int c=0;

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

   767     {

   768 	*buf = inputString[inputPosition++] ;

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

   770 	c++; buf++;

   771     }

   772     return c;

   773 }

   774 

   775 %}

   776 

   777        /* start command character */

   778 CMD	  ("\\"|"@")

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

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

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

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

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

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

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

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

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

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

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

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

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

   792 PRE       [pP][rR][eE]

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

   794 P	  [pP]

   795 UL        [uU][lL]

   796 OL	  [oO][lL]

   797 DL	  [dD][lL]

   798 IMG       [iI][mM][gG]

   799 HR        [hH][rR]

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

   801 BN        [ \t\n\r]

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

   803 B         [ \t]

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

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

   806 DOCNL     "\n"|"\\_linebr"

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

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

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

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

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

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

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

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

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

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

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

   818 

   819 %option noyywrap

   820 

   821   /* comment parsing states. */

   822 %x      Comment

   823 %x      PageDocArg1

   824 %x      PageDocArg2

   825 %x      RelatesParam1

   826 %x      ClassDocArg1

   827 %x      ClassDocArg2

   828 %x      ClassDocArg3

   829 %x      CategoryDocArg1

   830 %x      XRefItemParam1

   831 %x      XRefItemParam2

   832 %x      XRefItemParam3

   833 %x      FileDocArg1

   834 %x	EnumDocArg1

   835 %x	NameSpaceDocArg1

   836 %x	PackageDocArg1

   837 %x	GroupDocArg1

   838 %x	GroupDocArg2

   839 %x	SectionLabel

   840 %x	SectionTitle

   841 %x	SubpageLabel

   842 %x	SubpageTitle

   843 %x	FormatBlock

   844 %x	LineParam

   845 %x	GuardParam

   846 %x	SkipGuardedSection

   847 %x	SkipInternal

   848 %x      NameParam

   849 %x	InGroupParam

   850 %x	FnParam

   851 %x	OverloadParam

   852 %x	InheritParam

   853 %x	ExtendsParam

   854 %x      ReadFormulaShort

   855 %x	ReadFormulaLong

   856 %x	AnchorLabel

   857 %x      HtmlComment

   858 %x      SkipLang

   859 

   860 %%

   861 

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

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

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

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

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

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

   868    *   newlines.

   869    *   end of brief description due to blank line.

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

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

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

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

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

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

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

   877    */

   878 

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

   880   					  addOutput(yytext);

   881   					}

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

   883   					  addOutput(yytext);

   884   					}

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

   886   					  addOutput(yytext);

   887   					}

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

   889                                           addOutput(yytext);

   890   					}

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

   892   					  addOutput(yytext);

   893   					}

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

   895 					  if (inContext!=OutputXRef) 

   896 					  {

   897 					    briefEndsAtDot=FALSE;

   898 					    setOutput(OutputDoc);

   899 					  }

   900 					  // continue with the same input

   901                                           REJECT;

   902 					}

   903    /*

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

   905 				          briefEndsAtDot=FALSE;

   906 				          setOutput(OutputDoc);

   907 					  // continue with the same input

   908                                           REJECT;

   909 					}

   910    */

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

   912 					  setOutput(OutputDoc);

   913 					  // continue with the same input

   914                                           REJECT;

   915 					}

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

   917 					  setOutput(OutputBrief);

   918   					}

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

   920 					  setOutput(OutputDoc);

   921   					}

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

   923   					}

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

   925   					  setOutput(OutputDoc);

   926 					  REJECT;

   927   					}

   928 <Comment>"<!--"				{ 

   929   					  BEGIN(HtmlComment);

   930 					}

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

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

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

   934 					  if (cmdPtr) // special action is required

   935 					  {

   936 					    if (cmdPtr->endsBrief)

   937 					    { 

   938 					      briefEndsAtDot=FALSE;

   939 					      // this command forces the end of brief description

   940 					      setOutput(OutputDoc);

   941 					    }

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

   943 					    {

   944 					      // implicit split of the comment block into two

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

   946 					      // of this command.

   947 					      parseMore=TRUE;

   948 

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

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

   951 					      // rule matched.

   952 					      // for flex 2.5.33+ we should use YY_CURRENT_BUFFER_LVALUE

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

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

   955 #else

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

   957 #endif

   958 					      yyterminate();

   959 					    }

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

   961 					    {

   962 					      // command without handler, to be processed

   963 					      // later by parsedoc.cpp

   964 					      addOutput(yytext);

   965 					    }

   966 					  }

   967 					  else // command not relevant

   968 					  {

   969 					    addOutput(yytext);

   970 					  }

   971   					}

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

   973   					  addOutput(yytext);

   974   					}

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

   976                                           QCString langId = &yytext[2];

   977 			       	          if (!langId.isEmpty() &&

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

   979 				          { // enable language specific section

   980 				            BEGIN(SkipLang);

   981 				          }

   982   					}

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

   984 					  formulaText="\\begin";

   985 					  formulaEnv=&yytext[2];

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

   987 					  {

   988 					    // remove trailing open brace

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

   990 					  }

   991 					  formulaText+=formulaEnv;

   992 					  formulaNewLines=0;

   993 					  BEGIN(ReadFormulaLong);

   994   					}

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

   996 					  formulaText="$";

   997 					  formulaNewLines=0;

   998 					  BEGIN(ReadFormulaShort);

   999   					}

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

  1001 					  formulaText="\\[";

  1002 					  formulaNewLines=0;

  1003 					  BEGIN(ReadFormulaLong);

  1004   					}

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

  1006                                           //langParser->handleGroupStartCommand(g_memberGroupHeader);

  1007                                           openGroup(current,yyFileName,yyLineNr);

  1008                                         }

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

  1010                                           //langParser->handleGroupEndCommand();

  1011                                           closeGroup(current,yyFileName,yyLineNr);

  1012                                           g_memberGroupHeader.resize(0);

  1013                                         }

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

  1015   					  addOutput(yytext);

  1016   					}

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

  1018 					  addOutput(yytext);

  1019   					}

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

  1021   				          addOutput(yytext); 

  1022 					}

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

  1024   					  addOutput(yytext);

  1025   					}

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

  1027   					  addOutput(yytext[0]);

  1028   					  addOutput(yytext[2]);

  1029   					}

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

  1031   					  addOutput(yytext);

  1032   					}

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

  1034   					  if (inContext!=OutputBrief)

  1035 					  {

  1036   					    addOutput("\n\n");

  1037 					    setOutput(OutputDoc);

  1038 					  }

  1039 					  else 

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

  1041 					    // found some brief description and not just whitespace

  1042 					    endBrief(FALSE);

  1043 					  }

  1044   					  lineCount();

  1045   					}

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

  1047   					  addOutput(*yytext);

  1048   					  if (briefEndsAtDot)

  1049 					  {

  1050 					    setOutput(OutputDoc);

  1051 					    briefEndsAtDot=FALSE;

  1052 					  }

  1053   					}

  1054 <Comment>\n				{ // newline

  1055   					  addOutput(*yytext);

  1056   					  yyLineNr++;

  1057   					}

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

  1059   					  addOutput(*yytext);

  1060   					}

  1061 

  1062 

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

  1064 

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

  1066 <HtmlComment>{DOCNL}			{ 

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

  1068   					}

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

  1070   					}

  1071 <HtmlComment>.				{ // ignore every else

  1072   					}

  1073 

  1074  /* --------------   Rules for handling formulas ---------------- */

  1075  

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

  1077   					  formulaText+="$";

  1078 					  addOutput(addFormula());

  1079 					  BEGIN(Comment);

  1080   					}

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

  1082 					  formulaText+="\\]";

  1083 					  addOutput(addFormula());

  1084 					  BEGIN(Comment);

  1085   					}

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

  1087 					  formulaText+="\\end";

  1088 					  formulaText+=formulaEnv;

  1089 					  addOutput(addFormula());

  1090 					  BEGIN(Comment);

  1091   					}

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

  1093                                           formulaText+=yytext; 

  1094  					} 

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

  1096                                           formulaNewLines++;

  1097                                           formulaText+=*yytext; 

  1098 					  yyLineNr++; 

  1099 					}

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

  1101                                           formulaText+=*yytext; 

  1102 					}

  1103 

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

  1105 

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

  1107   					  current->name = yytext;

  1108 					  BEGIN( Comment );

  1109   					}

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

  1111   					  yyLineNr++;

  1112 					  addOutput('\n');

  1113                                         }

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

  1115   					  warn(yyFileName,yyLineNr,

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

  1117                                               );

  1118 					  addOutput('\n');

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

  1120 					  BEGIN( Comment );

  1121   					}

  1122 <EnumDocArg1>.				{ // ignore other stuff

  1123   					}

  1124 

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

  1126 

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

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

  1129 					  BEGIN( Comment );

  1130   					}

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

  1132                                           yyLineNr++; 

  1133 					  addOutput('\n');

  1134                                         }