diff --git a/HTMLKit/HTMLElementAdjustment.h b/HTMLKit/HTMLElementAdjustment.h index e6f2e24..17b1864 100644 --- a/HTMLKit/HTMLElementAdjustment.h +++ b/HTMLKit/HTMLElementAdjustment.h @@ -6,6 +6,10 @@ // Copyright (c) 2015 BrainCookie. All rights reserved. // +///------------------------------------------------------ +/// HTMLKit private header +///------------------------------------------------------ + #import "HTMLElement.h" #import "HTMLTokens.h" #import "HTMLNamespaces.h" diff --git a/HTMLKit/HTMLElementTypes.h b/HTMLKit/HTMLElementTypes.h index 44be082..bf7ce2d 100644 --- a/HTMLKit/HTMLElementTypes.h +++ b/HTMLKit/HTMLElementTypes.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" diff --git a/HTMLKit/HTMLListOfActiveFormattingElements.h b/HTMLKit/HTMLListOfActiveFormattingElements.h index 9b7d7b4..475dd85 100644 --- a/HTMLKit/HTMLListOfActiveFormattingElements.h +++ b/HTMLKit/HTMLListOfActiveFormattingElements.h @@ -6,33 +6,134 @@ // Copyright (c) 2015 BrainCookie. All rights reserved. // +///------------------------------------------------------ +/// HTMLKit private header +///------------------------------------------------------ + #import #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 diff --git a/HTMLKit/HTMLMarker.h b/HTMLKit/HTMLMarker.h index 1aa2ef8..7acd23b 100644 --- a/HTMLKit/HTMLMarker.h +++ b/HTMLKit/HTMLMarker.h @@ -6,10 +6,22 @@ // Copyright (c) 2015 BrainCookie. All rights reserved. // +///------------------------------------------------------ +/// HTMLKit private header +///------------------------------------------------------ + #import +/** + 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 diff --git a/HTMLKit/HTMLParser.h b/HTMLKit/HTMLParser.h index 2607919..02e4cef 100644 --- a/HTMLKit/HTMLParser.h +++ b/HTMLKit/HTMLParser.h @@ -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 diff --git a/HTMLKit/HTMLParserInsertionModes.h b/HTMLKit/HTMLParserInsertionModes.h index 69fb669..c86dde0 100644 --- a/HTMLKit/HTMLParserInsertionModes.h +++ b/HTMLKit/HTMLParserInsertionModes.h @@ -6,6 +6,10 @@ // Copyright (c) 2014 BrainCookie. All rights reserved. // +///------------------------------------------------------ +/// HTMLKit private header +///------------------------------------------------------ + #define INSERTION_MODES \ MODE_ENTRY( HTMLInsertionModeInitial, = 0 ) \ MODE_ENTRY( HTMLInsertionModeBeforeHTML, ) \ diff --git a/HTMLKit/HTMLStackOfOpenElements.h b/HTMLKit/HTMLStackOfOpenElements.h index 590afce..cbdab6e 100644 --- a/HTMLKit/HTMLStackOfOpenElements.h +++ b/HTMLKit/HTMLStackOfOpenElements.h @@ -6,37 +6,162 @@ // Copyright (c) 2015 BrainCookie. All rights reserved. // +///------------------------------------------------------ +/// HTMLKit private header +///------------------------------------------------------ + #import #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 +/** @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