src/xml.h

   1 // -*- C++ -*-
   2 /**
   3  * \file xml.h
   4  * This file is part of LyX, the document processor.
   5  * License details can be found in the file COPYING.
   6  *
   7  * \author José Matos
   8  * \author John Levon
   9  *
  10  * Full author contact details are available in file CREDITS.
  11  */
  12
  13 #ifndef XML_H
  14 #define XML_H
  15
  16 #include "support/docstring.h"
  17
  18 #include <deque>
  19 #include <memory>
  20
  21 namespace lyx {
  22
  23 class Buffer;
  24 class Paragraph;
  25 class OutputParams;
  26
  27 // Inspiration for the *Tag structs and for XMLStream
  28 // came from MathStream and its cousins.
  29
  30 namespace xml {
  31 struct StartTag;
  32 struct EndTag;
  33 struct CompTag;
  34 struct ParTag;
  35 struct FontTag;
  36 struct CR;
  37 }
  38
  39 class XMLStream {
  40 public:
  41         ///
  42         explicit XMLStream(odocstream & os): os_(os), escape_(ESCAPE_ALL) {}
  43         ///
  44         odocstream & os() { return os_; }
  45         ///
  46         // int & tab() { return tab_; }
  47         /// closes any font tags that are eligible to be closed,
  48         /// i.e., last on the tag_stack_.
  49         /// \return false if there are open font tags we could not close.
  50         /// because they are "blocked" by open non-font tags on the stack.
  51         bool closeFontTags();
  52         /// sets a mark so we know what tags to close at the end.
  53         /// normally called at the start of a paragraph.
  54         void startDivision(bool keep_empty);
  55         /// clears the mark set by previous method.
  56         /// there should not be any other tags open before it on the stack,
  57         /// but if there are, we will close them.
  58         void endDivision();
  59         ///
  60         XMLStream & operator<<(docstring const &);
  61         ///
  62         XMLStream & operator<<(const char *);
  63         ///
  64         XMLStream & operator<<(char_type);
  65         ///
  66         XMLStream & operator<<(int);
  67         ///
  68         XMLStream & operator<<(char);
  69         ///
  70         XMLStream & operator<<(xml::StartTag const &);
  71         ///
  72         XMLStream & operator<<(xml::EndTag const &);
  73         ///
  74         XMLStream & operator<<(xml::CompTag const &);
  75         ///
  76         XMLStream & operator<<(xml::ParTag const &);
  77         ///
  78         XMLStream & operator<<(xml::FontTag const &);
  79         ///
  80         XMLStream & operator<<(xml::CR const &);
  81         ///
  82         enum EscapeSettings {
  83                 ESCAPE_NONE,
  84                 ESCAPE_AND, // meaning &
  85                 ESCAPE_ALL, // meaning <, >, &, at present
  86                 ESCAPE_COMMENTS // Anything that is forbidden within comments
  87         };
  88         /// Sets what we are going to escape on the NEXT write.
  89         /// Everything is reset for the next time.
  90         XMLStream & operator<<(EscapeSettings);
  91         /// This routine is for debugging the tag stack, etc. Code
  92         /// for it is disabled by default, however, so you will need
  93         /// to enable it if you want to use it.
  94         void dumpTagStack(std::string const & msg);
  95         ///
  96         bool isTagOpen(xml::StartTag const &, int maxdepth = -1) const;
  97         ///
  98         bool isTagOpen(xml::EndTag const &, int maxdepth = -1) const;
  99         ///
 100         bool isTagPending(xml::StartTag const &, int maxdepth = -1) const;
 101 private:
 102         ///
 103         void clearTagDeque();
 104         ///
 105         void writeError(std::string const &) const;
 106         ///
 107         void writeError(docstring const &) const;
 108         ///
 109         odocstream & os_;
 110         ///
 111         EscapeSettings escape_;
 112         // What we would really like to do here is simply use a
 113         // deque<StartTag>. But we want to store both StartTags and
 114         // sub-classes thereof on this stack, which means we run into the
 115         // so-called polymorphic class problem with the STL. We therefore have
 116         // to use a deque<StartTag *>, which leads to the question who will
 117         // own these pointers and how they will be deleted, so we use shared
 118         // pointers.
 119         ///
 120         typedef std::shared_ptr<xml::StartTag> TagPtr;
 121         typedef std::deque<TagPtr> TagDeque;
 122         ///
 123         template <typename T>
 124         TagPtr makeTagPtr(T const & tag) { return std::make_shared<T>(tag); }
 125         ///
 126         TagDeque pending_tags_;
 127         ///
 128         TagDeque tag_stack_;
 129 };
 130
 131 namespace xml {
 132
 133 /// Escape the given character, if necessary, to an entity.
 134 docstring escapeChar(char_type c, XMLStream::EscapeSettings e);
 135
 136 /// Escape the given character, if necessary, to an entity.
 137 docstring escapeChar(char c, XMLStream::EscapeSettings e);
 138
 139 /// Escape a word instead of a single character
 140 docstring escapeString(docstring const & raw, XMLStream::EscapeSettings e=XMLStream::ESCAPE_ALL);
 141
 142 /// cleans \param str for use as an attribute by replacing all non-altnum by "_"
 143 docstring cleanAttr(docstring const & str);
 144
 145 /// \p c must be ASCII
 146 docstring escapeChar(char c, XMLStream::EscapeSettings e);
 147
 148 /// replaces illegal characters from ID attributes
 149 docstring cleanID(docstring const &orig);
 150
 151 /// returns a unique numeric ID
 152 docstring uniqueID(docstring const & label);
 153
 154 struct FontTag;
 155 struct EndFontTag;
 156
 157 /// Attributes will be escaped automatically and so should NOT
 158 /// be escaped before being passed to the constructor.
 159 struct StartTag
 160 {
 161         ///
 162         explicit StartTag(std::string const & tag) : tag_(from_ascii(tag)), keepempty_(false) {}
 163         ///
 164         explicit StartTag(docstring const & tag) : tag_(tag), keepempty_(false) {}
 165         ///
 166         explicit StartTag(docstring const & tag, docstring const & attr,
 167                                           bool keepempty = false)
 168                         : tag_(tag), attr_(attr), keepempty_(keepempty) {}
 169         ///
 170         explicit StartTag(std::string const & tag, std::string const & attr,
 171                                           bool keepempty = false)
 172                         : tag_(from_ascii(tag)), attr_(from_ascii(attr)), keepempty_(keepempty) {}
 173         ///
 174         explicit StartTag(std::string const & tag, docstring const & attr,
 175                                           bool keepempty = false)
 176                         : tag_(from_ascii(tag)), attr_(attr), keepempty_(keepempty) {}
 177         ///
 178         virtual ~StartTag() {}
 179         /// <tag_ attr_>
 180         virtual docstring writeTag() const;
 181         /// </tag_>
 182         virtual docstring writeEndTag() const;
 183         ///
 184         virtual FontTag const * asFontTag() const { return nullptr; }
 185         ///
 186         virtual bool operator==(StartTag const & rhs) const
 187         { return tag_ == rhs.tag_; }
 188         ///
 189         virtual bool operator!=(StartTag const & rhs) const
 190         { return !(*this == rhs); }
 191         ///
 192         virtual bool operator==(FontTag const & rhs) const;
 193         ///
 194         docstring tag_;
 195         ///
 196         docstring attr_;
 197         /// whether to keep things like "<tag></tag>" or discard them
 198         /// you would want this for td, e.g, but maybe not for a div
 199         bool keepempty_;
 200 };
 201
 202
 203 ///
 204 struct EndTag
 205 {
 206         ///
 207         explicit EndTag(std::string tag) : tag_(from_ascii(tag)) {}
 208         ///
 209         explicit EndTag(docstring tag) : tag_(tag) {}
 210         ///
 211         virtual ~EndTag() {}
 212         /// </tag_>
 213         virtual docstring writeEndTag() const;
 214         ///
 215         bool operator==(StartTag const & rhs) const
 216         { return tag_ == rhs.tag_; }
 217         ///
 218         bool operator!=(StartTag const & rhs) const
 219         { return !(*this == rhs); }
 220         ///
 221         virtual EndFontTag const * asFontTag() const { return 0; }
 222         ///
 223         docstring tag_;
 224 };
 225
 226
 227 /// Tags like <img />
 228 /// Attributes will be escaped automatically and so should NOT
 229 /// be escaped before being passed to the constructor.
 230 struct CompTag
 231 {
 232         ///
 233         explicit CompTag(std::string const & tag)
 234                         : tag_(tag) {}
 235         ///
 236         explicit CompTag(std::string const & tag, std::string const & attr)
 237                         : tag_(tag), attr_(attr) {}
 238         /// <tag_ attr_ />
 239         docstring writeTag() const;
 240         ///
 241         std::string tag_;
 242         ///
 243         std::string attr_;
 244 };
 245
 246
 247 /// A special case of StartTag, used exclusively for tags that wrap paragraphs.
 248 /// parid is only used for HTML output; XML is supposed to use attr for this.
 249 struct ParTag : public StartTag
 250 {
 251         ///
 252         explicit ParTag(std::string const & tag, const std::string & attr): StartTag(tag, from_utf8(attr)) {}
 253         ///
 254         ~ParTag() {}
 255 };
 256
 257
 258 ///
 259 enum FontTypes {
 260         // ranges
 261         FT_EMPH,
 262         FT_NOUN,
 263         FT_UBAR,
 264         FT_DBAR,
 265         FT_WAVE,
 266         FT_SOUT,
 267         FT_XOUT,
 268         // bold
 269         FT_BOLD,
 270         // shapes
 271         FT_UPRIGHT,
 272         FT_ITALIC,
 273         FT_SLANTED,
 274         FT_SMALLCAPS,
 275         // families
 276         FT_ROMAN,
 277         FT_SANS,
 278         FT_TYPE,
 279         // sizes
 280         FT_SIZE_TINY,
 281         FT_SIZE_SCRIPT,
 282         FT_SIZE_FOOTNOTE,
 283         FT_SIZE_SMALL,
 284         FT_SIZE_NORMAL,
 285         FT_SIZE_LARGE,
 286         FT_SIZE_LARGER,
 287         FT_SIZE_LARGEST,
 288         FT_SIZE_HUGE,
 289         FT_SIZE_HUGER,
 290         FT_SIZE_INCREASE,
 291         FT_SIZE_DECREASE
 292
 293         // When updating this list, also update fontToTag in both output_docbook.cpp and output_xhtml.cpp,
 294         // fontToRole in output_docbook.cpp, and fontToAttribute in output_xhtml.cpp.
 295 };
 296
 297
 298 ///
 299 struct FontTag : public StartTag
 300 {
 301         ///
 302         FontTag(docstring const & tag, FontTypes type): StartTag(tag), font_type_(type) {}
 303         ///
 304         FontTag(std::string const & tag, FontTypes type): StartTag(from_utf8(tag)), font_type_(type) {}
 305         ///
 306         FontTag(docstring const & tag, docstring const & attr, FontTypes type): StartTag(tag, attr), font_type_(type) {}
 307         ///
 308         FontTag(std::string const & tag, std::string const & attr, FontTypes type): StartTag(from_utf8(tag), from_utf8(attr)), font_type_(type) {}
 309         ///
 310         FontTag const * asFontTag() const override { return this; }
 311         ///
 312         bool operator==(StartTag const &) const override;
 313         ///
 314         FontTypes font_type_;
 315 };
 316
 317
 318 ///
 319 struct EndFontTag : public EndTag
 320 {
 321         ///
 322         EndFontTag(docstring const & tag, FontTypes type): EndTag(tag), font_type_(type) {}
 323         ///
 324         EndFontTag(std::string const & tag, FontTypes type): EndTag(from_utf8(tag)), font_type_(type) {}
 325         ///
 326         EndFontTag const * asFontTag() const override { return this; }
 327         ///
 328         FontTypes font_type_;
 329 };
 330
 331
 332 // trivial struct for output of newlines
 333 struct CR{};
 334
 335 // an illegal tag for internal use
 336 xml::StartTag const parsep_tag("&LyX_parsep_tag&");
 337
 338 /// Open tag
 339 void openTag(odocstream & os, std::string const & name,
 340              std::string const & attribute = std::string());
 341
 342 /// Open tag
 343 void openTag(Buffer const & buf, odocstream & os,
 344              OutputParams const & runparams, Paragraph const & par);
 345
 346 /// Close tag
 347 void closeTag(odocstream & os, std::string const & name);
 348
 349 /// Close tag
 350 void closeTag(odocstream & os, Paragraph const & par);
 351
 352 } // namespace xml
 353
 354 } // namespace lyx
 355
 356 #endif // XML_H