src/support/Lexer.h

   1 // -*- C++ -*-
   2 /**
   3  * \file Lexer.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Alejandro Aguilar Sierra
   8  * \author Lars Gullik Bjønnes
   9  *
  10  * Full author contact details are available in file CREDITS.
  11  */
  12
  13 //  Generalized simple lexical analizer.
  14 //  It can be used for simple syntax parsers, like lyxrc,
  15 //  texclass and others to come.
  16
  17 #ifndef LEXER_H
  18 #define LEXER_H
  19
  20 #include "support/strfwd.h"
  21 #include <string>
  22
  23 namespace lyx {
  24
  25 namespace support {
  26
  27 class FileName;
  28
  29 /** A helper structure to describe a keyword for the Lexer.
  30         Usually used bundled in C style arrays and passed to the
  31         Lexer using a LexerKeywordTable object.
  32 */
  33 struct LexerKeyword
  34 {
  35         /// the string to be recognized
  36         char const * tag;
  37         /// a corresponding numerical id
  38         int code;
  39 };
  40
  41
  42 /** Generalized simple lexical analyzer.
  43         Use the method isOK() to check if there is still data available
  44         for lexing. Use one of the the operators void* or ! to test if
  45         the last reading operation was successful.
  46
  47         Example:
  48
  49         int readParam(LyxLex & lex)
  50         {
  51                 int param = 1;    // default value
  52                 if (lex.isOK()) { // the lexer has data to read
  53                         int p;          // temporary variable
  54                         lex >> p;
  55                         if (lex)
  56                                 param = p; // only use the input if reading was successful
  57                 }
  58                 return param;
  59         }
  60
  61     @see LyXRC.cpp for an example of usage.
  62   */
  63 class Lexer
  64 {
  65 public:
  66         /// initialize Lexer with no special keywords.
  67         Lexer();
  68         /// initialize Lexer with a bunch of keywords
  69         template<int N> Lexer(LexerKeyword (&table)[N])
  70         : pimpl_(0), lastReadOk_(false) { init(table, N); }
  71
  72         ///
  73         ~Lexer();
  74
  75         /// Lex basic codes
  76         enum {
  77                 ///
  78                 LEX_UNDEF = -1,
  79                 ///
  80                 LEX_FEOF  = -2,
  81                 ///
  82                 LEX_DATA  = -3,
  83                 ///
  84                 LEX_TOKEN = -4
  85         };
  86
  87         /// stream is open and end of stream is not reached
  88         /// FIXME: test also if pushToken is not empty
  89         /// FIXME: the method should be renamed to something like
  90         ///        dataAvailable(), in order to reflect the real behavior
  91         bool isOK() const;
  92         /// FIXME: The next two operators should be replaced by one method
  93         ///        called e.g. lastReadOk(), in order to reflect the real
  94         ///        behavior
  95         /// last read operation was successful.
  96         operator void const *() const;
  97         /// last read operation was not successful
  98         bool operator!() const;
  99         /// return true if able to open file, else false
 100         bool setFile(support::FileName const & filename);
 101         ///
 102         void setStream(std::istream & is);
 103         ///
 104         std::istream & getStream();
 105         /// Danger! Don't use it unless you know what you are doing.
 106         void setLineNumber(int l);
 107         /// Change the character that begins a comment. Default is '#'
 108         void setCommentChar(char c);
 109
 110         /// returns a lex code
 111         int lex();
 112
 113         /// Read the next string, as delimited by double quotes or
 114         /// whitespace. If esc is true, then we remember that some chars
 115         /// might be escaped: \" at least.
 116         bool next(bool esc = false);
 117
 118         /// Read next token. This one is almost the same as next(),
 119         /// but it will consider " as a regular character and always
 120         /// split a word if it contains a backslash.
 121         bool nextToken();
 122
 123         /// Puts the rest of the line in the buffer, where it will
 124         /// be available via getString() or getDocString().
 125         bool eatLine();
 126
 127         /// Push a token, that next token got from lyxlex.
 128         void pushToken(std::string const &);
 129
 130         /// return the current line number
 131         int lineNumber() const;
 132
 133         ///
 134         int getInteger() const;
 135         ///
 136         bool getBool() const;
 137         ///
 138         double getFloat() const;
 139         ///
 140         std::string const getString(bool trim = false) const;
 141         ///
 142         docstring const getDocString(bool trim = false) const;
 143         /** Get a long string, ended by the tag `endtoken'. This string
 144             can span several lines. The first line serves as a template
 145             for what sequence of tabs and spaces make up the indentation.
 146             This prefix is skipped from each following line.
 147         */
 148         docstring getLongString(docstring const & endtoken);
 149
 150         /// Pushes a token list on a stack and replaces it with a new one.
 151         template<int N> void pushTable(LexerKeyword (&table)[N])
 152                 { pushTable(table, N); }
 153
 154         /** Pops a token list into void and replaces it with the one now
 155             on top of the stack.
 156         */
 157         void popTable();
 158
 159         /** Prints an error message with the corresponding line number
 160             and file name. If message contains the substring `$$Token',
 161             it is replaced with the value of GetString()
 162         */
 163         void printError(std::string const & message) const;
 164
 165         /// Prints the current token table on the supplied ostream.
 166         void printTable(std::ostream &);
 167         /// Used to dispaly context information in case of errors.
 168         void setContext(std::string const & functionName);
 169
 170         /// extract string
 171         Lexer & operator>>(std::string &);
 172         /// extract docstring
 173         Lexer & operator>>(docstring &);
 174         /// extract double
 175         Lexer & operator>>(double &);
 176         /// extract integer
 177         Lexer & operator>>(int &);
 178         /// extract unsigned integer
 179         Lexer & operator>>(unsigned int &);
 180         /// extract bool
 181         Lexer & operator>>(bool &);
 182         /// extract first char of the string
 183         Lexer & operator>>(char &);
 184
 185         /// read and check a required token
 186         Lexer & operator>>(char const * required);
 187         /// check for an optional token and swallow it if present.
 188         bool checkFor(char const * required);
 189
 190         /// Quotes a string so that reading it again with Lexer::next(true)
 191         /// gets the original string
 192         static std::string quoteString(std::string const &);
 193         /// Quotes a docstring so that reading it again with Lexer::next(true)
 194         /// gets the original string
 195         static docstring quoteString(docstring const &);
 196
 197 private:
 198         /// noncopyable
 199         Lexer(Lexer const &);
 200         void operator=(Lexer const &);
 201
 202         ///
 203         friend class PushPopHelper;
 204
 205         ///
 206         void init(LexerKeyword *, int);
 207         void pushTable(LexerKeyword *, int);
 208
 209         ///
 210         class Pimpl;
 211         ///
 212         Pimpl * pimpl_;
 213         ///
 214         mutable bool lastReadOk_;
 215 };
 216
 217
 218 /// extract something constructable from a string, i.e. a LaTeX length
 219 template <class T>
 220 Lexer & operator>>(Lexer & lex, T & t)
 221 {
 222         if (lex.next())
 223                 t = T(lex.getString());
 224         return lex;
 225 }
 226
 227
 228 /** Use to enable multiple exit points.
 229     This is needed to ensure that the pop is done upon exit from methods
 230     with more than one exit point or that can return as a response to
 231     exceptions.
 232     @author Lgb
 233 */
 234 class PushPopHelper
 235 {
 236 public:
 237         ///
 238         template<int N>
 239         PushPopHelper(Lexer & l, LexerKeyword (&table)[N])
 240                 : lex(l)
 241         {
 242                 lex.pushTable(table, N);
 243         }
 244         ///
 245         ~PushPopHelper()
 246         {
 247                 lex.popTable();
 248         }
 249         ///
 250         Lexer & lex;
 251 };
 252 /** Avoid wrong usage of PushPopHelper.
 253     To avoid wrong usage:
 254     PushPopHelper(...); // wrong
 255     PushPopHelper pph(...); // right
 256 */
 257 #define PushPopHelper(x, y, z) unnamed_PushPopHelper;
 258 // Tip gotten from Bobby Schmidt's column in C/C++ Users Journal
 259
 260 } // namespace support
 261
 262 } // namespace lyx
 263
 264 #endif