1 // Copyright 2015 The Weave Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef LIBWEAVE_SRC_NOTIFICATION_XML_NODE_H_ 6 #define LIBWEAVE_SRC_NOTIFICATION_XML_NODE_H_ 7 8 #include <map> 9 #include <memory> 10 #include <string> 11 #include <vector> 12 13 #include <base/macros.h> 14 15 namespace weave { 16 17 class XmlNodeTest; 18 class XmppStreamParser; 19 20 // XmlNode is a very simple class to represent the XML document element tree. 21 // It is used in conjunction with expat XML parser to implement XmppStreamParser 22 // class used to parse Xmpp data stream into individual stanzas. 23 class XmlNode final { 24 public: 25 XmlNode(const std::string& name, 26 std::map<std::string, std::string> attributes); 27 28 // The node's name. E.g. in <foo bar="baz">quux</foo> this will return "foo". 29 const std::string& name() const; 30 // The node text content. E.g. in <foo bar="baz">quux</foo> this will return 31 // "quux". 32 const std::string& text() const; 33 // The node attribute map. E.g. in <foo bar="baz">quux</foo> this will return 34 // {{"bar", "baz"}}. 35 const std::map<std::string, std::string>& attributes() const; 36 // Returns the list of child nodes, if any. 37 const std::vector<std::unique_ptr<XmlNode>>& children() const; 38 39 // Retrieves the value of the given attribute specified by |name|. 40 // If the attribute doesn't exist, returns false and |value| is not modified. 41 bool GetAttribute(const std::string& name, std::string* value) const; 42 // Returns the value of the given attribute specified by |name|. 43 // Returns empty string if the attribute does not exist. This method should be 44 // used only in limited scopes such as unit tests. 45 std::string GetAttributeOrEmpty(const std::string& name) const; 46 47 // Finds a first occurrence of a child node specified by |name_path|. A name 48 // path is a "/"-separated list of node names to look for. If |recursive| is 49 // set to true, the children are recursively traversed trying to match the 50 // node names. Otherwise only first-level children of the current node are 51 // matched against the top-level name of |name_path|. 52 // This method returns a pointer to the first node that matches the path, 53 // otherwise a nullptr is returned. 54 const XmlNode* FindFirstChild(const std::string& name_path, 55 bool recursive) const; 56 57 // Finds all the child nodes matching the |name_path|. This returns the list 58 // of pointers to the child nodes matching the criteria. If |recursive| is 59 // set to true, the children are recursively traversed trying to match the 60 // node names. Otherwise only first-level children of the current node are 61 // matched against the top-level name of |name_path|. 62 // For example, if the current node represents the <top> element of the 63 // following XML document: 64 // <top> 65 // <node1 id="1"><node2 id="2"><node3 id="3"/></node2></node1> 66 // <node2 id="4"><node3 id="5"/></node2> 67 // <node3 id="6"/> 68 // <node2 id="7"><node4 id="8"><node3 id="9"/></node4></node2> 69 // </top> 70 // Then recursively searching for nodes will produce the following results 71 // (only the node "id" attributes are listed in the results, for brevity): 72 // FindChildren("node2/node3", false) -> {"5"}. 73 // FindChildren("node2/node3", true) -> {"3", "5"}. 74 // FindChildren("node3", false) -> {"6"}. 75 // FindChildren("node3", true) -> {"3", "5", "6", "9"}. 76 std::vector<const XmlNode*> FindChildren(const std::string& name_path, 77 bool recursive) const; 78 79 // Adds a new child to the bottom of the child list of this node. 80 void AddChild(std::unique_ptr<XmlNode> child); 81 82 // Converts the node tree to XML-like string. Note that this not necessarily 83 // produces a valid XML string. It does not use any character escaping or 84 // canonicalization, which will produce invalid XML if any of the node or 85 // attribute names or values contain special characters such as ", <, >, etc. 86 // This function should be used only for logging/debugging purposes only and 87 // never to generate valid XML from the parsed node tree. 88 std::string ToString() const; 89 90 private: 91 friend class XmlNodeTest; 92 friend class XmppStreamParser; 93 94 // Sets the node's text. Used by XML parser. 95 void SetText(const std::string& text); 96 // Appends the |text| to the node's text string. 97 void AppendText(const std::string& text); 98 99 // Helper method used by FindFirstChild() and FindChildren(). Searches for 100 // child node(s) matching |name_path|. 101 // If |children| is not specified (nullptr), this function find the first 102 // matching node and returns it via return value of the function. If no match 103 // is found, this function will return nullptr. 104 // If |children| parameter is not nullptr, found nodes are added to the 105 // vector pointed to by |children| and search continues until the whole tree 106 // is inspected. In this mode, the function always returns nullptr. 107 const XmlNode* FindChildHelper(const std::string& name_path, 108 bool recursive, 109 std::vector<const XmlNode*>* children) const; 110 111 const XmlNode* parent_{nullptr}; // Weak pointer to the parent node, if any. 112 std::string name_; 113 std::string text_; 114 std::map<std::string, std::string> attributes_; 115 std::vector<std::unique_ptr<XmlNode>> children_; 116 117 DISALLOW_COPY_AND_ASSIGN(XmlNode); 118 }; 119 120 } // namespace weave 121 122 #endif // LIBWEAVE_SRC_NOTIFICATION_XML_NODE_H_ 123