src/tex2lyx/Parser.h

   1 // -*- C++ -*-
   2 /**
   3  * \file Parser.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author André Pönitz
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #ifndef PARSER_H
  13 #define PARSER_H
  14
  15 #include <string>
  16 #include <utility>
  17 #include <vector>
  18
  19 #include "support/docstream.h"
  20
  21 namespace lyx {
  22
  23
  24 enum mode_type {UNDECIDED_MODE, TEXT_MODE, MATH_MODE, MATHTEXT_MODE, TABLE_MODE};
  25
  26 mode_type asMode(mode_type oldmode, std::string const & str);
  27
  28
  29 // These are TeX's catcodes
  30 enum CatCode {
  31         catEscape,     // 0    backslash
  32         catBegin,      // 1    {
  33         catEnd,        // 2    }
  34         catMath,       // 3    $
  35         catAlign,      // 4    &
  36         catNewline,    // 5    ^^M
  37         catParameter,  // 6    #
  38         catSuper,      // 7    ^
  39         catSub,        // 8    _
  40         catIgnore,     // 9
  41         catSpace,      // 10   space
  42         catLetter,     // 11   a-zA-Z
  43         catOther,      // 12   none of the above
  44         catActive,     // 13   ~
  45         catComment,    // 14   %
  46         catInvalid     // 15   <delete>
  47 };
  48
  49 enum cat_type {
  50         NORMAL_CATCODES,
  51         VERBATIM_CATCODES,
  52         UNDECIDED_CATCODES
  53 };
  54
  55
  56 enum {
  57         FLAG_BRACE_LAST = 1 << 1,  //  last closing brace ends the parsing
  58         FLAG_RIGHT      = 1 << 2,  //  next \\right ends the parsing process
  59         FLAG_END        = 1 << 3,  //  next \\end ends the parsing process
  60         FLAG_BRACK_LAST = 1 << 4,  //  next closing bracket ends the parsing
  61         FLAG_TEXTMODE   = 1 << 5,  //  we are in a box
  62         FLAG_ITEM       = 1 << 6,  //  read a (possibly braced token)
  63         FLAG_LEAVE      = 1 << 7,  //  leave the loop at the end
  64         FLAG_SIMPLE     = 1 << 8,  //  next $ leaves the loop
  65         FLAG_EQUATION   = 1 << 9,  //  next \] leaves the loop
  66         FLAG_SIMPLE2    = 1 << 10, //  next \) leaves the loop
  67         FLAG_OPTION     = 1 << 11, //  read [...] style option
  68         FLAG_BRACED     = 1 << 12, //  read {...} style argument
  69         FLAG_CELL       = 1 << 13, //  read table cell
  70         FLAG_TABBING    = 1 << 14  //  We are inside a tabbing environment
  71 };
  72
  73
  74
  75 //
  76 // Helper class for parsing
  77 //
  78
  79 class Token {
  80 public:
  81         ///
  82         Token() : cs_(), cat_(catIgnore) {}
  83         ///
  84         Token(docstring const & cs, CatCode cat) : cs_(to_utf8(cs)), cat_(cat) {}
  85
  86         /// Returns the token as string
  87         std::string const & cs() const { return cs_; }
  88         /// Returns the catcode of the token
  89         CatCode cat() const { return cat_; }
  90         /** Get the character of tokens that were constructed from a single
  91          * character input or a two character input and cat_ == catEscape.
  92          * FIXME: The intended usage is not clear. The Token class in
  93          *        ../mathed/MathParser.cpp (which is the anchestor of this
  94          *        class) uses a separate char member for this method. I
  95          *        believe that the intended usage is to not cover tokens with
  96          *        catEscape or catComment, e.g. \code
  97          *        return (cs_.empty() || cat_ == catEscape || cat_ == catComment) ? 0 : cs_[0];
  98          *        \endcode
  99          *        All usages of this method should be checked. gb 2011-01-05
 100          */
 101         char character() const { return cs_.empty() ? 0 : cs_[0]; }
 102         /// Returns the token verbatim
 103         std::string asInput() const;
 104         /// Is the token an alphanumerical character?
 105         bool isAlnumASCII() const;
 106
 107 private:
 108         ///
 109         std::string cs_;
 110         ///
 111         CatCode cat_;
 112 };
 113
 114 std::ostream & operator<<(std::ostream & os, Token const & t);
 115
 116 #ifdef FILEDEBUG
 117 extern void debugToken(std::ostream & os, Token const & t, unsigned int flags);
 118 #endif
 119
 120 /// A docstream version that supports putback even when not buffered
 121 class iparserdocstream
 122 {
 123 public:
 124         typedef idocstream::int_type int_type;
 125
 126         iparserdocstream(idocstream & is) : is_(is) {}
 127
 128 #ifdef LYX_USE_CXX11
 129         /// Like std::istream::operator bool()
 130         /// Do not convert is_ implicitly to bool, since that is forbidden in C++11.
 131         explicit operator bool() const { return s_.empty() ? !is_.fail() : true; }
 132 #else
 133         /// Like std::istream::operator void*()
 134         operator void*() const { return (s_.empty() && is_.fail()) ?
 135                         0 : const_cast<iparserdocstream *>(this); }
 136 #endif
 137
 138         /// change the encoding of the input stream to \p e (iconv name)
 139         void setEncoding(std::string const & e);
 140
 141         // add to the list of characters to read before actually reading
 142         // the stream
 143         void putback(char_type c);
 144
 145         // add to the list of characters to read before actually reading
 146         // the stream
 147         void putback(docstring s);
 148
 149         /// Like std::istream::get()
 150         iparserdocstream & get(char_type &c);
 151
 152         /// Like std::istream::good()
 153         bool good() const { return s_.empty() ? is_.good() : true; }
 154
 155         /// Like std::istream::peek()
 156         int_type peek() const { return s_.empty() ? is_.peek() : s_[0]; }
 157 private:
 158         ///
 159         idocstream & is_;
 160         /// characters to read before actually reading the stream
 161         docstring s_;
 162 };
 163
 164
 165 /*!
 166  * Actual parser class
 167  *
 168  * The parser parses every character of the inputstream into a token
 169  * and classifies the token.
 170  * The following transformations are done:
 171  * - Consecutive spaces are combined into one single token with CatCode catSpace
 172  * - Consecutive newlines are combined into one single token with CatCode catNewline
 173  * - Comments and %\n combinations are parsed into one token with CatCode catComment
 174  */
 175
 176 class Parser {
 177         /// noncopyable
 178         Parser(Parser const & p);
 179         Parser & operator=(Parser const & p);
 180 public:
 181         ///
 182         Parser(idocstream & is, std::string const & fixedenc);
 183         ///
 184         Parser(std::string const & s);
 185         ///
 186         ~Parser();
 187
 188         /** forget already parsed next tokens and put the
 189          * corresponding characters into the input stream for
 190          * re-reading. Useful when changing catcodes. */
 191         void deparse();
 192
 193         /// change the encoding of the input stream according to \p encoding
 194         /// (latex name) and package \p package
 195         bool setEncoding(std::string const & encoding, int const & package);
 196         /// change the encoding of the input stream to \p encoding (iconv name)
 197         bool setEncoding(std::string const & encoding);
 198         /// get the current iconv encoding of the input stream
 199         std::string getEncoding() const { return encoding_iconv_; }
 200
 201         ///
 202         CatCode catcode(char_type c) const;
 203         ///
 204         void setCatcode(char c, CatCode cat);
 205         /// set parser to normal or verbatim mode
 206         void setCatcodes(cat_type t);
 207
 208         ///
 209         int lineno() const { return lineno_; }
 210         ///
 211         void putback();
 212         /// store current position
 213         void pushPosition();
 214         /// restore previous position
 215         void popPosition();
 216         /// forget last saved position
 217         void dropPosition();
 218         /// dump contents to screen
 219         void dump() const;
 220
 221         /// Does an optional argument follow after the current token?
 222         bool hasOpt();
 223         ///
 224         typedef std::pair<bool, std::string> Arg;
 225         /*!
 226          * Get an argument enclosed by \p left and \p right.
 227          * If \p allow_escaping is true, a right delimiter escaped by a
 228          * backslash does not count as delimiter, but is included in the
 229          * argument.
 230          * \returns wether an argument was found in \p Arg.first and the
 231          * argument in \p Arg.second. \see getArg().
 232          */
 233         Arg getFullArg(char left, char right, bool allow_escaping = true);
 234         /*!
 235          * Get an argument enclosed by \p left and \p right.
 236          * If \p allow_escaping is true, a right delimiter escaped by a
 237          * backslash does not count as delimiter, but is included in the
 238          * argument.
 239          * \returns the argument (without \p left and \p right) or the empty
 240          * string if the next non-space token is not \p left. Use
 241          * getFullArg() if you need to know wether there was an empty
 242          * argument or no argument at all.
 243          */
 244         std::string getArg(char left, char right, bool allow_escaping = true);
 245         /*!
 246          * Like getOpt(), but distinguishes between a missing argument ""
 247          * and an empty argument "[]".
 248          */
 249         std::string getFullOpt(bool keepws = false);
 250         /*!
 251          * \returns getArg('[', ']') including the brackets or the
 252          * empty string if there is no such argument.
 253          * No whitespace is eaten if \p keepws is true and no optional
 254          * argument exists. This is important if an optional argument is
 255          * parsed that would go after a command in ERT: In this case the
 256          * whitespace is needed to separate the ERT from the subsequent
 257          * word. Without it, the ERT and the next word would be concatenated
 258          * during .tex export, thus creating an invalid command.
 259          */
 260         std::string getOpt(bool keepws = false);
 261         /*!
 262          * \returns getFullArg('(', ')') including the parentheses or the
 263          * empty string if there is no such argument.
 264          */
 265         std::string getFullParentheseArg();
 266         /*!
 267          * \returns the contents of the environment \p name.
 268          * <tt>\begin{name}</tt> must be parsed already, <tt>\end{name}</tt>
 269          * is parsed but not returned. This parses nested environments properly.
 270          */
 271         std::string const ertEnvironment(std::string const & name);
 272         /*
 273          * The same as ertEnvironment(std::string const & name) but
 274          * \begin and \end commands inside the name environment are not parsed.
 275          * This function is designed to parse verbatim environments.
 276          */
 277         std::string const plainEnvironment(std::string const & name);
 278         /*
 279          * Basically the same as plainEnvironment(std::string const & name) but
 280          * instead of \begin and \end commands the parsing is started/stopped
 281          * at given characters.
 282          * This function is designed to parse verbatim commands.
 283          */
 284         std::string const plainCommand(char left, char right, std::string const & name);
 285         /*
 286          * Basically the same as plainEnvironment() but the parsing is
 287          * stopped at string \p end_string. Contrary to the other
 288          * methods, this uses proper catcode setting. This function is
 289          * designed to parse verbatim environments and command. The
 290          * intention is to eventually replace all of its siblings. the
 291          * member \p first of the result tells whether the arg was
 292          * found and the member \p second is the value. If \p
 293          * allow_linebreak is false, then the parsing is limited to one line
 294          */
 295         Arg verbatimStuff(std::string const & end_string,
 296                           bool allow_linebreak = true);
 297         /*
 298          * \returns the contents of the environment \p name.
 299          * <tt>\begin{name}</tt> must be parsed already,
 300          * <tt>\end{name}</tt> is parsed but not returned. The string
 301          * is parsed with proper verbatim catcodes and one newline is
 302          * removed from head and tail of the string if applicable.
 303          */
 304         std::string const verbatimEnvironment(std::string const & end_string);
 305         ///
 306         std::string verbatim_item();
 307         ///
 308         std::string verbatimOption();
 309         ///
 310         void error(std::string const & msg);
 311         /// The previous token.
 312         Token const prev_token() const;
 313         /// The current token.
 314         Token const curr_token() const;
 315         /// The next token. Caution: If this is called, an encoding change is
 316         /// only possible again after get_token() has been called.
 317         Token const next_token();
 318         /// The next but one token. Caution: If this is called, an encoding
 319         /// change is only possible again after get_token() has been called
 320         /// twice.
 321         Token const next_next_token();
 322         /// Make the next token current and return that.
 323         Token const get_token();
 324         /// \return whether the current token starts a new paragraph
 325         bool isParagraph();
 326         /// skips spaces (and comments if \p skip_comments is true)
 327         /// \return whether whitespace was skipped (not comments)
 328         bool skip_spaces(bool skip_comments = false);
 329         /// puts back spaces (and comments if \p skip_comments is true)
 330         void unskip_spaces(bool skip_comments = false);
 331         /// Is any further input pending()? This is not like
 332         /// std::istream::good(), which returns true if all available input
 333         /// was read, and the next attempt to read would return EOF.
 334         bool good();
 335         /// resets the parser to initial state
 336         void reset();
 337
 338 private:
 339         /// Setup catcode table
 340         void catInit();
 341         /// Parses one token from \p is
 342         void tokenize_one();
 343         ///
 344         void push_back(Token const & t);
 345         ///
 346         int lineno_;
 347         ///
 348         std::vector<Token> tokens_;
 349         ///
 350         size_t pos_;
 351         ///
 352         std::vector<unsigned> positions_;
 353         ///
 354         idocstringstream * iss_;
 355         ///
 356         iparserdocstream is_;
 357         /// iconv name of the current encoding
 358         std::string encoding_iconv_;
 359         ///
 360         CatCode theCatcode_[256];
 361         ///
 362         cat_type theCatcodesType_;
 363         ///
 364         cat_type curr_cat_;
 365         ///
 366         bool fixed_enc_;
 367 };
 368
 369
 370
 371 } // namespace lyx
 372
 373 #endif