src/mathed/MathStream.h

   1 // -*- C++ -*-
   2 /**
   3  * \file MathStream.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 MATH_MATHMLSTREAM_H
  13 #define MATH_MATHMLSTREAM_H
  14
  15 #include "InsetMath.h"
  16 #include "texstream.h"
  17
  18 #include "support/Changer.h"
  19 #include "support/strfwd.h"
  20 #include "support/unique_ptr.h"
  21
  22
  23 namespace lyx {
  24
  25 class Encoding;
  26 class InsetMath;
  27 class MathAtom;
  28 class MathData;
  29 struct RowEntry;
  30
  31 //
  32 // LaTeX/LyX
  33 //
  34
  35 class WriteStream {
  36 public:
  37         ///
  38         enum OutputType {
  39                 wsDefault,
  40                 wsDryrun,
  41                 wsPreview
  42         };
  43         ///
  44         explicit WriteStream(otexrowstream & os, bool fragile = false,
  45                              bool latex = false, OutputType output = wsDefault,
  46                              Encoding const * encoding = 0);
  47         ///
  48         ~WriteStream();
  49         ///
  50         int line() const { return line_; }
  51         ///
  52         bool fragile() const { return fragile_; }
  53         ///
  54         bool latex() const { return latex_; }
  55         ///
  56         OutputType output() const { return output_; }
  57         ///
  58         otexrowstream & os() { return os_; }
  59         ///
  60         TexRow & texrow() { return os_.texrow(); }
  61         ///
  62         bool & firstitem() { return firstitem_; }
  63         ///
  64         void addlines(unsigned int);
  65         /// record whether we can write an immediately following newline char
  66         void canBreakLine(bool breakline) { canbreakline_ = breakline; }
  67         /// tell whether we can write an immediately following newline char
  68         bool canBreakLine() const { return canbreakline_; }
  69         /// writes space if next thing is isalpha()
  70         void pendingSpace(bool how);
  71         /// writes space if next thing is isalpha()
  72         bool pendingSpace() const { return pendingspace_; }
  73         /// tell whether to write the closing brace of \ensuremath
  74         void pendingBrace(bool brace);
  75         /// tell whether to write the closing brace of \ensuremath
  76         bool pendingBrace() const { return pendingbrace_; }
  77         /// tell whether we are in text mode or not when producing latex code
  78         void textMode(bool textmode);
  79         /// tell whether we are in text mode or not when producing latex code
  80         bool textMode() const { return textmode_; }
  81         /// tell whether we are allowed to switch mode when producing latex code
  82         void lockedMode(bool locked);
  83         /// tell whether we are allowed to switch mode when producing latex code
  84         bool lockedMode() const { return locked_; }
  85         /// tell whether to use only ascii chars when producing latex code
  86         void asciiOnly(bool ascii);
  87         /// tell whether to use only ascii chars when producing latex code
  88         bool asciiOnly() const { return ascii_; }
  89         /// LaTeX encoding
  90         Encoding const * encoding() const { return encoding_; }
  91
  92         /// Temporarily change the TexRow information about the outer row entry.
  93         Changer changeRowEntry(RowEntry entry);
  94         /// TexRow::starts the innermost outer math inset
  95         /// returns true if the outer row entry will appear at this line
  96         bool startOuterRow();
  97 private:
  98         ///
  99         otexrowstream & os_;
 100         /// do we have to write \\protect sometimes
 101         bool fragile_;
 102         /// are we at the beginning of an MathData?
 103         bool firstitem_;
 104         /// are we writing to .tex?
 105         int latex_;
 106         /// output type (default, source preview, instant preview)?
 107         OutputType output_;
 108         /// do we have a space pending?
 109         bool pendingspace_;
 110         /// do we have a brace pending?
 111         bool pendingbrace_;
 112         /// are we in text mode when producing latex code?
 113         bool textmode_;
 114         /// are we allowed to switch mode when producing latex code?
 115         bool locked_;
 116         /// should we use only ascii chars when producing latex code?
 117         bool ascii_;
 118         /// are we allowed to output an immediately following newline?
 119         bool canbreakline_;
 120         ///
 121         int line_;
 122         ///
 123         Encoding const * encoding_;
 124         /// Row entry we are in
 125         /// (it is a pointer to allow forward-declaration)
 126         unique_ptr<RowEntry> row_entry_;
 127 };
 128
 129 ///
 130 WriteStream & operator<<(WriteStream &, MathAtom const &);
 131 ///
 132 WriteStream & operator<<(WriteStream &, MathData const &);
 133 ///
 134 WriteStream & operator<<(WriteStream &, docstring const &);
 135 ///
 136 WriteStream & operator<<(WriteStream &, char const * const);
 137 ///
 138 WriteStream & operator<<(WriteStream &, char);
 139 ///
 140 WriteStream & operator<<(WriteStream &, int);
 141 ///
 142 WriteStream & operator<<(WriteStream &, unsigned int);
 143
 144 /// ensure correct mode, possibly by opening \ensuremath or \lyxmathsym
 145 bool ensureMath(WriteStream & os, bool needs_mathmode = true,
 146                 bool macro = false, bool textmode_macro = false);
 147
 148 /// ensure the requested mode, possibly by closing \ensuremath or \lyxmathsym
 149 int ensureMode(WriteStream & os, InsetMath::mode_type mode, bool locked, bool ascii);
 150
 151
 152 /**
 153  * MathEnsurer - utility class for ensuring math mode
 154  *
 155  * A local variable of this type can be used to either ensure math mode
 156  * or delay the writing of a pending brace when outputting LaTeX.
 157  * A LyX MathMacro is always assumed needing a math mode environment, while
 158  * no assumption is made for macros defined through \newcommand or \def.
 159  *
 160  * Example 1:
 161  *
 162  *      MathEnsurer ensurer(os);
 163  *
 164  * If not already in math mode, inserts an \ensuremath command followed
 165  * by an open brace. This brace will be automatically closed when exiting
 166  * math mode. Math mode is automatically exited when writing something
 167  * that doesn't explicitly require math mode.
 168  *
 169  * Example 2:
 170  *
 171  *      MathEnsurer ensurer(os, false);
 172  *
 173  * Simply suspend writing a closing brace until the end of ensurer's scope.
 174  *
 175  * Example 3:
 176  *
 177  *      MathEnsurer ensurer(os, needs_mathmode, true, textmode_macro);
 178  *
 179  * This form is mainly used for math macros as they are treated specially.
 180  * In essence, the macros defined in the lib/symbols file and tagged as
 181  * textmode will be enclosed in \lyxmathsym if they appear in a math mode
 182  * environment, while macros defined in the preamble or ERT are left as is.
 183  * The third parameter must be set to true and the fourth parameter has also
 184  * to be specified. Only the following 3 different cases are handled.
 185  *
 186  * When the needs_mathmode parameter is true the behavior is as in Example 1.
 187  * This is the case for a LyX MathMacro or a macro not tagged as textmode.
 188  *
 189  * When the needs_mathmode and textmode_macro parameters are both false the
 190  * macro is left in the same (text or math mode) environment it was entered.
 191  * This is because it is assumed that the macro was designed for that mode
 192  * and we have no way to tell the contrary.
 193  * This is the case for macros defined by using \newcommand or \def in ERT.
 194  *
 195  * When the needs_mathmode parameter is false while textmode_macro is true the
 196  * macro will be enclosed in \lyxmathsym if it appears in a math mode environment.
 197  * This is the case for the macros tagged as textmode in lib/symbols.
 198  */
 199 class MathEnsurer
 200 {
 201 public:
 202         ///
 203         explicit MathEnsurer(WriteStream & os, bool needs_mathmode = true,
 204                              bool macro = false, bool textmode_macro = false)
 205                 : os_(os), brace_(ensureMath(os, needs_mathmode, macro, textmode_macro)) {}
 206         ///
 207         ~MathEnsurer() { os_.pendingBrace(brace_); }
 208 private:
 209         ///
 210         WriteStream & os_;
 211         ///
 212         bool brace_;
 213 };
 214
 215
 216 /**
 217  * ModeSpecifier - utility class for specifying a given mode (math or text)
 218  *
 219  * A local variable of this type can be used to specify that a command or
 220  * environment works in a given mode. For example, \mbox works in text
 221  * mode, but \boxed works in math mode. Note that no mode changing commands
 222  * are needed, but we have to track the current mode, hence this class.
 223  * This is only used when exporting to latex and helps determining whether
 224  * the mode needs being temporarily switched when a command would not work
 225  * in the current mode. As there are cases where this switching is to be
 226  * avoided, the optional third parameter can be used to lock the mode.
 227  * When the mode is locked, the optional fourth parameter specifies whether
 228  * strings are to be output by using a suitable ascii representation.
 229  *
 230  * Example 1:
 231  *
 232  *      ModeSpecifier specifier(os, TEXT_MODE);
 233  *
 234  * Sets the current mode to text mode and allows mode switching.
 235  *
 236  * Example 2:
 237  *
 238  *      ModeSpecifier specifier(os, TEXT_MODE, true);
 239  *
 240  * Sets the current mode to text mode and disallows mode switching.
 241  *
 242  * Example 3:
 243  *
 244  *      ModeSpecifier specifier(os, TEXT_MODE, true, true);
 245  *
 246  * Sets the current mode to text mode, disallows mode switching, and outputs
 247  * strings as ascii only.
 248  *
 249  * At the end of specifier's scope the mode is reset to its previous value.
 250  */
 251 class ModeSpecifier
 252 {
 253 public:
 254         ///
 255         explicit ModeSpecifier(WriteStream & os, InsetMath::mode_type mode,
 256                                 bool locked = false, bool ascii = false)
 257                 : os_(os), oldmodes_(ensureMode(os, mode, locked, ascii)) {}
 258         ///
 259         ~ModeSpecifier()
 260         {
 261                 os_.textMode(oldmodes_ & 0x01);
 262                 os_.lockedMode(oldmodes_ & 0x02);
 263                 os_.asciiOnly(oldmodes_ & 0x04);
 264         }
 265 private:
 266         ///
 267         WriteStream & os_;
 268         ///
 269         int oldmodes_;
 270 };
 271
 272
 273
 274 //
 275 //  MathML
 276 //
 277
 278 class MTag {
 279 public:
 280         ///
 281         MTag(char const * const tag, std::string attr = "")
 282                 : tag_(tag), attr_(attr) {}
 283         ///
 284         char const * const tag_;
 285         ///
 286         std::string attr_;
 287 };
 288
 289 class ETag {
 290 public:
 291         ///
 292         ETag(char const * const tag) : tag_(tag) {}
 293         ///
 294         char const * const tag_;
 295 };
 296
 297
 298 /// Throw MathExportException to signal that the attempt to export
 299 /// some math in the current format did not succeed. E.g., we can't
 300 /// export xymatrix as MathML, so that will throw, and we'll fall back
 301 /// to images.
 302 class MathExportException : public std::exception {};
 303
 304
 305 class MathStream {
 306 public:
 307         ///
 308         explicit MathStream(odocstream & os);
 309         ///
 310         void cr();
 311         ///
 312         odocstream & os() { return os_; }
 313         ///
 314         int line() const { return line_; }
 315         ///
 316         int & tab() { return tab_; }
 317         ///
 318         friend MathStream & operator<<(MathStream &, char const *);
 319         ///
 320         void defer(docstring const &);
 321         ///
 322         void defer(std::string const &);
 323         ///
 324         docstring deferred() const;
 325         ///
 326         bool inText() const { return in_text_; }
 327 private:
 328         ///
 329         void setTextMode(bool t) { in_text_ = t; }
 330         ///
 331         odocstream & os_;
 332         ///
 333         int tab_;
 334         ///
 335         int line_;
 336         ///
 337         bool in_text_;
 338         ///
 339         odocstringstream deferred_;
 340         ///
 341         friend class SetMode;
 342 };
 343
 344 ///
 345 MathStream & operator<<(MathStream &, MathAtom const &);
 346 ///
 347 MathStream & operator<<(MathStream &, MathData const &);
 348 ///
 349 MathStream & operator<<(MathStream &, docstring const &);
 350 ///
 351 MathStream & operator<<(MathStream &, char const *);
 352 ///
 353 MathStream & operator<<(MathStream &, char);
 354 ///
 355 MathStream & operator<<(MathStream &, char_type);
 356 ///
 357 MathStream & operator<<(MathStream &, MTag const &);
 358 ///
 359 MathStream & operator<<(MathStream &, ETag const &);
 360
 361
 362 /// A simpler version of ModeSpecifier, for MathML
 363 class SetMode {
 364 public:
 365         ///
 366         explicit SetMode(MathStream & os, bool text);
 367         ///
 368         ~SetMode();
 369 private:
 370         ///
 371         MathStream & os_;
 372         ///
 373         bool was_text_;
 374 };
 375
 376
 377 class HtmlStream {
 378 public:
 379         ///
 380         explicit HtmlStream(odocstream & os);
 381         ///
 382         void cr();
 383         ///
 384         odocstream & os() { return os_; }
 385         ///
 386         int line() const { return line_; }
 387         ///
 388         int & tab() { return tab_; }
 389         ///
 390         friend HtmlStream & operator<<(HtmlStream &, char const *);
 391         ///
 392         void defer(docstring const &);
 393         ///
 394         void defer(std::string const &);
 395         ///
 396         docstring deferred() const;
 397         ///
 398         bool inText() const { return in_text_; }
 399 private:
 400         ///
 401         void setTextMode(bool t) { in_text_ = t; }
 402         ///
 403         odocstream & os_;
 404         ///
 405         int tab_;
 406         ///
 407         int line_;
 408         ///
 409         bool in_text_;
 410         ///
 411         odocstringstream deferred_;
 412         ///
 413         friend class SetHTMLMode;
 414 };
 415
 416 ///
 417 HtmlStream & operator<<(HtmlStream &, MathAtom const &);
 418 ///
 419 HtmlStream & operator<<(HtmlStream &, MathData const &);
 420 ///
 421 HtmlStream & operator<<(HtmlStream &, docstring const &);
 422 ///
 423 HtmlStream & operator<<(HtmlStream &, char const *);
 424 ///
 425 HtmlStream & operator<<(HtmlStream &, char);
 426 ///
 427 HtmlStream & operator<<(HtmlStream &, char_type);
 428 ///
 429 HtmlStream & operator<<(HtmlStream &, MTag const &);
 430 ///
 431 HtmlStream & operator<<(HtmlStream &, ETag const &);
 432
 433
 434 class SetHTMLMode {
 435 public:
 436         ///
 437         explicit SetHTMLMode(HtmlStream & os, bool text);
 438         ///
 439         ~SetHTMLMode();
 440 private:
 441         ///
 442         HtmlStream & os_;
 443         ///
 444         bool was_text_;
 445 };
 446
 447
 448 //
 449 // Debugging
 450 //
 451
 452 class NormalStream {
 453 public:
 454         ///
 455         explicit NormalStream(odocstream & os) : os_(os) {}
 456         ///
 457         odocstream & os() { return os_; }
 458 private:
 459         ///
 460         odocstream & os_;
 461 };
 462
 463 ///
 464 NormalStream & operator<<(NormalStream &, MathAtom const &);
 465 ///
 466 NormalStream & operator<<(NormalStream &, MathData const &);
 467 ///
 468 NormalStream & operator<<(NormalStream &, docstring const &);
 469 ///
 470 NormalStream & operator<<(NormalStream &, char const *);
 471 ///
 472 NormalStream & operator<<(NormalStream &, char);
 473 ///
 474 NormalStream & operator<<(NormalStream &, int);
 475
 476
 477 //
 478 // Maple
 479 //
 480
 481
 482 class MapleStream {
 483 public:
 484         ///
 485         explicit MapleStream(odocstream & os) : os_(os) {}
 486         ///
 487         odocstream & os() { return os_; }
 488 private:
 489         ///
 490         odocstream & os_;
 491 };
 492
 493
 494 ///
 495 MapleStream & operator<<(MapleStream &, MathAtom const &);
 496 ///
 497 MapleStream & operator<<(MapleStream &, MathData const &);
 498 ///
 499 MapleStream & operator<<(MapleStream &, docstring const &);
 500 ///
 501 MapleStream & operator<<(MapleStream &, char_type);
 502 ///
 503 MapleStream & operator<<(MapleStream &, char const *);
 504 ///
 505 MapleStream & operator<<(MapleStream &, char);
 506 ///
 507 MapleStream & operator<<(MapleStream &, int);
 508
 509
 510 //
 511 // Maxima
 512 //
 513
 514
 515 class MaximaStream {
 516 public:
 517         ///
 518         explicit MaximaStream(odocstream & os) : os_(os) {}
 519         ///
 520         odocstream & os() { return os_; }
 521 private:
 522         ///
 523         odocstream & os_;
 524 };
 525
 526
 527 ///
 528 MaximaStream & operator<<(MaximaStream &, MathAtom const &);
 529 ///
 530 MaximaStream & operator<<(MaximaStream &, MathData const &);
 531 ///
 532 MaximaStream & operator<<(MaximaStream &, docstring const &);
 533 ///
 534 MaximaStream & operator<<(MaximaStream &, char_type);
 535 ///
 536 MaximaStream & operator<<(MaximaStream &, char const *);
 537 ///
 538 MaximaStream & operator<<(MaximaStream &, char);
 539 ///
 540 MaximaStream & operator<<(MaximaStream &, int);
 541
 542
 543 //
 544 // Mathematica
 545 //
 546
 547
 548 class MathematicaStream {
 549 public:
 550         ///
 551         explicit MathematicaStream(odocstream & os) : os_(os) {}
 552         ///
 553         odocstream & os() { return os_; }
 554 private:
 555         ///
 556         odocstream & os_;
 557 };
 558
 559
 560 ///
 561 MathematicaStream & operator<<(MathematicaStream &, MathAtom const &);
 562 ///
 563 MathematicaStream & operator<<(MathematicaStream &, MathData const &);
 564 ///
 565 MathematicaStream & operator<<(MathematicaStream &, docstring const &);
 566 ///
 567 MathematicaStream & operator<<(MathematicaStream &, char const *);
 568 ///
 569 MathematicaStream & operator<<(MathematicaStream &, char);
 570 ///
 571 MathematicaStream & operator<<(MathematicaStream &, int);
 572
 573
 574 //
 575 // Octave
 576 //
 577
 578
 579 class OctaveStream {
 580 public:
 581         ///
 582         explicit OctaveStream(odocstream & os) : os_(os) {}
 583         ///
 584         odocstream & os() { return os_; }
 585 private:
 586         ///
 587         odocstream & os_;
 588 };
 589
 590 ///
 591 OctaveStream & operator<<(OctaveStream &, MathAtom const &);
 592 ///
 593 OctaveStream & operator<<(OctaveStream &, MathData const &);
 594 ///
 595 OctaveStream & operator<<(OctaveStream &, docstring const &);
 596 ///
 597 OctaveStream & operator<<(OctaveStream &, char_type);
 598 ///
 599 OctaveStream & operator<<(OctaveStream &, char const *);
 600 ///
 601 OctaveStream & operator<<(OctaveStream &, char);
 602 ///
 603 OctaveStream & operator<<(OctaveStream &, int);
 604
 605
 606 docstring convertDelimToXMLEscape(docstring const & name);
 607
 608 } // namespace lyx
 609
 610 #endif