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