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     virtual ~wxMarkupParserOutput() { }
  82
  83     // Virtual functions called by wxMarkupParser while parsing the markup.
  84
  85     // Called for a run of normal text.
  86     virtual void OnText(const wxString& text) = 0;
  87
  88     // These functions correspond to the simple tags without parameters.
  89     virtual void OnBoldStart() = 0;
  90     virtual void OnBoldEnd() = 0;
  91
  92     virtual void OnItalicStart() = 0;
  93     virtual void OnItalicEnd() = 0;
  94
  95     virtual void OnUnderlinedStart() = 0;
  96     virtual void OnUnderlinedEnd() = 0;
  97
  98     virtual void OnStrikethroughStart() = 0;
  99     virtual void OnStrikethroughEnd() = 0;
 100
 101     virtual void OnBigStart() = 0;
 102     virtual void OnBigEnd() = 0;
 103
 104     virtual void OnSmallStart() = 0;
 105     virtual void OnSmallEnd() = 0;
 106
 107     virtual void OnTeletypeStart() = 0;
 108     virtual void OnTeletypeEnd() = 0;
 109
 110     // The generic span start and end functions.
 111     virtual void OnSpanStart(const wxMarkupSpanAttributes& attrs) = 0;
 112     virtual void OnSpanEnd(const wxMarkupSpanAttributes& attrs) = 0;
 113
 114 private:
 115     wxDECLARE_NO_COPY_CLASS(wxMarkupParserOutput);
 116 };
 117
 118 // ----------------------------------------------------------------------------
 119 // wxMarkupParser: parses the given markup text into wxMarkupParserOutput.
 120 // ----------------------------------------------------------------------------
 121
 122 class WXDLLIMPEXP_CORE wxMarkupParser
 123 {
 124 public:
 125     // Initialize the parser with the object that will receive parsing results.
 126     // This object lifetime must be greater than ours.
 127     explicit wxMarkupParser(wxMarkupParserOutput& output)
 128         : m_output(output)
 129     {
 130     }
 131
 132     // Parse the entire string and call wxMarkupParserOutput methods.
 133     //
 134     // Return true if the string was successfully parsed or false if it failed
 135     // (presumably because of syntax errors in the markup).
 136     bool Parse(const wxString& text);
 137
 138     // Quote a normal string, not meant to be interpreted as markup, so that it
 139     // produces the same string when parsed as markup. This means, for example,
 140     // replacing '<' in the input string with "&lt;" to prevent them from being
 141     // interpreted as tag opening characters.
 142     static wxString Quote(const wxString& text);
 143
 144     // Strip markup from a string, i.e. simply remove all tags and replace
 145     // XML entities with their values (or with "&&" in case of "&amp;" to
 146     // prevent it from being interpreted as mnemonic marker).
 147     static wxString Strip(const wxString& text);
 148
 149 private:
 150     // Simple struct combining the name of a tag and its attributes.
 151     struct TagAndAttrs
 152     {
 153         TagAndAttrs(const wxString& name_) : name(name_) { }
 154
 155         wxString name;
 156         wxMarkupSpanAttributes attrs;
 157     };
 158
 159     // Call the wxMarkupParserOutput method corresponding to the given tag.
 160     //
 161     // Return false if the tag doesn't match any of the known ones.
 162     bool OutputTag(const TagAndAttrs& tagAndAttrs, bool start);
 163
 164     // Parse the attributes and fill the provided TagAndAttrs object with the
 165     // information about them. Does nothing if attrs string is empty.
 166     //
 167     // Returns empty string on success of a [fragment of an] error message if
 168     // we failed to parse the attributes.
 169     wxString ParseAttrs(wxString attrs, TagAndAttrs& tagAndAttrs);
 170
 171
 172     wxMarkupParserOutput& m_output;
 173
 174     wxDECLARE_NO_COPY_CLASS(wxMarkupParser);
 175 };
 176
 177 #endif // _WX_PRIVATE_MARKUPPARSER_H_