src/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 { class FileName; }
  26
  27 /** A helper structure to describe a keyword for the Lexer.
  28         Usually used bundled in C style arrays and passed to the
  29         Lexer using a LexerKeywordTable object.
  30 */
  31 struct LexerKeyword
  32 {
  33         /// the string to be recognized
  34         char const * tag;
  35         /// a corresponding numerical id
  36         int code;
  37 };
  38
  39
  40 /** Generalized simple lexical analizer.
  41         Use the method isOK() to check if there is still data available
  42         for lexing. Use one of the the operators void* or ! to test if
  43         the last reading operation was successful.
  44
  45         Example:
  46
  47         int readParam(LyxLex & lex)
  48         {
  49                 int param = 1;    // default value
  50                 if (lex.isOK()) { // the lexer has data to read
  51                         int p;          // temporary variable
  52                         lex >> p;
  53                         if (lex)
  54                                 param = p; // only use the input if reading was successful
  55                 }
  56                 return param;
  57         }
  58
  59     @see LyXRC.cpp for an example of usage.
  60   */
  61 class Lexer
  62 {
  63 public:
  64         /// initialize Lexer with no special keywords.
  65         Lexer();
  66         /// initialize Lexer with a bunch of keywords
  67         template<int N> Lexer(LexerKeyword (&table)[N])
  68         : pimpl_(0), lastReadOk_(false) { init(table, N); }
  69
  70         ///
  71         ~Lexer();
  72
  73         /// Lex basic codes
  74         enum {
  75                 ///
  76                 LEX_UNDEF = -1,
  77                 ///
  78                 LEX_FEOF  = -2,
  79                 ///
  80                 LEX_DATA  = -3,
  81                 ///
  82                 LEX_TOKEN = -4
  83         };
  84
  85         /// stream is open and end of stream is not reached
  86         /// FIXME: test also if pushToken is not empty
  87         /// FIXME: the method should be renamed to something like
  88         ///        dataAvailable(), in order to reflect the real behavior
  89         bool isOK() const;
  90         /// FIXME: The next two operators should be replaced by one method
  91         ///        called e.g. lastReadOk(), in order to reflect the real
  92         ///        behavior
  93         /// last read operation was successful.
  94         operator void const *() const;
  95         /// last read operation was not successful
  96         bool operator!() const;
  97         /// return true if able to open file, else false
  98         bool setFile(support::FileName const & filename);
  99         ///
 100         void setStream(std::istream & is);
 101         ///
 102         std::istream & getStream();
 103         /// Danger! Don't use it unless you know what you are doing.
 104         void setLineNumber(int l);
 105         /// Change the character that begins a comment. Default is '#'
 106         void setCommentChar(char c);
 107
 108         /// returns a lex code
 109         int lex();
 110
 111         /// Read the next string, as delimited by double quotes or
 112         /// whitespace. If esc is true, then we remember that some chars
 113         /// might be escaped: \" at least.
 114         bool next(bool esc = false);
 115
 116         /// Read next token. This one is almost the same as next(),
 117         /// but it will consider " as a regular character and always
 118         /// split a word if it contains a backslash.
 119         bool nextToken();
 120
 121         /// Puts the rest of the line in the buffer, where it will
 122         /// be available via getString() or getDocString().
 123         bool eatLine();
 124
 125         /// Push a token, that next token got from lyxlex.
 126         void pushToken(std::string const &);
 127
 128         /// return the current line number
 129         int lineNumber() const;
 130
 131         ///
 132         int getInteger() const;
 133         ///
 134         bool getBool() const;
 135         ///
 136         double getFloat() const;
 137         ///
 138         std::string const getString(bool trim = false) const;
 139         ///
 140         docstring const getDocString(bool trim = false) const;
 141         /** Get a long string, ended by the tag `endtoken'.
 142             This string can span several lines. The first line
 143             serves as a template for how many spaces the lines
 144             are indented. This much white space is skipped from
 145             each following line. This mechanism does not work
 146             perfectly if you use tabs.
 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
 261 } // namespace lyx
 262
 263 #endif