GitHub/HTMLKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add source code documentation for all HTML Node subclasses

Browse Source
This commit is contained in:
iska
2015-12-20 23:35:34 +01:00
parent fd965e014d
commit 7a1bb21b33
9 changed files with 294 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HTMLKit/HTMLComment.h
+10
View File
@@ -10,10 +10,20 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Comment node
*/
@interface HTMLComment : HTMLNode
/** @brief The comment string. */
@property (nonatomic, copy) NSString *data;
/**
Initializes a new HTML comment node.
@param data The comment string.
@returns A new isntance of a HTML comment node.
*/
- (instancetype)initWithData:(NSString *)data;
@end
HTMLKit/HTMLDOMTokenList.h
+77 -5
View File
@@ -12,23 +12,95 @@ NS_ASSUME_NONNULL_BEGIN
@class HTMLElement;
/**
A HTML DOM Token List.
The DOM Token List is used for manipulating an element's attributes that contain muliplte values separated by a space.
https://dom.spec.whatwg.org/#interface-domtokenlist
*/
@interface HTMLDOMTokenList : NSObject
/** @brief The associated context element. */
@property (nonatomic, strong, readonly) HTMLElement *element;
/** @brief The associated attribute. */
@property (nonatomic, strong, readonly) NSString *attribute;
/**
Initializes a new DOM token list.
@param element The associated context element.
@param attribute The associated attribute.
@param value The initial attribute's value.
@returns A new instance of the DOM token list.
*/
- (instancetype)initWithElement:(HTMLElement *)element attribute:(NSString *)attribute value:(NSString *)value;
/**
@returns The length of this token list
*/
- (NSUInteger)length;
- (BOOL)contains:(NSString *)token;
- (void)add:(NSArray<NSString *> *)tokens;
- (void)remove:(NSArray<NSString *> *)tokens;
- (BOOL)toggle:(NSString *)token;
- (void)replaceToke:(NSString *)token withToken:(NSString *)newToken;
/**
Checks whether this list contains the given token.
@param token The token.
@returns `YES` if the given token is in this list, `NO` otherwise.
*/
- (BOOL)contains:(NSString *)token;
/**
Add the given tokens to the list.
@param tokens The tokens to add.
*/
- (void)add:(NSArray<NSString *> *)tokens;
/**
Removes the given tokens from the list.
@param tokens The tokens to remove.
*/
- (void)remove:(NSArray<NSString *> *)tokens;
/**
Toggles the given token.
@param token The token to toggle.
@returns `YES` if the token was added to the list, `NO` if it was removed from it.
*/
- (BOOL)toggle:(NSString *)token;
/**
Replaces the given token with new token.
@param token The token to replace.
@param newToken The replacement token.
*/
- (void)replaceToken:(NSString *)token withToken:(NSString *)newToken;
/**
Returns the value of the token at the given index.
@param index The index at which to return the token.
@returns The token at the given index. If index is greater than or equal to the value returned by count, an
NSRangeException is raised.
*/
- (NSString *)objectAtIndexedSubscript:(NSUInteger)index;
/**
Set the token at the given index.
@param obj The token to set.
@param index The index at which to set the token. If index is greater than or equal to the value returned by count, an
NSRangeException is raised.
*/
- (void)setObject:(NSString *)obj atIndexedSubscript:(NSUInteger)index;
/**
@returns The string representation of this token list, which can be used as the attribute's value.
*/
- (NSString *)stringify;
@end
HTMLKit/HTMLDOMTokenList.m
+1 -1
View File
@@ -83,7 +83,7 @@
}
}
- (void)replaceToke:(NSString *)token withToken:(NSString *)newToken
- (void)replaceToken:(NSString *)token withToken:(NSString *)newToken
{
NSUInteger index = [_tokens indexOfObject:token];
_tokens[index] = newToken;
HTMLKit/HTMLDocument.h
+52 -2
View File
@@ -12,6 +12,10 @@
NS_ASSUME_NONNULL_BEGIN
/**
The document's ready state. The document is `Loading` while being parsed, `Complete` otherwise. The `Interactive` state
is not supported.
*/
typedef NS_ENUM(short, HTMLDocumentReadyState)
{
HTMLDocumentLoading,
@@ -19,28 +23,74 @@ typedef NS_ENUM(short, HTMLDocumentReadyState)
HTMLDocumentComplete
};
/**
The HTML Document. This is the root of a parsed DOM tree.
https://html.spec.whatwg.org/multipage/dom.html#documents
*/
@interface HTMLDocument : HTMLNode
/**
The document's DOCTYPE.
@see HTMLDocumentType
*/
@property (nonatomic, strong, nullable) HTMLDocumentType *documentType;
/**
The document's quirks mode.
@see HTMLQuirksMode
*/
@property (nonatomic, assign) HTMLQuirksMode quirksMode;
@property (nonatomic, copy, readonly) NSString *compatMode;
/**
The document's ready state.
@see HTMLDocumentReadyState
*/
@property (nonatomic, assign, readonly) HTMLDocumentReadyState readyState;
/**
The document's root element, which is the first element in tree order, if any. Usually it is the <html> element.
*/
@property (nonatomic, strong, nullable) HTMLElement *rootElement;
/**
The document element, i.e. the <html> element, if it exists.
*/
@property (nonatomic, strong, nullable) HTMLElement *documentElement;
/**
The document's <head> element, if it exists.
*/
@property (nonatomic, strong, nullable) HTMLElement *head;
/**
The document's <body> element, if it exists.
*/
@property (nonatomic, strong, nullable) HTMLElement *body;
/**
Retunrs a new HTML Document instance with the given HTML string.
@param string The HTML string to parse into a document.
*/
+ (instancetype)documentWithString:(NSString *)string;
/**
Adopts a given node into this document, i.e. the document becomes the new owner of the node. Raises a HTMLKitNotSupportedError
exception if node is an instance of HTMLDocument.
@param node The node to adopt.
@returns The adopted node
*/
- (HTMLNode *)adoptNode:(HTMLNode *)node;
/**
Returns the associated HTML Document proxy instance, which owns the template contents of all its template elements.
https://html.spec.whatwg.org/multipage/scripting.html#associated-inert-template-document
*/
- (HTMLDocument *)associatedInertTemplateDocument;
@end
HTMLKit/HTMLDocumentFragment.h
+12
View File
@@ -10,8 +10,20 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Document Fragment. Represents a minimal document object that has no parent. It is used as a light-weight
version of Document
https://dom.spec.whatwg.org/#interface-documentfragment
*/
@interface HTMLDocumentFragment : HTMLNode
/**
Initializes a new document fragment with the given document as owner.
@param document The owner document.
@returns A new instance of a document fragment.
*/
- (instancetype)initWithDocument:(nullable HTMLDocument *)document;
@end
HTMLKit/HTMLDocumentType.h
+35
View File
@@ -11,17 +11,52 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Document Type node. There is only one valid document type, which is `<!DOCTYPE html>`.
Other DOCTYPES, e.g. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
are obsolete but permitted.
https://dom.spec.whatwg.org/#interface-documenttype
*/
@interface HTMLDocumentType : HTMLNode
/**
The public identifier
*/
@property (nonatomic, copy, readonly) NSString *publicIdentifier;
/**
The system identifier
*/
@property (nonatomic, copy, readonly) NSString *systemIdentifier;
/**
Initializes and returns a new isntance of a Document Type node.
@param name The name.
@param publicIdentifier The public identifier.
@param systemIdentifier The system identigier
@returns A new document type instance.
*/
- (instancetype)initWithName:(NSString *)name
publicIdentifier:(nullable NSString *)publicIdentifier
systemIdentifier:(nullable NSString *)systemIdentifier;
/**
Checks whether this DOCTYPE is valid.
@returns `YES` if this is a valid DOCTYPE, `NO` otherwise.
*/
- (BOOL)isValid;
/**
Return the quirks mode of this DOCTYPE.
@returns The quirks mode.
@see HTMLQuirksMode
*/
- (HTMLQuirksMode)quirksMode;
@end
HTMLKit/HTMLElement.h
+82
View File
@@ -13,27 +13,109 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Element.
https://html.spec.whatwg.org/multipage/dom.html#elements
https://html.spec.whatwg.org/multipage/syntax.html#elements-2
*/
@interface HTMLElement : HTMLNode
/**
The namesapce of this element.
@see HTMLNamespace
*/
@property (nonatomic, assign, readonly) HTMLNamespace htmlNamespace;
/**
The elemen's tag name.
*/
@property (nonatomic, copy, readonly) NSString *tagName;
/**
The elemen's id attribute value. Empty string if the element has no id attribute.
*/
@property (nonatomic, copy) NSString *elementId;
/**
The elemen's class attribute value. Empty string if the element has no class attribute.
*/
@property (nonatomic, copy) NSString *className;
/**
The element's class attribute as a DOM Token List
@see HTMLDOMTokenList
*/
@property (nonatomic, strong, readonly) HTMLDOMTokenList *classList;
/**
The element's attribites.
*/
@property (nonatomic, strong) NSMutableDictionary *attributes;
/**
@warning Use one of the initWithTagName: methods instead.
*/
- (instancetype)init NS_UNAVAILABLE;
/**
Initializes a new HTML element with the given tag name.
@param tagname The tag name.
@returns A new HTML element.
*/
- (instancetype)initWithTagName:(NSString *)tagName;
/**
Initializes a new HTML element with the given tag name and attributes.
@param tagname The tag name.
@param attributes The attributes.
@returns A new HTML element.
*/
- (instancetype)initWithTagName:(NSString *)tagName attributes:(NSDictionary *)attributes;
/**
Initializes a new HTML element with the given tag name, namespace, and attributes.
@param tagname The tag name.
@param namespace The namespace.
@param attributes The attributes.
@returns A new HTML element.
*/
- (instancetype)initWithTagName:(NSString *)tagName namespace:(HTMLNamespace)htmlNamespace attributes:(NSDictionary *)attributes;
/**
Checks whether this element has an attribute with the given name.
@param name The attribute name.
@returns `YES` if the element has such an attributes, `NO` otherwise.
*/
- (BOOL)hasAttribute:(NSString *)name;
/**
Returns the value of the attribute with the given name.
@param name The attribute's name.
@returns The attribute's value, `nil` if the element doesn't have such attribute.
*/
- (nullable NSString *)objectForKeyedSubscript:(NSString *)name;
/**
Set the value of the attribute with the given name.
@param value The value to set.
@param name The attribute's name.
*/
- (void)setObject:(NSString *)value forKeyedSubscript:(NSString *)attribute;
/**
Removes the attribute with the given name.
@param name The attribute to remove.
*/
- (void)removeAttribute:(NSString *)name;
@end
HTMLKit/HTMLTemplate.h
+10
View File
@@ -11,8 +11,18 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Template node.
https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
*/
@interface HTMLTemplate : HTMLElement
/**
The content of the template.
@see HTMLDocumentFragment
*/
@property (nonatomic, strong) HTMLDocumentFragment *content;
@end
HTMLKit/HTMLText.h
+15
View File
@@ -10,12 +10,27 @@
NS_ASSUME_NONNULL_BEGIN
/**
A HTML Text node
*/
@interface HTMLText : HTMLNode
/** @brief The text string. */
@property (nonatomic, copy) NSMutableString *data;
/**
Initializes a new HTML text node.
@param data The text string.
@returns A new isntance of a HTML text node.
*/
- (instancetype)initWithData:(NSString *)data;
/**
Appends the string to this text node.
@param string The string to append.
*/
- (void)appendString:(NSString *)string;
@end