From c2e1fb8e0aa51ced87f883c05523de01b44cc59e Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Fri, 31 May 2024 15:38:46 +0100 Subject: [PATCH] Reorganize HTML plugin API functions in the same order as in the code to make it easier to keep the two in sync --- site/reference-manual.md | 156 ++++++++++++++++++++------------------- 1 file changed, 79 insertions(+), 77 deletions(-) diff --git a/site/reference-manual.md b/site/reference-manual.md index 3790996..b1398fd 100644 --- a/site/reference-manual.md +++ b/site/reference-manual.md @@ -1714,7 +1714,7 @@ This can be used to avoid running some expensive calculations more than once, or -##### Document parsing, creation, and formatting +##### Parsing and rendering ###### HTML.parse(string) @@ -1729,16 +1729,6 @@ and correct errors as much as it can. For best results, make sure that your HTML is valid, since invalid HTML may silently produce unexpected behavior. -###### HTML.create_document() - -Creates an empty HTML element tree root. - -Example: `doc = HTML.create_document()` - -###### HTML.clone_document(html) - -Creates a full copy of an HTML document element tree. - ###### HTML.to_string(html) Converts an HTML element tree to HTML source, without adding any whitespace. @@ -1747,14 +1737,13 @@ Converts an HTML element tree to HTML source, without adding any whitespace. Converts an HTML element tree to HTML source and adds whitespace for readability. -##### Element creation and destructuring +##### Node creation -###### HTML.create_text(string) +###### HTML.create_document() -Example: `h = HTML.create_text("hello world")` +Creates an empty HTML element tree root. -Creates a text node that can be inserted into the page just like element nodes. -This function automatically escapes all HTML special characters inside the string. +Example: `doc = HTML.create_document()` ###### HTML.create_element(tag, text) @@ -1764,23 +1753,29 @@ Creates an HTML element node. The text argument can be `nil`, so you can safely omit it and write something like `h = HTML.create_element("hr")`. -###### HTML.inner_html(html) +###### HTML.create_text(string) -Example: `h = HTML.inner_html(HTML.select(page, "body"))` +Example: `h = HTML.create_text("hello world")` -Returns element content as a string. +Creates a text node that can be inserted into an element tree just like element nodes. +This function automatically escapes all HTML special characters inside the string. -###### HTML.inner_text(html) +##### Node cloning -Similar to `HTML.inner_html` but strips all tags away and returns only the text. +###### HTML.clone_document(html) -###### HTML.strip_tags(html) +Creates a full copy of an HTML document element tree. -Example: `h = HTML.strip_tags(HTML.select(page, "body"))` +###### HTML.clone_content(html_element) -Returns element content as a string, with all HTML tags removed. +Creates a new HTML element tree object from the content of an element. + +Useful for duplicating an element elsewhere in the page. +Since `HTML.select` and friends return _references_ to elements within the `page` tree. +To create a new element _value_ that can be independently modified, you need to clone an element +using this function. -##### Element tree queries +##### Selection and selector match checking ###### HTML.select(html, selector) @@ -1815,7 +1810,7 @@ Example: `HTML.matches_selector(page, (HTML.select_one(page, "body")), "body")` Checks if an element node matches given selector. -The `elem` value must be an element node retrieved from an `document` with a function from the `HTML.select_*` family. +The `elem` value must be an element node retrieved from an `document` with a function from the `HTML.select_*` fami> The reason you need to give that function both parent document and child element values is that otherwise composite selectors like `div > p` wouldn’t work. @@ -1825,7 +1820,7 @@ otherwise composite selectors like `div > p` wouldn’t work. Like `HTML.matches_selector`, but allows checking against a list of selectors and returns true if any of them would match. -##### Access to surrounding elements +##### Access to element tree surroundings ###### HTML.parent(elem) @@ -1866,34 +1861,17 @@ Table.iter_values(add_silly_class, children) Returns the number of element’s children (handy for checking if it has any). -##### Tag and attribute manipulation - -###### HTML.is_element(elem) - -Web browsers provide a narrower API than general purpose HTML parsers. In the JavaScript DOM API, `element.children` provides access to all _child elements_ of an element. - -However, in the HTML parse tree, the picture is more complex. Text nodes are also child nodes—browsers just filter those out because JavaScript code rarely has a need to do anything with text nodes. - -Consider this HTML: `

This is a great paragraph

`. How many children does the `

` element have? In fact, three: `text("This is a ")`, `element("em", "great")`, `text(" paragraph")`. - -The goal of soupault is to allow modifying HTML pages in any imaginable way, so it cannot ignore this complexity. -Many operations like `HTML.add_class` still make no sense for text nodes, so there has to be a way to check if something is an element or not. - -That’s where `HTML.is_element` comes in handy. - ###### HTML.is_empty(elem) (since 4.6.0) -Returns true is `elem` has no child nodes. - -###### HTML.is_root(elem) (since 4.6.0) +Returns true is `elem` has no child nodes (a shortcut for `HTML.child_cound(elem) == 0`). -Returns true if `elem` has no parent node. +##### Element property access and manipulation ###### HTML.get_tag_name(html_element) Returns the tag name of an element. -Example: +Example: ```lua link_or_pic = HTML.select_any_of(page, {"a", "img"}) @@ -1923,10 +1901,10 @@ end Example: `href = HTML.get_attribute(link, "href")` -Returns the value of an element attribute. The first argument must be an element reference produced by `HTML.select_one` or another function. +Returns the value of an element attribute. The first argument must be an element reference produced by `HTML.select> -If the attribute is missing, it returns `nil`. If the attribute is present but its value is empty (like in `` or ``), it returns an empty string. -In Lua, both empty strings and `nil` are false for the purpose of `if value then … end`, so if you want to check for presence of an attribute regardless of its value, you should explicitly check for `nil`. +If the attribute is missing, it returns `nil`. If the attribute is present but its value is empty (like in ` +In Lua, both empty strings and `nil` are false for the purpose of `if value then … end`, so if you want to check fo> ###### HTML.set_attribute(html_element, attribute, value) @@ -1934,39 +1912,63 @@ Example: `HTML.set_attribute(content_div, "id", "content")` Sets an attribute value. +###### HTML.append_attribute(html_element, attribute, value) + +Appends a string to the value of an attribute. + +For example, a crude reimplementation of `HTML.add_class`: `HTML.append_attribute(content_div, "class", " green-background")` + ###### HTML.delete_attribute(html_element, attribute) Example: `HTML.delete_attribute(content_div, "id")` -Removes an attribute. +Removes an attribute from an element. + +###### HTML.list_attributes(html_element) + +Returns a list (i.e., a number-indexed table) with names of all attributes of an element. +For example, for `

` +it would return `{"id", "class"}`. + +###### HTML.clear_attributes(html_element) + +Removes all attributes from an element. ###### HTML.get_classes(html_element) If an element has `class` attribute, returns a list (i.e. a number-indexed table) of its classes. +###### HTML.has_class(html_element, class_name) + +Returns true is an element has given class. + ###### HTML.add_class(html_element, class_name) Example: `HTML.add_class(p, "centered")` Adds a new class. If an element has no classes, adds a `class` attribute in the process. -###### HTML.has_class(html_element, class_name) - -Returns true is an element has given class. - ###### HTML.remove_class(html_element, class_name) Example: `HTML.remove_class(p, "centered")` -###### HTML.list_attributes(html_element) +###### HTML.inner_html(html) -Returns a list (i.e. a number-indexed table) with names of all attributes of an element. +Example: `h = HTML.inner_html(HTML.select(page, "body"))` -###### HTML.clear_attributes(html_element) +Returns element content as a string. -Removes all attributes from an element. +###### HTML.inner_text(html) -##### Element tree modification +Similar to `HTML.inner_html` but strips all tags away and returns only the text. + +###### HTML.strip_tags(html) + +Example: `h = HTML.strip_tags(HTML.select(page, "body"))` + +Returns element content as a string, with all HTML tags removed. + +##### Element tree manipulation ###### HTML.append_root(parent, child) ###### HTML.prepend_root(parent, child) (since 4.5.0) @@ -2001,31 +2003,27 @@ HTML.insert_before(main, header) HTML.insert_after(main, footer) ``` +###### HTML.replace(orig, new) (legacy name) +###### HTML.replace_element(orig, new) (new name, recommended) + +Deletes the `orig` element from the element tree where it belongs +and inserts the `new` element in its former place. + ###### HTML.replace_content(parent, child) Deletes all existing children of the `parent` element and inserts the `child` element in their place. -###### HTML.delete(element) +###### HTML.delete(element) (legacy name) +###### HTML.delete_element(element) (new name, recommended) Example: `HTML.delete(HTML.select_one(page, "h1"))` -Deletes an element from the page. +Deletes an element from an element tree. ###### HTML.delete_content(element) Deletes all children of an element (but leaves the element itself in place). -###### HTML.clone_content(html_element) - -Creates a new HTML element tree object from the content of an element. - -Useful for duplicating an element elsewhere in the page. -Since `HTML.select` and friends return _references_ to elements within the `page` tree. -To create a new element _value_ that can be independently modified, you need to clone an element -using this function. - -##### Convenience functions - ###### HTML.wrap(node, elem) (since 4.7.0) Wraps `node` in `elem`. @@ -2038,14 +2036,18 @@ and leave just `

Test!

`. ###### HTML.swap(l, r) -Swaps two elements in the element tree. Element nodes `l` and `r`, obviously, -must belong to the same element tree. +Swaps two elements in an element tree. +Element nodes `l` and `r`, obviously, must belong to the same element tree. + +##### Node tests + +##### High-level convenience functions ###### HTML.get_heading_level(element) For elements whose tag name matches `` pattern, returns the heading level. -Returns zero for elements whose tag name doesn’t look like a heading and for values that aren’t HTML elements. +Returns zero for elements whose tag name doesn't look like a heading and for values that aren't HTML elements. ###### HTML.get_headings_tree(element) @@ -2063,7 +2065,7 @@ Returns a table that represents the tree of HTML document headings in a format l ] ``` -Values of `heading` fields are HTML element references. Perfect for those who want to implement their own ToC generator. +Values of `heading` fields are HTML element references (not clones). Perfect for those who want to implement their own ToC generator. ##### Behaviour