1 #ifndef IMAGE_IO_XML_XML_HANDLER_H_ // NOLINT 2 #define IMAGE_IO_XML_XML_HANDLER_H_ // NOLINT 3 4 #include "image_io/base/data_match_result.h" 5 #include "image_io/xml/xml_token_context.h" 6 7 namespace photos_editing_formats { 8 namespace image_io { 9 10 /// The handler that is called by XmlRule instances as they parse XML syntax 11 /// and produce tokens defined in the XmlTokenContext. Each handler function 12 /// may be called multiple times with different XmlPortion values. The first 13 /// time the XmlPortion::kBegin bit will be set. The last time, XmlPortion::kEnd 14 /// will be set. In between, XmlPortion::kMiddle will be set. If the entire 15 /// token value is available for the handler, all three bits will be set. 16 /// The implementation of each function in this base class returns the 17 /// DataMatchResult value that the context provides. The function overrides in 18 /// subclasses can return the same context value, or a copy that is modified 19 /// with a different result type, message and "can continue" flag. 20 class XmlHandler { 21 public: 22 virtual ~XmlHandler() = default; 23 24 /// This function is called to start an XML element. Once started, any of 25 /// the other handler functions may be called. 26 /// @param context The token context used to specify the element name. 27 /// @return The match result from the context, or one that is modified to 28 /// contain an error message if needed. 29 virtual DataMatchResult StartElement(const XmlTokenContext& context); 30 31 /// This function is called to finish an XML element. Each call to this 32 /// function should be paired with a call to a StartElement function. 33 /// @param context The token context used to obtain the match result for 34 /// returning. For this function, the context might not have a valid token 35 /// value: the XmlPortion will always be kNone and the token range invalid. 36 /// This is the case if the syntax parsed is an empty element like this: 37 /// "<SomeElement [Attribute=Name]... />". For non empty elements with syntax: 38 /// "<SomeElement>...</SomeElement>", the value will be the element name. 39 /// @return The match result from the context, or one that is modified to 40 /// contain an error message if needed. 41 virtual DataMatchResult FinishElement(const XmlTokenContext& context); 42 43 /// This function is called to define an attribute name. This function will 44 /// never be called unless an element has been started with a prior call to 45 /// the StartElement() function. 46 /// @param context The token context used to specify the attribute name. 47 /// @return The match result from the context, or one that is modified to 48 /// contain an error message if needed. 49 virtual DataMatchResult AttributeName(const XmlTokenContext& context); 50 51 /// This function is called to define an attribute value. The token value 52 /// passed to this function always includes the quote marks at the begin and 53 /// end of the token value. The quote marks always match and may be either a 54 /// single quote (') or a double quote ("). Sometimes attribute values can be 55 /// very long, so implementations of this function should use care if they 56 /// retain the value as a string for later processing. This function will 57 /// never be called unless an element has been started with a prior call to 58 /// the StartElement() and AttributeName() functions. 59 /// @param context The token context used to specify the attribute value. 60 /// @return The match result from the context, or one that is modified to 61 /// contain an error message if needed. 62 virtual DataMatchResult AttributeValue(const XmlTokenContext& context); 63 64 /// This function is called to define a block of characters in the body of 65 /// an element. This function may be called multiple times for a given 66 /// element. Handlers that are interested in the character content for an 67 /// element should concatenate the token values from all calls to obtain the 68 /// full value for the element. 69 /// @param context The token context used to specify the content value. 70 /// @return The match result from the context, or one that is modified to 71 /// contain an error message if needed. 72 virtual DataMatchResult ElementContent(const XmlTokenContext& context); 73 74 /// This function is called to inform the handler of a comment. A comment in 75 /// XML has the syntax "<!--...-->". In order to simplify the XML parsing 76 /// task, the tokens passed to this function never include the leading "<!--" 77 /// characters, but always include the trailing "-->". 78 /// @param context The token context used to specify the comment. 79 /// @return The match result from the context, or one that is modified to 80 /// contain an error message if needed. 81 virtual DataMatchResult Comment(const XmlTokenContext& context); 82 83 /// This function is called to inform the handler CDATA block. A CDATA block 84 /// in XML has the syntax "<![CDATA[...]]>". In order to simplify the XML 85 /// parsing task, the tokens passed to this function never include the leading 86 /// "<![CDATA[" characters, but always include the trailing "]]". 87 /// @param context The token context used to specify the CDATA block. 88 /// @return The match result from the context, or one that is modified to 89 /// contain an error message if needed. 90 virtual DataMatchResult Cdata(const XmlTokenContext& context); 91 92 /// This function is called to define a processing instruction. Processing 93 /// instructions have an XML syntax "<?...?>". In order to simplify the XML 94 /// parsing task, no parsing of the processing instruction is done: handlers 95 /// that need the contents parsed are on their own. Also, again to simplify 96 /// the XML parsing task, the tokens passed to this function never include the 97 /// leading "<?" characters, but always include the trailing "?>". 98 /// @param context The token context used to specify the processing data. 99 /// @return The match result from the context, or one that is modified to 100 /// contain an error message if needed. 101 virtual DataMatchResult Pi(const XmlTokenContext& context); 102 }; 103 104 } // namespace image_io 105 } // namespace photos_editing_formats 106 107 #endif // IMAGE_IO_XML_XML_HANDLER_H_ // NOLINT 108