Add source documentation for the Parser classes
This commit is contained in:
iska
@@ -6,6 +6,10 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import "HTMLElement.h"
|
||||
#import "HTMLTokens.h"
|
||||
#import "HTMLNamespaces.h"
|
||||
|
||||
@@ -6,6 +6,10 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import "HTMLElement.h"
|
||||
#import "HTMLNamespaces.h"
|
||||
#import "NSString+HTMLKit.h"
|
||||
|
||||
@@ -6,33 +6,134 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import <Foundation/Foundation.h>
|
||||
#import "HTMLElement.h"
|
||||
|
||||
/**
|
||||
The List of Active Formatting Elements. It is used to handle mis-nested formatting element tags.
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#the-list-of-active-formatting-elements
|
||||
*/
|
||||
@interface HTMLListOfActiveFormattingElements : NSObject
|
||||
|
||||
/**
|
||||
Returns the object at the specified index.
|
||||
|
||||
@param index An index within the bounds of the list.
|
||||
@return The node located at index.
|
||||
*/
|
||||
- (id)objectAtIndexedSubscript:(NSUInteger)index;
|
||||
|
||||
/**
|
||||
Replaces the object at the index with the new object.
|
||||
|
||||
@param obj The node with which to replace the object at given index in the list.
|
||||
@param idx The index of the object to be replaced.
|
||||
*/
|
||||
- (void)setObject:(id)obj atIndexedSubscript:(NSUInteger)idx;
|
||||
|
||||
/**
|
||||
Returns the index of the given node in the list.
|
||||
|
||||
@param node The node.
|
||||
@returns The index of the given node in the list.
|
||||
*/
|
||||
- (NSUInteger)indexOfElement:(id)node;
|
||||
|
||||
/**
|
||||
Adds the given element to the list.
|
||||
|
||||
@param element The element to add.
|
||||
*/
|
||||
- (void)addElement:(HTMLElement *)element;
|
||||
|
||||
/**
|
||||
Removes the given element from the list.
|
||||
|
||||
@param element The element to remove.
|
||||
*/
|
||||
- (void)removeElement:(id)element;
|
||||
|
||||
/**
|
||||
Checks whether the given element is in the list.
|
||||
|
||||
@param element The element to check.
|
||||
@returns `YES` if element is in the list, `NO` otherwise.
|
||||
*/
|
||||
- (BOOL)containsElement:(id)element;
|
||||
|
||||
/**
|
||||
Inserts the given element at the index into the list.
|
||||
|
||||
@param element The element to insert.
|
||||
@param index The index at which the element should be inserted.
|
||||
*/
|
||||
- (void)insertElement:(HTMLElement *)element atIndex:(NSUInteger)index;
|
||||
|
||||
/**
|
||||
Replaces the element at the given index in the list with the new element.
|
||||
|
||||
@param index The index of the element to be replaced.
|
||||
@param element The element with which to replace the element at given index in the list.
|
||||
*/
|
||||
- (void)replaceElementAtIndex:(NSUInteger)index withElement:(HTMLElement *)element;
|
||||
|
||||
/**
|
||||
Returns the last element in this list.
|
||||
|
||||
@returns The last entry.
|
||||
*/
|
||||
- (id)lastEntry;
|
||||
|
||||
/**
|
||||
Adds a marker to the end of this list
|
||||
*/
|
||||
- (void)addMarker;
|
||||
|
||||
/**
|
||||
Clears all elements from the end of this list upto the last marker.
|
||||
*/
|
||||
- (void)clearUptoLastMarker;
|
||||
|
||||
/**
|
||||
Returns the last element in the list having the given tag name, that is between the end of the list and the last marker
|
||||
in the list, if any, or the start of the list otherwise.
|
||||
|
||||
@param tagName The tag name.
|
||||
@returns The formatting element.
|
||||
*/
|
||||
- (HTMLElement *)formattingElementWithTagName:(NSString *)tagName;
|
||||
|
||||
/**
|
||||
Returns the count of elements in this list.
|
||||
|
||||
@returns The elements count.
|
||||
*/
|
||||
- (NSUInteger)count;
|
||||
|
||||
/**
|
||||
Checks whether this list is empty.
|
||||
|
||||
@returns `YES` if the stack is empty, `NO` otherwise.
|
||||
*/
|
||||
- (BOOL)isEmpty;
|
||||
|
||||
/**
|
||||
Return an object enumerator over this list.
|
||||
|
||||
@returns An enumerator
|
||||
*/
|
||||
- (NSEnumerator *)enumerator;
|
||||
|
||||
/**
|
||||
Return an object enumerator over this list.
|
||||
|
||||
@returns An enumerator
|
||||
*/
|
||||
- (NSEnumerator *)reverseObjectEnumerator;
|
||||
|
||||
@end
|
||||
|
||||
@@ -6,10 +6,22 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import <Foundation/Foundation.h>
|
||||
|
||||
/**
|
||||
A Maker that is used in the List of Active Formatting Elements.
|
||||
|
||||
@see HTMLListOfActiveFormattingElements
|
||||
*/
|
||||
@interface HTMLMarker : NSObject
|
||||
|
||||
/**
|
||||
Returns the singleton instance of the Marker.
|
||||
*/
|
||||
+ (instancetype)marker;
|
||||
|
||||
@end
|
||||
|
||||
@@ -11,14 +11,62 @@
|
||||
|
||||
NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
/**
|
||||
The HTML Parser.
|
||||
Parses HTML strings to valid HTML documents and/or fragments. This parser implements the WHATWG specification:
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#tree-construction
|
||||
|
||||
@see HTMLDocument
|
||||
@see HTMLElement
|
||||
*/
|
||||
@interface HTMLParser : NSObject
|
||||
|
||||
/**
|
||||
An array of errors that occurred during document parsing.
|
||||
*/
|
||||
@property (nonatomic, strong, readonly) NSArray *parseErrors;
|
||||
|
||||
/**
|
||||
The parsed HTML Document.
|
||||
|
||||
@see HTMLDocument
|
||||
*/
|
||||
@property (nonatomic, strong, readonly) HTMLDocument *document;
|
||||
|
||||
/**
|
||||
Intializes a new parser instance with a given HTML string.
|
||||
|
||||
@discussion The parser assumes a UTF-8 encoded string and does not implement the encoding sniffing algorithm that is
|
||||
described under the following section of the specification:
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#determining-the-character-encoding
|
||||
|
||||
@param string The HTML string to parse
|
||||
@returns A new instance of the HTML parser.
|
||||
*/
|
||||
- (instancetype)initWithString:(NSString *)string;
|
||||
|
||||
/**
|
||||
Runs the parsing algorithm and generates a valid HTML document object.
|
||||
|
||||
@returns A HTML document object that is the result of parsing the HTML string, with which this parser instance was
|
||||
initialized
|
||||
|
||||
@see HTMLDocument
|
||||
*/
|
||||
- (HTMLDocument *)parseDocument;
|
||||
|
||||
/**
|
||||
Runs the HTML fragment parsing algorithm with the provided context element. The algorithm is sprecified under the
|
||||
following section: https://html.spec.whatwg.org/multipage/syntax.html#parsing-html-fragments
|
||||
|
||||
@discussion The fragment parsing algorithm can be run multiple times with different context elements on the same parser
|
||||
instance. In this case the parser will reset its internal state and re-run the parsing algorithm.
|
||||
|
||||
@param contextElement A context element used for parsing a HTML fragment
|
||||
@returns An array of HTML elements, that are the result of parsing the given HTML string with the given context element.
|
||||
|
||||
@see HTMLElement
|
||||
*/
|
||||
- (NSArray *)parseFragmentWithContextElement:(HTMLElement *)contextElement;
|
||||
|
||||
@end
|
||||
|
||||
@@ -6,6 +6,10 @@
|
||||
// Copyright (c) 2014 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#define INSERTION_MODES \
|
||||
MODE_ENTRY( HTMLInsertionModeInitial, = 0 ) \
|
||||
MODE_ENTRY( HTMLInsertionModeBeforeHTML, ) \
|
||||
|
||||
@@ -6,37 +6,162 @@
|
||||
// Copyright (c) 2015 BrainCookie. All rights reserved.
|
||||
//
|
||||
|
||||
///------------------------------------------------------
|
||||
/// HTMLKit private header
|
||||
///------------------------------------------------------
|
||||
|
||||
#import <Foundation/Foundation.h>
|
||||
#import "HTMLElement.h"
|
||||
|
||||
/**
|
||||
The Stack of Open Elements. The stack grows downwards; the topmost node on the stack is the first one added to the
|
||||
stack, and the bottommost node of the stack is the most recently added node in the stack
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#the-stack-of-open-elements
|
||||
*/
|
||||
@interface HTMLStackOfOpenElements : NSObject <NSFastEnumeration>
|
||||
|
||||
/** @brief The current node in the stack. It is the bottommost node. */
|
||||
- (HTMLElement *)currentNode;
|
||||
|
||||
/** @brief The first node in the stack. */
|
||||
- (HTMLElement *)firstNode;
|
||||
|
||||
/** @brief The last node in the stack. */
|
||||
- (HTMLElement *)lastNode;
|
||||
|
||||
/**
|
||||
Returns the object at the specified index.
|
||||
|
||||
@param index An index within the bounds of the stack.
|
||||
@return The node located at index.
|
||||
*/
|
||||
- (id)objectAtIndexedSubscript:(NSUInteger)index;
|
||||
|
||||
/**
|
||||
Replaces the object at the index with the new object.
|
||||
|
||||
@param obj The node with which to replace the object at given index in the stack.
|
||||
@param idx The index of the object to be replaced.
|
||||
*/
|
||||
- (void)setObject:(id)obj atIndexedSubscript:(NSUInteger)idx;
|
||||
|
||||
/**
|
||||
Returns the index of the given node in the stack.
|
||||
|
||||
@param node The node.
|
||||
@returns The index of the given node in the stack.
|
||||
*/
|
||||
- (NSUInteger)indexOfElement:(id)node;
|
||||
|
||||
/**
|
||||
Pushes the given element onto the stack.
|
||||
|
||||
@param element The element.
|
||||
*/
|
||||
- (void)pushElement:(HTMLElement *)element;
|
||||
|
||||
/**
|
||||
Removes the given element from the stack.
|
||||
|
||||
@param element The element.
|
||||
*/
|
||||
- (void)removeElement:(id)element;
|
||||
|
||||
/**
|
||||
Checks whether the given element is in the stack.
|
||||
|
||||
@param element The element.
|
||||
@returns `YES` if the element is in the stack, `NO` otherwise.
|
||||
*/
|
||||
- (BOOL)containsElement:(id)element;
|
||||
|
||||
/**
|
||||
Checks whether an element with the given tag name is in the stack.
|
||||
|
||||
@param tagname The element's tag name.
|
||||
@returns `YES` if such an element is in the stack, `NO` otherwise.
|
||||
*/
|
||||
- (BOOL)containsElementWithTagName:(NSString *)tagName;
|
||||
|
||||
/**
|
||||
Inserts the given element at the index into the stack.
|
||||
|
||||
@param element The element to insert.
|
||||
@param index The index at which the element should be inserted.
|
||||
*/
|
||||
- (void)insertElement:(HTMLElement *)element atIndex:(NSUInteger)index;
|
||||
|
||||
/**
|
||||
Replaces the element at the given index in the stack with the new element.
|
||||
|
||||
@param index The index of the element to be replaced.
|
||||
@param element The element with which to replace the element at given index in the stack.
|
||||
*/
|
||||
- (void)replaceElementAtIndex:(NSUInteger)index withElement:(HTMLElement *)element;
|
||||
|
||||
/**
|
||||
Pops current node from the stack.
|
||||
*/
|
||||
- (void)popCurrentNode;
|
||||
|
||||
/**
|
||||
Pops elements from the stack until an element with the given tag name is poped.
|
||||
|
||||
@param tagName The tag name.
|
||||
*/
|
||||
- (void)popElementsUntilElementPoppedWithTagName:(NSString *)tagName;
|
||||
|
||||
/**
|
||||
Pops elements from the stack until an element with any of the given tag names is poped.
|
||||
|
||||
@param tagNames The tag names.
|
||||
*/
|
||||
- (void)popElementsUntilAnElementPoppedWithAnyOfTagNames:(NSArray *)tagNames;
|
||||
|
||||
/**
|
||||
Pops elements from the stack until the given element is poped.
|
||||
|
||||
@param element The element.
|
||||
*/
|
||||
- (void)popElementsUntilElementPopped:(HTMLElement *)element;
|
||||
|
||||
/**
|
||||
Pops elements from the stack until a template element is poped.
|
||||
*/
|
||||
- (void)popElementsUntilTemplateElementPopped;
|
||||
|
||||
/**
|
||||
Clears the stack to a table context
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#clear-the-stack-back-to-a-table-context
|
||||
*/
|
||||
- (void)clearBackToTableContext;
|
||||
|
||||
/**
|
||||
Clears the stack to a table body context
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#clear-the-stack-back-to-a-table-body-context
|
||||
*/
|
||||
- (void)clearBackToTableBodyContext;
|
||||
|
||||
/**
|
||||
Clears the stack to a table context
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#clear-the-stack-back-to-a-table-row-context
|
||||
*/
|
||||
- (void)clearBackToTableRowContext;
|
||||
|
||||
/**
|
||||
Pops all nodes from the stack.
|
||||
*/
|
||||
- (void)popAll;
|
||||
|
||||
/**
|
||||
Methods for checking whether the stack contains elements in speccific scopes:
|
||||
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#has-an-element-in-the-specific-scope
|
||||
*/
|
||||
- (HTMLElement *)hasElementInScopeWithTagName:(NSString *)tagName;
|
||||
- (HTMLElement *)hasAnyElementInScopeWithAnyOfTagNames:(NSArray *)tagNames;
|
||||
- (HTMLElement *)hasElementInListItemScopeWithTagName:(NSString *)tagName;
|
||||
@@ -44,12 +169,45 @@
|
||||
- (HTMLElement *)hasElementInTableScopeWithTagName:(NSString *)tagName;
|
||||
- (HTMLElement *)hasElementInTableScopeWithAnyOfTagNames:(NSArray *)tagNames;
|
||||
- (HTMLElement *)hasElementInSelectScopeWithTagName:(NSString *)tagName;
|
||||
|
||||
/**
|
||||
Returns the furthest block after a given index.
|
||||
|
||||
@discussion The furthest block is the topmost node in the stack of open elements that is lower in the stack than
|
||||
formatting element, and is an element in the special category. This is used in the adoption agency algorithm:
|
||||
https://html.spec.whatwg.org/multipage/syntax.html#adoption-agency-algorithm
|
||||
|
||||
@param index The index.
|
||||
@returns The furthest block after index.
|
||||
*/
|
||||
- (HTMLElement *)furthestBlockAfterIndex:(NSUInteger)index;
|
||||
|
||||
/**
|
||||
Returns the count of elements in this stack.
|
||||
|
||||
@returns The elements count.
|
||||
*/
|
||||
- (NSUInteger)count;
|
||||
|
||||
/**
|
||||
Checks whether this stack is empty.
|
||||
|
||||
@returns `YES` if the stack is empty, `NO` otherwise.
|
||||
*/
|
||||
- (BOOL)isEmpy;
|
||||
|
||||
/**
|
||||
Return an object enumerator over this stack.
|
||||
|
||||
@returns An enumerator
|
||||
*/
|
||||
- (NSEnumerator *)enumerator;
|
||||
|
||||
/**
|
||||
Return a reverse object enumerator over this stack.
|
||||
|
||||
@returns A reverse enumerator
|
||||
*/
|
||||
- (NSEnumerator *)reverseObjectEnumerator;
|
||||
|
||||
@end
|
||||
|
||||
Reference in New Issue
Block a user