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 // A class deriving directly from this one needs to implement all the pure
  74 // virtual functions below but as the handling of all simple tags (bold, italic
  75 // &c) is often very similar, it is usually more convenient to inherit from
  76 // wxMarkupParserFontOutput defined in wx/private/markupparserfont.h instead.
  77 class wxMarkupParserOutput
  78 {
  79 public:
  80     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_