Add source code documentation for node filter, tree walker, namespaces and quirks modes
This commit is contained in:
iska
@@ -6,8 +6,18 @@
|
||||
// Copyright (c) 2014 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
/**
|
||||
HTML Namespaces
|
||||
https://html.spec.whatwg.org/multipage/infrastructure.html#namespaces
|
||||
*/
|
||||
typedef NS_ENUM(NSInteger, HTMLNamespace)
|
||||
{
|
||||
/** The default HTML namespace. */
|
||||
HTMLNamespaceHTML,
|
||||
|
||||
/** The namespace for most of the <math> elements. */
|
||||
HTMLNamespaceMathML,
|
||||
|
||||
/** The namespace for most of the <svg> elements. */
|
||||
HTMLNamespaceSVG
|
||||
};
|
||||
|
||||
@@ -10,6 +10,10 @@
|
||||
|
||||
NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
/**
|
||||
The node filter's value when applied to a given HTML node. The node filter can either accept a node, skip it, or
|
||||
reject it. Rejecting a node means skipping the node itself and all of it descendants.
|
||||
*/
|
||||
typedef NS_ENUM(unsigned short, HTMLNodeFilterValue)
|
||||
{
|
||||
HTMLNodeFilterAccept = 1,
|
||||
@@ -17,6 +21,12 @@ typedef NS_ENUM(unsigned short, HTMLNodeFilterValue)
|
||||
HTMLNodeFilterSkip = 3
|
||||
};
|
||||
|
||||
/**
|
||||
The show options for the HTML node iterator and tree walker.
|
||||
|
||||
@see HTMLNodeIterator
|
||||
@see HTMLTreeWalker
|
||||
*/
|
||||
typedef NS_OPTIONS(unsigned long, HTMLNodeFilterShowOptions)
|
||||
{
|
||||
HTMLNodeFilterShowAll = 0xFFFFFFFF,
|
||||
@@ -33,16 +43,36 @@ typedef NS_OPTIONS(unsigned long, HTMLNodeFilterShowOptions)
|
||||
|
||||
@class HTMLNode;
|
||||
|
||||
/**
|
||||
A HTML Node Filter which can be used with a node iterator or a tree walker.
|
||||
|
||||
@see HTMLNodeIterator
|
||||
@see HTMLTreeWalker
|
||||
*/
|
||||
@protocol HTMLNodeFilter <NSObject>
|
||||
|
||||
@required
|
||||
/**
|
||||
The implementation should return a HTMLNodeFilterValue to indicate accepting, skipping or rejecting a node.
|
||||
|
||||
@param node The node to be filtered.
|
||||
@returns `HTMLNodeFilterAccept` if accepted, `HTMLNodeFilterSkip` if skipped, or `HTMLNodeFilterReject` if rejected.
|
||||
*/
|
||||
- (HTMLNodeFilterValue)acceptNode:(HTMLNode *)node;
|
||||
|
||||
@end
|
||||
|
||||
#pragma mark - Block Filter
|
||||
|
||||
/**
|
||||
A concrete block-based HTML Node Filter implementation.
|
||||
*/
|
||||
@interface HTMLNodeFilterBlock : NSObject <HTMLNodeFilter>
|
||||
|
||||
/**
|
||||
Initializes and returns a new instance of this filter.
|
||||
|
||||
@param block The block to apply on each node to be filtered.
|
||||
*/
|
||||
+ (instancetype)filterWithBlock:(HTMLNodeFilterValue (^)(HTMLNode *node))block;
|
||||
|
||||
@end
|
||||
@@ -51,8 +81,16 @@ typedef NS_OPTIONS(unsigned long, HTMLNodeFilterShowOptions)
|
||||
|
||||
@class CSSSelector;
|
||||
|
||||
/**
|
||||
A concrete css-selector-based HTML Node Filter implementation.
|
||||
*/
|
||||
@interface HTMLSelectorNodeFilter : NSObject <HTMLNodeFilter>
|
||||
|
||||
/**
|
||||
Initializes and returns a new instance of this filter.
|
||||
|
||||
@param selector The selector to apply on each node to be filtered.
|
||||
*/
|
||||
+ (instancetype)filterWithSelector:(CSSSelector *)selector;
|
||||
|
||||
@end
|
||||
|
||||
@@ -13,26 +13,81 @@ NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
@class HTMLNode;
|
||||
|
||||
/**
|
||||
A HTML Node Iterator, which iterates the nodes in the DOM in tree order, i.e. depth-first traversal of the tree.
|
||||
|
||||
https://dom.spec.whatwg.org/#interface-nodeiterator
|
||||
*/
|
||||
@interface HTMLNodeIterator : NSEnumerator
|
||||
|
||||
/**
|
||||
The root element of this iterator, i.e. the traversed tree is rooted at this element.
|
||||
*/
|
||||
@property (nonatomic, strong, readonly) HTMLNode *root;
|
||||
|
||||
/**
|
||||
The current reference node.
|
||||
*/
|
||||
@property (nonatomic, strong, readonly) HTMLNode *referenceNode;
|
||||
|
||||
/**
|
||||
Whether the iterator's pointer is before the reference node.
|
||||
*/
|
||||
@property (nonatomic, assign, readonly) BOOL pointerBeforeReferenceNode;
|
||||
|
||||
/**
|
||||
The iterator's show options. These options control what types of elements are shown or skipped during iteration.
|
||||
|
||||
@see HTMLNodeFilterShowOptions
|
||||
*/
|
||||
@property (nonatomic, assign, readonly) HTMLNodeFilterShowOptions whatToShow;
|
||||
@property (nonatomic, strong, readonly) id<HTMLNodeFilter> filter;
|
||||
|
||||
+ (instancetype)iteratorWithNode:(HTMLNode *)node
|
||||
showOptions:(HTMLNodeFilterShowOptions)showOptions
|
||||
filter:(nullable HTMLNodeFilterValue (^)(HTMLNode *node))filter;
|
||||
/**
|
||||
A node filter, that is applied to each node during iteration.
|
||||
|
||||
@see HTMLNodeFilter
|
||||
*/
|
||||
@property (nonatomic, strong, readonly, nullable) id<HTMLNodeFilter> filter;
|
||||
|
||||
|
||||
/**
|
||||
Initializes a new node iterator with no filter and HTMLNodeFilterShowAll show options.
|
||||
|
||||
@param node The root node.
|
||||
@returns A new instance of a node iterator.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node;
|
||||
|
||||
/**
|
||||
Initializes a new node iterator with HTMLNodeFilterShowAll show options.
|
||||
|
||||
@param node The root node.
|
||||
@param filter The node filter to use.
|
||||
@returns A new instance of a node iterator.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node
|
||||
filter:(nullable id<HTMLNodeFilter>)filter;
|
||||
|
||||
/**
|
||||
Initializes a new node iterator.
|
||||
|
||||
@param node The root node.
|
||||
@param showOptions The show options for the iterator.
|
||||
@param filter The node filter to use.
|
||||
@returns A new instance of a node iterator.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node
|
||||
showOptions:(HTMLNodeFilterShowOptions)showOptions
|
||||
filter:(nullable id<HTMLNodeFilter>)filter;
|
||||
|
||||
/**
|
||||
@returns The next iterated node in tree order, `nil` if there are no more nodes to iterate.
|
||||
*/
|
||||
- (nullable HTMLNode *)nextNode;
|
||||
|
||||
/**
|
||||
@returns The previous iterated node in tree order, `nil` if there are no more nodes to iterate.
|
||||
*/
|
||||
- (nullable HTMLNode *)previousNode;
|
||||
|
||||
@end
|
||||
|
||||
@@ -6,6 +6,10 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import <Foundation/Foundation.h>
|
||||
#import "HTMLNodeFilter.h"
|
||||
|
||||
|
||||
@@ -8,6 +8,10 @@
|
||||
|
||||
#import "NSString+HTMLKit.h"
|
||||
|
||||
/**
|
||||
HTML quirks modes
|
||||
https://html.spec.whatwg.org/multipage/infrastructure.html#quirks-mode
|
||||
*/
|
||||
typedef NS_ENUM(short, HTMLQuirksMode)
|
||||
{
|
||||
HTMLQuirksModeNoQuirks,
|
||||
|
||||
@@ -13,26 +13,102 @@ NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
@class HTMLNode;
|
||||
|
||||
/**
|
||||
A HTML Tree Walker. Used to "walk" the DOM tree in all directions, i.e. it can traverse from a given node to its parent,
|
||||
child, next, or previous sibling.
|
||||
|
||||
https://dom.spec.whatwg.org/#interface-treewalker
|
||||
*/
|
||||
@interface HTMLTreeWalker : NSObject
|
||||
|
||||
/**
|
||||
The root element of this tree walker, i.e. the traversed tree is rooted at this element.
|
||||
*/
|
||||
@property (nonatomic, strong, readonly) HTMLNode *root;
|
||||
|
||||
/**
|
||||
The iterator's show options. These options control what types of elements are shown or skipped during tree walking.
|
||||
|
||||
@see HTMLNodeFilterShowOptions
|
||||
*/
|
||||
@property (nonatomic, assign, readonly) HTMLNodeFilterShowOptions whatToShow;
|
||||
|
||||
/**
|
||||
A node filter, that is applied to each node during tree walking.
|
||||
|
||||
@see HTMLNodeFilter
|
||||
*/
|
||||
@property (nonatomic, strong, readonly, nullable) id<HTMLNodeFilter> filter;
|
||||
|
||||
/**
|
||||
The current node at which this walker is standing.
|
||||
*/
|
||||
@property (nonatomic, strong) HTMLNode *currentNode;
|
||||
|
||||
/**
|
||||
Initializes a new tree walker with no filter and HTMLNodeFilterShowAll show options.
|
||||
|
||||
@param node The root node.
|
||||
@param filter The node filter to use.
|
||||
@returns A new instance of a tree walker.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node;
|
||||
|
||||
/**
|
||||
Initializes a new tree walker with HTMLNodeFilterShowAll show options.
|
||||
|
||||
@param node The root node.
|
||||
@param filter The node filter to use.
|
||||
@returns A new instance of a tree walker.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node
|
||||
filter:(nullable id<HTMLNodeFilter>)filter;
|
||||
|
||||
/**
|
||||
Initializes a new tree walker.
|
||||
|
||||
@param node The root node.
|
||||
@param showOptions The show options for the walker.
|
||||
@param filter The node filter to use.
|
||||
@returns A new instance of a tree walker.
|
||||
*/
|
||||
- (instancetype)initWithNode:(HTMLNode *)node
|
||||
showOptions:(HTMLNodeFilterShowOptions)showOptions
|
||||
filter:(nullable id<HTMLNodeFilter>)filter;
|
||||
|
||||
/**
|
||||
The parent node of the current node.
|
||||
*/
|
||||
- (nullable HTMLNode *)parentNode;
|
||||
|
||||
/**
|
||||
The first child node of the current node.
|
||||
*/
|
||||
- (nullable HTMLNode *)firstChild;
|
||||
|
||||
/**
|
||||
The last child node of the current node.
|
||||
*/
|
||||
- (nullable HTMLNode *)lastChild;
|
||||
|
||||
/**
|
||||
The previous sibling node of the current node.
|
||||
*/
|
||||
- (nullable HTMLNode *)previousSibling;
|
||||
|
||||
/**
|
||||
The next sibling node of the current node.
|
||||
*/
|
||||
- (nullable HTMLNode *)nextSibling;
|
||||
|
||||
/**
|
||||
The previous node of the current node in tree order.
|
||||
*/
|
||||
- (nullable HTMLNode *)previousNode;
|
||||
|
||||
/**
|
||||
The next node of the current node in tree order.
|
||||
*/
|
||||
- (nullable HTMLNode *)nextNode;
|
||||
|
||||
@end
|
||||
|
||||
Reference in New Issue
Block a user