Home | History | Annotate | Download | only in AST
      1 //===--- CommentLexer.h - Lexer for structured comments ---------*- C++ -*-===//
      2 //
      3 //                     The LLVM Compiler Infrastructure
      4 //
      5 // This file is distributed under the University of Illinois Open Source
      6 // License. See LICENSE.TXT for details.
      7 //
      8 //===----------------------------------------------------------------------===//
      9 //
     10 //  This file defines lexer for structured comments and supporting token class.
     11 //
     12 //===----------------------------------------------------------------------===//
     13 
     14 #ifndef LLVM_CLANG_AST_COMMENT_LEXER_H
     15 #define LLVM_CLANG_AST_COMMENT_LEXER_H
     16 
     17 #include "clang/Basic/Diagnostic.h"
     18 #include "clang/Basic/SourceManager.h"
     19 #include "llvm/ADT/SmallString.h"
     20 #include "llvm/ADT/SmallVector.h"
     21 #include "llvm/ADT/StringRef.h"
     22 #include "llvm/Support/Allocator.h"
     23 #include "llvm/Support/raw_ostream.h"
     24 
     25 namespace clang {
     26 namespace comments {
     27 
     28 class Lexer;
     29 class TextTokenRetokenizer;
     30 struct CommandInfo;
     31 class CommandTraits;
     32 
     33 namespace tok {
     34 enum TokenKind {
     35   eof,
     36   newline,
     37   text,
     38   unknown_command,   // Command that does not have an ID.
     39   backslash_command, // Command with an ID, that used backslash marker.
     40   at_command,        // Command with an ID, that used 'at' marker.
     41   verbatim_block_begin,
     42   verbatim_block_line,
     43   verbatim_block_end,
     44   verbatim_line_name,
     45   verbatim_line_text,
     46   html_start_tag,     // <tag
     47   html_ident,         // attr
     48   html_equals,        // =
     49   html_quoted_string, // "blah\"blah" or 'blah\'blah'
     50   html_greater,       // >
     51   html_slash_greater, // />
     52   html_end_tag        // </tag
     53 };
     54 } // end namespace tok
     55 
     56 /// \brief Comment token.
     57 class Token {
     58   friend class Lexer;
     59   friend class TextTokenRetokenizer;
     60 
     61   /// The location of the token.
     62   SourceLocation Loc;
     63 
     64   /// The actual kind of the token.
     65   tok::TokenKind Kind;
     66 
     67   /// Length of the token spelling in comment.  Can be 0 for synthenized
     68   /// tokens.
     69   unsigned Length;
     70 
     71   /// Contains text value associated with a token.
     72   const char *TextPtr;
     73 
     74   /// Integer value associated with a token.
     75   ///
     76   /// If the token is a konwn command, contains command ID and TextPtr is
     77   /// unused (command spelling can be found with CommandTraits).  Otherwise,
     78   /// contains the length of the string that starts at TextPtr.
     79   unsigned IntVal;
     80 
     81 public:
     82   SourceLocation getLocation() const LLVM_READONLY { return Loc; }
     83   void setLocation(SourceLocation SL) { Loc = SL; }
     84 
     85   SourceLocation getEndLocation() const LLVM_READONLY {
     86     if (Length == 0 || Length == 1)
     87       return Loc;
     88     return Loc.getLocWithOffset(Length - 1);
     89   }
     90 
     91   tok::TokenKind getKind() const LLVM_READONLY { return Kind; }
     92   void setKind(tok::TokenKind K) { Kind = K; }
     93 
     94   bool is(tok::TokenKind K) const LLVM_READONLY { return Kind == K; }
     95   bool isNot(tok::TokenKind K) const LLVM_READONLY { return Kind != K; }
     96 
     97   unsigned getLength() const LLVM_READONLY { return Length; }
     98   void setLength(unsigned L) { Length = L; }
     99 
    100   StringRef getText() const LLVM_READONLY {
    101     assert(is(tok::text));
    102     return StringRef(TextPtr, IntVal);
    103   }
    104 
    105   void setText(StringRef Text) {
    106     assert(is(tok::text));
    107     TextPtr = Text.data();
    108     IntVal = Text.size();
    109   }
    110 
    111   StringRef getUnknownCommandName() const LLVM_READONLY {
    112     assert(is(tok::unknown_command));
    113     return StringRef(TextPtr, IntVal);
    114   }
    115 
    116   void setUnknownCommandName(StringRef Name) {
    117     assert(is(tok::unknown_command));
    118     TextPtr = Name.data();
    119     IntVal = Name.size();
    120   }
    121 
    122   unsigned getCommandID() const LLVM_READONLY {
    123     assert(is(tok::backslash_command) || is(tok::at_command));
    124     return IntVal;
    125   }
    126 
    127   void setCommandID(unsigned ID) {
    128     assert(is(tok::backslash_command) || is(tok::at_command));
    129     IntVal = ID;
    130   }
    131 
    132   unsigned getVerbatimBlockID() const LLVM_READONLY {
    133     assert(is(tok::verbatim_block_begin) || is(tok::verbatim_block_end));
    134     return IntVal;
    135   }
    136 
    137   void setVerbatimBlockID(unsigned ID) {
    138     assert(is(tok::verbatim_block_begin) || is(tok::verbatim_block_end));
    139     IntVal = ID;
    140   }
    141 
    142   StringRef getVerbatimBlockText() const LLVM_READONLY {
    143     assert(is(tok::verbatim_block_line));
    144     return StringRef(TextPtr, IntVal);
    145   }
    146 
    147   void setVerbatimBlockText(StringRef Text) {
    148     assert(is(tok::verbatim_block_line));
    149     TextPtr = Text.data();
    150     IntVal = Text.size();
    151   }
    152 
    153   unsigned getVerbatimLineID() const LLVM_READONLY {
    154     assert(is(tok::verbatim_line_name));
    155     return IntVal;
    156   }
    157 
    158   void setVerbatimLineID(unsigned ID) {
    159     assert(is(tok::verbatim_line_name));
    160     IntVal = ID;
    161   }
    162 
    163   StringRef getVerbatimLineText() const LLVM_READONLY {
    164     assert(is(tok::verbatim_line_text));
    165     return StringRef(TextPtr, IntVal);
    166   }
    167 
    168   void setVerbatimLineText(StringRef Text) {
    169     assert(is(tok::verbatim_line_text));
    170     TextPtr = Text.data();
    171     IntVal = Text.size();
    172   }
    173 
    174   StringRef getHTMLTagStartName() const LLVM_READONLY {
    175     assert(is(tok::html_start_tag));
    176     return StringRef(TextPtr, IntVal);
    177   }
    178 
    179   void setHTMLTagStartName(StringRef Name) {
    180     assert(is(tok::html_start_tag));
    181     TextPtr = Name.data();
    182     IntVal = Name.size();
    183   }
    184 
    185   StringRef getHTMLIdent() const LLVM_READONLY {
    186     assert(is(tok::html_ident));
    187     return StringRef(TextPtr, IntVal);
    188   }
    189 
    190   void setHTMLIdent(StringRef Name) {
    191     assert(is(tok::html_ident));
    192     TextPtr = Name.data();
    193     IntVal = Name.size();
    194   }
    195 
    196   StringRef getHTMLQuotedString() const LLVM_READONLY {
    197     assert(is(tok::html_quoted_string));
    198     return StringRef(TextPtr, IntVal);
    199   }
    200 
    201   void setHTMLQuotedString(StringRef Str) {
    202     assert(is(tok::html_quoted_string));
    203     TextPtr = Str.data();
    204     IntVal = Str.size();
    205   }
    206 
    207   StringRef getHTMLTagEndName() const LLVM_READONLY {
    208     assert(is(tok::html_end_tag));
    209     return StringRef(TextPtr, IntVal);
    210   }
    211 
    212   void setHTMLTagEndName(StringRef Name) {
    213     assert(is(tok::html_end_tag));
    214     TextPtr = Name.data();
    215     IntVal = Name.size();
    216   }
    217 
    218   void dump(const Lexer &L, const SourceManager &SM) const;
    219 };
    220 
    221 /// \brief Comment lexer.
    222 class Lexer {
    223 private:
    224   Lexer(const Lexer &) LLVM_DELETED_FUNCTION;
    225   void operator=(const Lexer &) LLVM_DELETED_FUNCTION;
    226 
    227   /// Allocator for strings that are semantic values of tokens and have to be
    228   /// computed (for example, resolved decimal character references).
    229   llvm::BumpPtrAllocator &Allocator;
    230 
    231   DiagnosticsEngine &Diags;
    232 
    233   const CommandTraits &Traits;
    234 
    235   const char *const BufferStart;
    236   const char *const BufferEnd;
    237   SourceLocation FileLoc;
    238 
    239   const char *BufferPtr;
    240 
    241   /// One past end pointer for the current comment.  For BCPL comments points
    242   /// to newline or BufferEnd, for C comments points to star in '*/'.
    243   const char *CommentEnd;
    244 
    245   enum LexerCommentState {
    246     LCS_BeforeComment,
    247     LCS_InsideBCPLComment,
    248     LCS_InsideCComment,
    249     LCS_BetweenComments
    250   };
    251 
    252   /// Low-level lexer state, track if we are inside or outside of comment.
    253   LexerCommentState CommentState;
    254 
    255   enum LexerState {
    256     /// Lexing normal comment text
    257     LS_Normal,
    258 
    259     /// Finished lexing verbatim block beginning command, will lex first body
    260     /// line.
    261     LS_VerbatimBlockFirstLine,
    262 
    263     /// Lexing verbatim block body line-by-line, skipping line-starting
    264     /// decorations.
    265     LS_VerbatimBlockBody,
    266 
    267     /// Finished lexing verbatim line beginning command, will lex text (one
    268     /// line).
    269     LS_VerbatimLineText,
    270 
    271     /// Finished lexing \verbatim <TAG \endverbatim part, lexing tag attributes.
    272     LS_HTMLStartTag,
    273 
    274     /// Finished lexing \verbatim </TAG \endverbatim part, lexing '>'.
    275     LS_HTMLEndTag
    276   };
    277 
    278   /// Current lexing mode.
    279   LexerState State;
    280 
    281   /// If State is LS_VerbatimBlock, contains the name of verbatim end
    282   /// command, including command marker.
    283   SmallString<16> VerbatimBlockEndCommandName;
    284 
    285   /// Given a character reference name (e.g., "lt"), return the character that
    286   /// it stands for (e.g., "<").
    287   StringRef resolveHTMLNamedCharacterReference(StringRef Name) const;
    288 
    289   /// Given a Unicode codepoint as base-10 integer, return the character.
    290   StringRef resolveHTMLDecimalCharacterReference(StringRef Name) const;
    291 
    292   /// Given a Unicode codepoint as base-16 integer, return the character.
    293   StringRef resolveHTMLHexCharacterReference(StringRef Name) const;
    294 
    295   void formTokenWithChars(Token &Result, const char *TokEnd,
    296                           tok::TokenKind Kind);
    297 
    298   void formTextToken(Token &Result, const char *TokEnd) {
    299     StringRef Text(BufferPtr, TokEnd - BufferPtr);
    300     formTokenWithChars(Result, TokEnd, tok::text);
    301     Result.setText(Text);
    302   }
    303 
    304   SourceLocation getSourceLocation(const char *Loc) const {
    305     assert(Loc >= BufferStart && Loc <= BufferEnd &&
    306            "Location out of range for this buffer!");
    307 
    308     const unsigned CharNo = Loc - BufferStart;
    309     return FileLoc.getLocWithOffset(CharNo);
    310   }
    311 
    312   DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
    313     return Diags.Report(Loc, DiagID);
    314   }
    315 
    316   /// Eat string matching regexp \code \s*\* \endcode.
    317   void skipLineStartingDecorations();
    318 
    319   /// Lex stuff inside comments.  CommentEnd should be set correctly.
    320   void lexCommentText(Token &T);
    321 
    322   void setupAndLexVerbatimBlock(Token &T,
    323                                 const char *TextBegin,
    324                                 char Marker, const CommandInfo *Info);
    325 
    326   void lexVerbatimBlockFirstLine(Token &T);
    327 
    328   void lexVerbatimBlockBody(Token &T);
    329 
    330   void setupAndLexVerbatimLine(Token &T, const char *TextBegin,
    331                                const CommandInfo *Info);
    332 
    333   void lexVerbatimLineText(Token &T);
    334 
    335   void lexHTMLCharacterReference(Token &T);
    336 
    337   void setupAndLexHTMLStartTag(Token &T);
    338 
    339   void lexHTMLStartTag(Token &T);
    340 
    341   void setupAndLexHTMLEndTag(Token &T);
    342 
    343   void lexHTMLEndTag(Token &T);
    344 
    345 public:
    346   Lexer(llvm::BumpPtrAllocator &Allocator, DiagnosticsEngine &Diags,
    347         const CommandTraits &Traits,
    348         SourceLocation FileLoc,
    349         const char *BufferStart, const char *BufferEnd);
    350 
    351   void lex(Token &T);
    352 
    353   StringRef getSpelling(const Token &Tok,
    354                         const SourceManager &SourceMgr,
    355                         bool *Invalid = nullptr) const;
    356 };
    357 
    358 } // end namespace comments
    359 } // end namespace clang
    360 
    361 #endif
    362 
    363