/*################################################################################### # # # HTMLNode.h # # # # Copyright © 2011-2013 by Stefan Klieme # # # # Objective-C wrapper for HTML parser of libxml2 # # # # Version 1.6 - 29. Sep 2013 # # # # usage: add libxml2.dylib to frameworks # # add $SDKROOT/usr/include/libxml2 to target -> Header Search Paths # # add -lxml2 to target -> other linker flags # # # #################################################################################### # # # Permission is hereby granted, free of charge, to any person obtaining a copy of # # this software and associated documentation files (the "Software"), to deal # # in the Software without restriction, including without limitation the rights # # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies # # of the Software, and to permit persons to whom the Software is furnished to do # # so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,# # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR # # IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # # # ###################################################################################*/ #import #import #import #define kClassKey @"class" #define kIdKey @"id" // ARCMacros by John Blanco // added a macro for computed readonly properties which return always autoreleased objects #if __has_feature(objc_arc) #define SAFE_ARC_PROP_RETAIN strong #define SAFE_ARC_READONLY_OBJ_PROP unsafe_unretained, readonly #define SAFE_ARC_RELEASE(x) #define SAFE_ARC_AUTORELEASE(x) (x) #define SAFE_ARC_SUPER_DEALLOC() #else #define SAFE_ARC_PROP_RETAIN retain #define SAFE_ARC_READONLY_OBJ_PROP readonly #define SAFE_ARC_RELEASE(x) ([(x) release]) #define SAFE_ARC_AUTORELEASE(x) ([(x) autorelease]) #define SAFE_ARC_SUPER_DEALLOC() ([super dealloc]) #endif #if __has_feature(objc_instancetype) #define INSTANCETYPE_OR_ID instancetype #else #define INSTANCETYPE_OR_ID id #endif @interface HTMLNode : NSObject { NSError *xpathError; xmlNode * xmlNode_; } /*! An XPath error*/ @property (SAFE_ARC_PROP_RETAIN) NSError *xpathError; #pragma mark - init methods #pragma mark class // Returns a HTMLNode object initialized with a xml node pointer of xmllib /*! Returns an HTMLNode object with a specified xmlNode pointer. * \param xmlNode The xmlNode pointer for the created node object * \returns An HTMLNode object */ + (HTMLNode *)nodeWithXMLNode:(xmlNode *)xmlNode; // convenience initializer #pragma mark instance /*! Initializes and returns a newly allocated HTMLNode object with a specified xmlNode pointer. * \param xmlNode The xmlNode pointer for the created node object * \returns An initizlized HTMLNode object or nil if the object couldn't be created */ - (INSTANCETYPE_OR_ID)initWithXMLNode:(xmlNode *)xmlNode; #pragma mark - navigation // Node navigation relative to current node (self) /*! The parent node * \returns The parent node or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) HTMLNode *parent; /*! The next sibling node * \returns The next sibling node or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) HTMLNode *nextSibling; /*! The previous sibling node * \returns The previous sibling or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) HTMLNode *previousSibling; /*! The first child node * \returns The first child or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) HTMLNode *firstChild; /*! The last child node * \returns The last child or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) HTMLNode *lastChild; /*! The first level of children * \returns The children array or an empty array */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSArray *children; /*! The number of children*/ @property (readonly) NSUInteger childCount; /*! The child node at specified index * \param index The specified index * \returns The child node or nil if the index is invalid */ - (HTMLNode *)childAtIndex:(NSUInteger)index; // Remove Node - (void)remove; #pragma mark - attributes and values of current node (self) /*! The attribute value of a node matching a given name * \param attributeName A name of an attribute * \returns The attribute value or nil if the attribute could not be found */ - (void)setAttributeForName:(NSString *)attributeName value:(NSString *)value; - (NSString *)attributeForName:(NSString *)attributeName; /*! All attributes and values as dictionary * \returns a dictionary which could be empty if there are no attributes. Returns nil if the node is nil or is document node */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSDictionary *attributes; /*! The tag name * \returns The tag name or nil if the node is document node */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *tagName; /*! The value for the class attribute*/ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *className; /*! The value for the href attribute*/ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *idName; // Returns the value for the href attribute @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *hrefValue; /*! The value for the src attribute*/ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *srcValue; /*! The integer value*/ @property (readonly) NSInteger integerValue; /*! The double value*/ @property (readonly) double doubleValue; /*! Returns the double value of the string value for a specified locale identifier * \param identifier A locale identifier. The locale identifier must conform to http://www.iso.org/iso/country_names_and_code_elements and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes * \returns The double value of the string value depending on the parameter */ - (double )doubleValueForLocaleIdentifier:(NSString *)identifier; /*! Returns the double value of the string value for a specified locale identifier considering a plus sign prefix * \param identifier A locale identifier. The locale identifier must conform to http://www.iso.org/iso/country_names_and_code_elements and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes * \param flag Considers the plus sign in the string if YES * \returns The double value of the string value depending on the parameters */ - (double )doubleValueForLocaleIdentifier:(NSString *)identifier consideringPlusSign:(BOOL)flag; /*! Returns the double value of the text content for a specified locale identifier * \param identifier A locale identifier. The locale identifier must conform to http://www.iso.org/iso/country_names_and_code_elements and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes * \returns The double value of the text content depending on the parameter */ - (double )contentDoubleValueForLocaleIdentifier:(NSString *)identifier; /*! Returns the double value of the text content for a specified locale identifier considering a plus sign prefix * \param identifier A locale identifier. The locale identifier must conform to http://www.iso.org/iso/country_names_and_code_elements and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes * \param flag Considers the plus sign in the string if YES * \returns The double value of the text content depending on the parameters */ - (double )contentDoubleValueForLocaleIdentifier:(NSString *)identifier consideringPlusSign:(BOOL)flag; /*! Returns the date value of the string value for a specified date format and time zone * \param dateFormat A date format string. The date format must conform to http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns * \param timeZone A time zone * \returns The date value of the string value depending on the parameters */ - (NSDate *)dateValueForFormat:(NSString *)dateFormat timeZone:(NSTimeZone *)timeZone; /*! Returns the date value of the text content for a specified date format and time zone * \param dateFormat A date format string. The date format must conform to http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns * \param timeZone A time zone * \returns The date value of the text content depending on the parameters */ - (NSDate *)contentDateValueForFormat:(NSString *)dateFormat timeZone:(NSTimeZone *)timeZone; /*! Returns the date value of the string value for a specified date format * \param dateFormat A date format string. The date format must conform to http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns * \returns The date value of the string value depending on the parameter */ - (NSDate *)dateValueForFormat:(NSString *)dateFormat; /*! Returns the date value of the text content for a specified date format * \param dateFormat A date format string. The date format must conform to http://unicode.org/reports/tr35/tr35-10.html#Date_Format_Patterns * \returns The date value of the text content depending on the parameter */ - (NSDate *)contentDateValueForFormat:(NSString *)dateFormat; /*! The raw string * \returns The raw string value or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *rawStringValue; /*! The string value of a node trimmed by whitespace and newline characters * \returns The string value or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *stringValue; /*! The string value of a node trimmed by whitespace and newline characters and collapsing all multiple occurrences of whitespace and newline characters within the string into a single space * \returns The trimmed and collapsed string value or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *stringValueCollapsingWhitespace; /*! The raw html text dump * \returns The raw html text dump or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *HTMLString; /*! The array of all text content of children * \returns The text content array - each array item is trimmed by whitespace and newline characters - or an empty array */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSArray *textContentOfChildren; /*! The element type of the node*/ @property (readonly) xmlElementType elementType; /*! Is the node an attribute node*/ @property (readonly) BOOL isAttributeNode; /*! Is the node a document node*/ @property (readonly) BOOL isDocumentNode; /*! Is the node an element node*/ @property (readonly) BOOL isElementNode; /*! Is the node a text node*/ @property (readonly) BOOL isTextNode; #pragma mark - contents of current node and its descendants (descendant-or-self) /*! The raw text content of descendant-or-self * \returns The raw text content of the node and all its descendants or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *rawTextContent; /*! The text content of descendant-or-self trimmed by whitespace and newline characters * \returns The trimmed text content of the node and all its descendants or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *textContent; /*! The text content of descendant-or-self trimmed by whitespace and newline characters and collapsing all multiple occurrences of whitespace and newline characters within the string into a single space * \returns The text content of the node and all its descendants trimmed and collapsed or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *textContentCollapsingWhitespace; /*! The text content of descendant-or-self in an array, each item trimmed by whitespace and newline characters * \returns An array of all text content of the node and its descendants - each array item is trimmed by whitespace and newline characters - or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSArray *textContentOfDescendants; /*! The raw html text dump of descendant-or-self * \returns The raw html text dump of the node and all its descendants or nil */ @property (SAFE_ARC_READONLY_OBJ_PROP) NSString *HTMLContent; #pragma mark - Query method declarations // Note: In the category HTMLNode+XPath all appropriate query methods begin with node instead of descendant /*! Returns the first descendant node with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The first found descendant node or nil if no node matches the parameters */ - (HTMLNode *)descendantWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns the first child node with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The first found child node or nil if no node matches the parameters */ - (HTMLNode *)childWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns the first sibling node with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The first found sibling node or nil if no node matches the parameters */ - (HTMLNode *)siblingWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns the first descendant node with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The first found descendant node or nil if no node matches the parameters */ - (HTMLNode *)descendantWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns the first child node with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The first found child node or nil if no node matches the parameters */ - (HTMLNode *)childWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns the first sibling node with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The first found sibling node or nil if no node matches the parameters */ - (HTMLNode *)siblingWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns all descendant nodes with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns all child nodes with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns all sibling nodes with the specifed attribute name and value matching exactly * \param attributeName The name of the attribute * \param attributeValue The value of the attribute * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsWithAttribute:(NSString *)attributeName valueMatches:(NSString *)attributeValue; /*! Returns all descendant nodes with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns all child nodes with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns all sibling nodes with the specifed attribute name and the value contains the specified attribute value * \param attributeName The name of the attribute * \param attributeValue The partial string of the attribute value * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsWithAttribute:(NSString *)attributeName valueContains:(NSString *)attributeValue; /*! Returns the first descendant node with the specifed attribute name * \param attributeName The name of the attribute * \returns The first found descendant node or nil */ - (HTMLNode *)descendantWithAttribute:(NSString *)attributeName; /*! Returns the first child node with the specifed attribute name * \param attributeName The name of the attribute * \returns The first found child node or nil */ - (HTMLNode *)childWithAttribute:(NSString *)attributeName; /*! Returns the first sibling node with the specifed attribute name * \param attributeName The name of the attribute * \returns The first found sibling node or nil */ - (HTMLNode *)siblingWithAttribute:(NSString *)attributeName; /*! Returns all descendant nodes with the specifed attribute name * \param attributeName The name of the attribute * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsWithAttribute:(NSString *)attributeName; /*! Returns all child nodes with the specifed attribute name * \param attributeName The name of the attribute * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenWithAttribute:(NSString *)attributeName; /*! Returns all sibling nodes with the specifed attribute name * \param attributeName The name of the attribute * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsWithAttribute:(NSString *)attributeName; /*! Returns the first descendant node with the specifed class name * \param classValue The name of the class * \returns The first found descendant node or nil */ - (HTMLNode *)descendantWithClass:(NSString *)classValue; /*! Returns the first child node with the specifed class name * \param classValue The name of the class * \returns The first found child node or nil */ - (HTMLNode *)childWithClass:(NSString *)classValue; /*! Returns the first sibling node with the specifed class name * \param classValue The name of the class * \returns The first found sibling node or nil */ - (HTMLNode *)siblingWithClass:(NSString *)classValue; /*! Returns all descendant nodes with the specifed class name * \param classValue The name of the class * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsWithClass:(NSString *)classValue; /*! Returns all child nodes with the specifed class name * \param classValue The name of the class * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenWithClass:(NSString *)classValue; /*! Returns all sibling nodes with the specifed class name * \param classValue The name of the class * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsWithClass:(NSString *)classValue; /*! Returns the first descendant node with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The first found descendant node or nil if no node matches the parameters */ - (HTMLNode *)descendantOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns the first child node with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The first found child node or nil if no node matches the parameters */ - (HTMLNode *)childOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns the first sibling node with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The first found sibling node or nil if no node matches the parameters */ - (HTMLNode *)siblingOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns all descendant nodes with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns all child nodes with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns all sibling nodes with the specifed tag name and string value matching exactly * \param tagName The name of the tag * \param value The string value of the tag * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsOfTag:(NSString *)tagName valueMatches:(NSString *)value; /*! Returns the first descendant node with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The first found descendant node or nil if no node matches the parameters */ - (HTMLNode *)descendantOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns the child node with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The first found child node or nil if no node matches the parameters */ - (HTMLNode *)childOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns the sibling node with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The first found sibling node or nil if no node matches the parameters */ - (HTMLNode *)siblingOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns all descendant nodes with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns all child nodes with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns all sibling nodes with the specifed attribute name and the string value contains the specified value * \param tagName The name of the attribute * \param value The partial string of the attribute value * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsOfTag:(NSString *)tagName valueContains:(NSString *)value; /*! Returns the first descendant node with the specifed tag name * \param tagName The name of the tag * \returns The first found descendant node or nil */ - (HTMLNode *)descendantOfTag:(NSString *)tagName; /*! Returns the first child node with the specifed tag name * \param tagName The name of the tag * \returns The first found child node or nil */ - (HTMLNode *)childOfTag:(NSString *)tagName; /*! Returns the first sibling node with the specifed tag name * \param tagName The name of the tag * \returns The first found sibling node or nil */ - (HTMLNode *)siblingOfTag:(NSString *)tagName; /*! Returns all descendant nodes with the specifed tag name * \param tagName The name of the tag * \returns The array of all found descendant nodes or an empty array */ - (NSArray *)descendantsOfTag:(NSString *)tagName; /*! Returns all child nodes with the specifed tag name * \param tagName The name of the tag * \returns The array of all found child nodes or an empty array */ - (NSArray *)childrenOfTag:(NSString *)tagName; /*! Returns all sibling nodes with the specifed tag name * \param tagName The name of the tag * \returns The array of all found sibling nodes or an empty array */ - (NSArray *)siblingsOfTag:(NSString *)tagName; @end