include/wx/private/markupparser.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/private/markupparser.h
   3 // Purpose:     Classes for parsing simple markup.
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-02-16
   6 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_PRIVATE_MARKUPPARSER_H_
  11 #define _WX_PRIVATE_MARKUPPARSER_H_
  12
  13 #include "wx/string.h"
  14
  15 // ----------------------------------------------------------------------------
  16 // wxMarkupSpanAttributes: information about attributes for a markup span.
  17 // ----------------------------------------------------------------------------
  18
  19 struct wxMarkupSpanAttributes
  20 {
  21     enum OptionalBool
  22     {
  23         Unspecified = -1,
  24         No,
  25         Yes
  26     };
  27
  28     wxMarkupSpanAttributes()
  29     {
  30         m_sizeKind = Size_Unspecified;
  31
  32         m_isBold =
  33         m_isItalic =
  34         m_isUnderlined =
  35         m_isStrikethrough = Unspecified;
  36     }
  37
  38     // If a string is empty, it means that the corresponding attribute is not
  39     // set.
  40     wxString m_fgCol,
  41              m_bgCol,
  42              m_fontFace;
  43
  44     // There are many ways of specifying the size. First of all, the size may
  45     // be relative in which case m_fontSize is either -1 or +1 meaning that
  46     // it's one step smaller or larger than the current font. Second, it may be
  47     // absolute in which case m_fontSize contains either the size in 1024th of
  48     // a point (Pango convention) or its values are in [-3, 3] interval and map
  49     // to [xx-small, xx-large] CSS-like font size specification. And finally it
  50     // may be not specified at all, of course, in which case the value of
  51     // m_fontSize doesn't matter and it shouldn't be used.
  52     enum
  53     {
  54         Size_Unspecified,
  55         Size_Relative,
  56         Size_Symbolic,
  57         Size_PointParts
  58     } m_sizeKind;
  59     int m_fontSize;
  60
  61     // If the value is Unspecified, the attribute wasn't given.
  62     OptionalBool m_isBold,
  63                  m_isItalic,
  64                  m_isUnderlined,
  65                  m_isStrikethrough;
  66 };
  67
  68 // ----------------------------------------------------------------------------
  69 // wxMarkupParserOutput: gathers the results of parsing markup.
  70 // ----------------------------------------------------------------------------
  71
  72 // A class deriving directly from this one needs to implement all the pure
  73 // virtual functions below but as the handling of all simple tags (bold, italic
  74 // &c) is often very similar, it is usually more convenient to inherit from
  75 // wxMarkupParserFontOutput defined in wx/private/markupparserfont.h instead.
  76 class wxMarkupParserOutput
  77 {
  78 public:
  79     wxMarkupParserOutput() { }
  80     virtual ~wxMarkupParserOutput() { }
  81
  82     // Virtual functions called by wxMarkupParser while parsing the markup.
  83
  84     // Called for a run of normal text.
  85     virtual void OnText(const wxString& text) = 0;
  86
  87     // These functions correspond to the simple tags without parameters.
  88     virtual void OnBoldStart() = 0;
  89     virtual void OnBoldEnd() = 0;
  90
  91     virtual void OnItalicStart() = 0;
  92     virtual void OnItalicEnd() = 0;
  93
  94     virtual void OnUnderlinedStart() = 0;
  95     virtual void OnUnderlinedEnd() = 0;
  96
  97     virtual void OnStrikethroughStart() = 0;
  98     virtual void OnStrikethroughEnd() = 0;
  99
 100     virtual void OnBigStart() = 0;
 101     virtual void OnBigEnd() = 0;
 102
 103     virtual void OnSmallStart() = 0;
 104     virtual void OnSmallEnd() = 0;
 105
 106     virtual void OnTeletypeStart() = 0;
 107     virtual void OnTeletypeEnd() = 0;
 108
 109     // The generic span start and end functions.
 110     virtual void OnSpanStart(const wxMarkupSpanAttributes& attrs) = 0;
 111     virtual void OnSpanEnd(const wxMarkupSpanAttributes& attrs) = 0;
 112
 113 private:
 114     wxDECLARE_NO_COPY_CLASS(wxMarkupParserOutput);
 115 };
 116
 117 // ----------------------------------------------------------------------------
 118 // wxMarkupParser: parses the given markup text into wxMarkupParserOutput.
 119 // ----------------------------------------------------------------------------
 120
 121 class WXDLLIMPEXP_CORE wxMarkupParser
 122 {
 123 public:
 124     // Initialize the parser with the object that will receive parsing results.
 125     // This object lifetime must be greater than ours.
 126     explicit wxMarkupParser(wxMarkupParserOutput& output)
 127         : m_output(output)
 128     {
 129     }
 130
 131     // Parse the entire string and call wxMarkupParserOutput methods.
 132     //
 133     // Return true if the string was successfully parsed or false if it failed
 134     // (presumably because of syntax errors in the markup).
 135     bool Parse(const wxString& text);
 136
 137     // Quote a normal string, not meant to be interpreted as markup, so that it
 138     // produces the same string when parsed as markup. This means, for example,
 139     // replacing '<' in the input string with "&lt;" to prevent them from being
 140     // interpreted as tag opening characters.
 141     static wxString Quote(const wxString& text);
 142
 143     // Strip markup from a string, i.e. simply remove all tags and replace
 144     // XML entities with their values (or with "&&" in case of "&amp;" to
 145     // prevent it from being interpreted as mnemonic marker).
 146     static wxString Strip(const wxString& text);
 147
 148 private:
 149     // Simple struct combining the name of a tag and its attributes.
 150     struct TagAndAttrs
 151     {
 152         TagAndAttrs(const wxString& name_) : name(name_) { }
 153
 154         wxString name;
 155         wxMarkupSpanAttributes attrs;
 156     };
 157
 158     // Call the wxMarkupParserOutput method corresponding to the given tag.
 159     //
 160     // Return false if the tag doesn't match any of the known ones.
 161     bool OutputTag(const TagAndAttrs& tagAndAttrs, bool start);
 162
 163     // Parse the attributes and fill the provided TagAndAttrs object with the
 164     // information about them. Does nothing if attrs string is empty.
 165     //
 166     // Returns empty string on success of a [fragment of an] error message if
 167     // we failed to parse the attributes.
 168     wxString ParseAttrs(wxString attrs, TagAndAttrs& tagAndAttrs);
 169
 170
 171     wxMarkupParserOutput& m_output;
 172
 173     wxDECLARE_NO_COPY_CLASS(wxMarkupParser);
 174 };
 175
 176 #endif // _WX_PRIVATE_MARKUPPARSER_H_