HTMLNode.h

//  HTMLNode.h
//
//  Public domain. https://github.com/nolanw/HTMLReader

#import <HTMLReader/HTMLNamespace.h>
#import <HTMLReader/HTMLSupport.h>
@class HTMLDocument;
@class HTMLElement;

NS_ASSUME_NONNULL_BEGIN

/**
    HTMLNode is an abstract class representing a node in a parsed HTML tree.
 
    A node maintains strong references to its children and a weak reference to its parents.
 
    @note Copying an HTMLNode does not copy its document, parentElement, or children.
 */
@interface HTMLNode : NSObject <NSCopying>

/// Basically useless on its own; please call a subclass's initializer to initialize a useful HTMLNode.
- (instancetype)init NS_DESIGNATED_INITIALIZER;

/// The document in which this node appears, or nil if the node is not in a tree with a document at its root.
@property (readonly, strong, nonatomic) HTMLDocument * __nullable document;

/// The node's parent, or nil if the node is a root node.
@property (weak, nonatomic) HTMLNode * __nullable parentNode;

/// The node's parent if it is an instance of HTMLElement, otherwise nil. Setter is equivalent to calling -setParentNode:.
@property (weak, nonatomic) HTMLElement * __nullable parentElement;

/// Removes the node from its parent, effectively detaching it from the tree.
- (void)removeFromParentNode;

/// The node's children. Each is an instance of HTMLNode. Key-Value Coding compliant for accessing and mutation.
@property (readonly, copy, nonatomic) HTMLOrderedSetOf(HTMLNode *) *children;

/// Convenience method that returns a mutable proxy for children. The proxy returned by -mutableChildren is much faster than the one obtained by calling -mutableOrderedSetValueForKey: yourself.
@property (readonly, nonatomic) HTMLMutableOrderedSetOf(HTMLNode *) *mutableChildren;

/**
    The number of nodes that have the node as their parent.
 
    This method is faster than calling `aNode.children.count`.
 */
@property (readonly, assign, nonatomic) NSUInteger numberOfChildren;

/**
    Returns a child of the node. Throws an NSRangeException if index is out of bounds.
 
    This method is faster than calling `[aNode.children objectAtIndex:]`.
 */
- (HTMLNode *)childAtIndex:(NSUInteger)index;

/**
    Returns the location of a child, or NSNotFound if the node is not the child's parent.
 
    This method is faster than calling `[aNode.children indexOfObject:]`.
 */
- (NSUInteger)indexOfChild:(HTMLNode *)child;

/// The node's children which are instances of HTMLElement.
@property (readonly, copy, nonatomic) HTMLArrayOf(HTMLElement *) *childElementNodes;

/**
    Emits in tree order the nodes in the subtree rooted at the node.
 
    For more information, see http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order
 */
- (HTMLEnumeratorOf(HTMLNode *) *)treeEnumerator;

/// Emits in tree order the node in the subree rooted at the node, except children are enumerated back to front.
- (HTMLEnumeratorOf(HTMLNode *) *)reversedTreeEnumerator;

/**
    The combined text content of the node and its descendants. The setter replaces the node's text, removing all descendants.
 
    For more information, see http://dom.spec.whatwg.org/#dom-node-textcontent
 */
@property (copy, nonatomic) NSString *textContent;

/**
    Convenience method for either adding a string to an existing text node or creating a new text node.
 
    @param string         The text to insert.
    @param childNodeIndex The desired location of the text. If a new text node is created, this is where it will be inserted.
 */
- (void)insertString:(NSString *)string atChildNodeIndex:(NSUInteger)childNodeIndex;

@end

NS_ASSUME_NONNULL_END