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