Floki

https://floki.hexdocs.pm/
Admin
Floki is a simple HTML parser for Elixir that enables searching for nodes using CSS selectors,...
Tokens:10,890
Snippets:109
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Installing Floki

Source: https://floki.hexdocs.pm/

Instructions for adding Floki to a project via mix.exs or installing it directly in scripts.

```elixir
defp deps do
  [
    {:floki, "~> 0.38.0"}
  ]
end
```

```elixir
Mix.install([
  {:floki, "~> 0.38.0"
])
```

--------------------------------

### Install Floki with Mix.install

Source: https://floki.hexdocs.pm/readme.md

Use this method for scripts or Livebook environments.

```elixir
Mix.install([
  {:floki, "~> 0.38.0"}
])
```

--------------------------------

### Parse HTML document examples

Source: https://floki.hexdocs.pm/Floki.md

Examples demonstrating basic parsing, specifying a parser module, and enabling attribute maps.

```elixir
iex> Floki.parse_document("<html><head></head><body>hello</body></html>")
{:ok, [{"html", [], [{"head", [], []}, {"body", [], ["hello"]}]}]}
```

```elixir
iex> Floki.parse_document("<html><head></head><body>hello</body></html>", html_parser: Floki.HTMLParser.Mochiweb)
{:ok, [{"html", [], [{"head", [], []}, {"body", [], ["hello"]}]}]}
```

```elixir
iex> Floki.parse_document(
...>   "<html><head></head><body class=main>hello</body></html>",
...>   attributes_as_maps: true,
...>   html_parser: Floki.HTMLParser.Mochiweb
...>)
{:ok, [{"html", %{}, [{"head", %{}, []}, {"body", %{"class" => "main"}, ["hello"]}]}]}
```

--------------------------------

### Traverse and update HTML tree examples

Source: https://floki.hexdocs.pm/Floki.md

Examples demonstrating node transformation and accumulator usage during tree traversal.

```elixir
iex> html = [{"div", [], [{:comment, "I am a comment"}, "hello"]}, {"div", [], ["world"]}]
iex> Floki.traverse_and_update(html, 0, fn
...>   {"div", attrs, children}, acc ->
...>     {{"p", [{"data-count", to_string(acc)} | attrs], children}, acc + 1}
...>   other, acc -> {other, acc}
...> end)
{[
   {"p", [{"data-count", "0"}], [{:comment, "I am a comment"}, "hello"]},
   {"p", [{"data-count", "1"}], ["world"]}
 ], 2}
```

```elixir
iex> html = {"div", [], [{"span", [], ["hello"]}]}
iex> Floki.traverse_and_update(html, [deleted: 0], fn
...>   {"span", _attrs, _children}, acc ->
...>     {nil, Keyword.put(acc, :deleted, acc[:deleted] + 1)}
...>   tag, acc ->
...>     {tag, acc}
...> end)
{{"div", [], []}, [deleted: 1]}
```

--------------------------------

### Example HTML Structure

Source: https://floki.hexdocs.pm/

Sample HTML document used for demonstrating Floki parsing and querying capabilities.

```html
<!DOCTYPE html>
<html>
  <body>
    <section id="content">
      <p class="headline">Floki</p>
      <span class="headline">Enables search using CSS selectors</span>
      <a href="https://github.com/philss/floki">Github page</a>
      <span data-model="user">philss</span>
    </section>
    <a href="https://hex.pm/packages/floki">Hex package</a>
  </body>
</html>
```

--------------------------------

### Configure HTML Parser

Source: https://floki.hexdocs.pm/Floki.HTMLParser.md

Examples for setting the HTML parser via function options or global application configuration.

```elixir
Floki.parse_document(document, html_parser: Floki.HTMLParser.FastHtml)
```

```elixir
import Config
config :floki, :html_parser, Floki.HTMLParser.Mochiweb
```

--------------------------------

### Query HTML nodes

Source: https://floki.hexdocs.pm/Floki.md

Examples of CSS selector queries performed on a parsed HTML document.

```elixir
  * `Floki.find(html, "#content")`
  * `Floki.find(html, ".headline")`
  * `Floki.find(html, "a")`
  * `Floki.find(html, "[data-model=user]")`
  * `Floki.find(html, "#content a")`
  * `Floki.find(html, ".headline, a")`
```

--------------------------------

### Query HTML with robust selectors

Source: https://floki.hexdocs.pm/changelog.md

Use these examples to perform complex queries on HTML content using combined selector types.

```elixir
Floki.find(html, "a.foo")
```

```elixir
Floki.find(html, "a.foo[data-action=post]")
```

```elixir
Floki.find(html, ".foo.bar")
```

```elixir
Floki.find(html, "a.foo[href$='.org']")
```

--------------------------------

### Running Benchmarks

Source: https://floki.hexdocs.pm/

Commands to execute performance benchmarks for Floki's parsing capabilities.

```bash
sh benchs/extract.sh
mix run benchs/parse_document.exs
```

--------------------------------

### Configuring html5ever Parser

Source: https://floki.hexdocs.pm/

Steps to add html5ever as a dependency and configure Floki to use it as the default parser.

```elixir
defp deps do
  [
    {:floki, "~> 0.38.0"},
    {:html5ever, "~> 0.16.0"}
  ]
end
```

```elixir
# in config/config.exs

config :floki, :html_parser, Floki.HTMLParser.Html5ever
```

--------------------------------

### Configuring fast_html Parser

Source: https://floki.hexdocs.pm/

Steps to add fast_html as a dependency and configure Floki to use it as the default parser.

```elixir
defp deps do
  [
    {:floki, "~> 0.38.0"},
    {:fast_html, "~> 2.0"}
  ]
end
```

```elixir
# in config/config.exs

config :floki, :html_parser, Floki.HTMLParser.FastHtml
```

--------------------------------

### Update HTML parsing workflow

Source: https://floki.hexdocs.pm/changelog.md

Demonstrates the transition from passing raw HTML strings to using pre-parsed fragments for Floki functions.

```elixir
html = "<div class='foobar'><p>Hello</p></div>"
Floki.find(html, "p")
Floki.attribute(html, "div", "class")
```

```elixir
html = "<div class='foobar'><p>Hello</p></div>"
parsed_html = Floki.parse_fragment!(html)
Floki.find(parsed_html, "p")
Floki.attribute(parsed_html, "div", "class")
```

--------------------------------

### Querying HTML with Floki

Source: https://floki.hexdocs.pm/

Demonstrates parsing a document and using CSS selectors to find and extract HTML elements.

```elixir
{:ok, document} = Floki.parse_document(html)

Floki.find(document, "p.headline")
# => [{"p", [{"class", "headline"}], ["Floki"]}]

document
|> Floki.find("p.headline")
|> Floki.raw_html()
# => <p class="headline">Floki</p>
```

--------------------------------

### Define sample HTML document

Source: https://floki.hexdocs.pm/Floki.md

A basic HTML structure used for demonstrating parsing and querying capabilities.

```html
<!doctype html>
<html>
<body>
  <section id="content">
    <p class="headline">Floki</p>
    <a href="http://github.com/philss/floki">Github page</a>
    <span data-model="user">philss</span>
  </section>
</body>
</html>
```

--------------------------------

### Floki.raw_html/1

Source: https://floki.hexdocs.pm/

Converts a node tree back into a raw HTML string.

```APIDOC
## Floki.raw_html(nodes)

### Description
Serializes a node tree or list of nodes back into an HTML string representation.

### Parameters
- **nodes** (Term) - Required - The node tree or list of nodes to convert.
```

--------------------------------

### Transforming HTML Nodes

Source: https://floki.hexdocs.pm/Floki.md

Demonstrates replacing a div tag with a p tag using traverse_and_update.

```elixir
iex> html = [{"div", [], ["hello"]}]
iex> Floki.traverse_and_update(html, fn
...>   {"div", attrs, children} -> {"p", attrs, children}
...>   other -> other
...> end)
[{"p", [], ["hello"]}]
```

--------------------------------

### Parse HTML Fragment with parse_fragment!

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML fragment, raising a Floki.ParseError if parsing fails.

```elixir
@spec parse_fragment!(binary(), Keyword.t()) :: html_tree()
```

--------------------------------

### HTMLParser Callback Definitions

Source: https://floki.hexdocs.pm/Floki.HTMLParser.md

Behaviour callbacks that must be implemented by custom HTML parsers.

```elixir
@callback parse_document(html(), Keyword.t()) :: result(Floki.html_tree())
```

```elixir
@callback parse_document_with_attributes_as_maps(html(), Keyword.t()) ::
  result(Floki.html_tree())
```

```elixir
@callback parse_fragment(html(), Keyword.t()) :: result(Floki.html_tree())
```

```elixir
@callback parse_fragment_with_attributes_as_maps(html(), Keyword.t()) ::
  result(Floki.html_tree())
```

--------------------------------

### Floki.traverse_and_update(html_node | html_tree, fun)

Source: https://floki.hexdocs.pm/Floki.md

Traverses an HTML tree and applies a transformation function to each node (excluding text nodes). The function supports post-walk traversal, allowing for node modification, splitting, or deletion.

```APIDOC
## Function: Floki.traverse_and_update/2

### Description
Traverses and updates a HTML tree structure. This function returns a new tree structure that is the result of applying the given `fun` on all nodes except text nodes. The tree is traversed in a post-walk fashion, where the children are traversed before the parent.

### Signature
`traverse_and_update(html_node() | html_tree(), (html_node() -> html_node() | [html_node()] | nil)) :: html_node() | html_tree()`

### Parameters
- **html_node/tree** (html_node() | html_tree()) - The input HTML structure to traverse.
- **fun** ((html_node() -> html_node() | [html_node()] | nil)) - A function applied to each node. It receives a tuple representing the node and should return a modified tuple, a list of tuples (to split), or `nil` (to delete).

### Usage Example
```elixir
html = [{"div", [], ["hello"]}]
Floki.traverse_and_update(html, fn
  {"div", attrs, children} -> {"p", attrs, children}
  other -> other
end)
# Output: [{"p", [], ["hello"]}]
```
```

--------------------------------

### Add Floki to mix.exs

Source: https://floki.hexdocs.pm/readme.md

Include Floki in the dependencies list of your Elixir project.

```elixir
defp deps do
  [
    {:floki, "~> 0.38.0"}
  ]
end
```

--------------------------------

### Floki.raw_html/2

Source: https://floki.hexdocs.pm/Floki.md

Converts an HTML tree, node, or binary into a raw HTML string. Supports options for character encoding and pretty printing.

```APIDOC
## Floki.raw_html(html, options)

### Description
Converts an HTML tree to raw HTML. Note that the resultant HTML may be different from the original one as spaces after tags and doctypes are ignored.

### Parameters
- **html** (html_tree | html_node | binary) - Required - The HTML structure to convert.
- **options** (keyword) - Optional - Configuration options:
  - **:encode** (boolean) - Whether to encode special HTML characters. Defaults to true.
  - **:pretty** (boolean) - Whether to format the output with indentation. Defaults to false.
```

--------------------------------

### Floki.traverse_and_update/3

Source: https://floki.hexdocs.pm/Floki.md

Traverses and updates a HTML tree structure with an accumulator. The function applies a transformation function to all nodes except text nodes in a post-walk fashion.

```APIDOC
## Floki.traverse_and_update(html_node | html_tree, traverse_acc, fun)

### Description
Traverses and updates a HTML tree structure with an accumulator. This function returns a new tree structure and the final value of the accumulator after applying the provided function to all nodes except text nodes.

### Signature
`traverse_and_update(html_node() | html_tree(), traverse_acc, (html_node(), traverse_acc -> {html_node() | [html_node()] | nil, traverse_acc})) :: {html_node() | html_tree(), traverse_acc}`

### Parameters
- **html_node | html_tree** - The input HTML structure to traverse.
- **traverse_acc** - The initial accumulator value.
- **fun** - A function that receives a node and the current accumulator, returning a tuple containing the new node (or nil to delete) and the updated accumulator.

### Example
```elixir
iex> html = [{"div", [], [{:comment, "I am a comment"}, "hello"]}, {"div", [], ["world"]}]
iex> Floki.traverse_and_update(html, 0, fn
...>   {"div", attrs, children}, acc ->
...>     {{"p", [{"data-count", to_string(acc)} | attrs], children}, acc + 1}
...>   other, acc -> {other, acc}
...> end)
{[{"p", [{"data-count", "0"}], [{:comment, "I am a comment"}, "hello"]}, {"p", [{"data-count", "1"}], ["world"]}], 2}
```
```

--------------------------------

### Floki.parse_document!/2

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML document from a string and raises an error if parsing fails.

```APIDOC
## Floki.parse_document!(html_string, options)

### Description
Pareses a full HTML document from a string. Raises `Floki.ParseError` if parsing fails.

### Parameters
- **html_string** (binary) - Required - The HTML content to parse.
- **options** (Keyword.t) - Optional - Configuration options for the parser.

### Example
```elixir
Floki.parse_document!("<html><body>hello</body></html>")
```
```

--------------------------------

### Floki.attribute/3

Source: https://floki.hexdocs.pm/Floki.md

Returns a list of attribute values for elements matching a given CSS selector.

```APIDOC
## Floki.attribute(html_tree | html_node, selector, attribute_name)

### Description
Returns a list with attribute values for a given selector.

### Signature
`@spec attribute(html_tree() | html_node(), binary(), binary()) :: list()`

### Examples
```elixir
Floki.attribute([{"a", [{"href", "https://google.com"}], ["Google"]}], "a", "href")
# => ["https://google.com"]
```
```

--------------------------------

### Find elements using CSS selectors

Source: https://floki.hexdocs.pm/

Queries the parsed document for elements matching a specific CSS selector.

```elixir
Floki.find(document, ".example")
# => [{"div", [{"class", "example"}], []}]
```

--------------------------------

### Retrieve elements by ID with get_by_id

Source: https://floki.hexdocs.pm/Floki.md

Finds the first element matching a specific ID. Useful for IDs containing special characters that are invalid in CSS selectors.

```elixir
@spec get_by_id(html_tree() | html_node(), String.t()) :: html_node() | nil
```

```elixir
iex> {:ok, html} = Floki.parse_fragment(~s[<p><span class="hint" id="id?foo_special:chars">hello</span></p>])
iex> Floki.get_by_id(html, "id?foo_special:chars")
{"span", [{"class", "hint"}, {"id", "id?foo_special:chars"}], ["hello"]}
iex> Floki.get_by_id(html, "does-not-exist")
nil
```

--------------------------------

### Floki.parse_fragment!/2

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML fragment from a string and raises an error if parsing fails.

```APIDOC
## Floki.parse_fragment!(html_string, options)

### Description
Pareses an HTML fragment from a string. Raises `Floki.ParseError` if parsing fails.

### Parameters
- **html_string** (binary) - Required - The HTML fragment to parse.
- **options** (Keyword.t) - Optional - Configuration options.
```

--------------------------------

### Convert HTML tree to raw HTML string

Source: https://floki.hexdocs.pm/Floki.md

Converts an HTML tree structure into a raw HTML string. Note that the output may differ from the original due to whitespace normalization.

```elixir
@spec raw_html(
  html_tree() | html_node() | binary(),
  keyword()
) :: binary()
```

```elixir
iex> Floki.raw_html({"div", [{"class", "wrapper"}], ["my content"]})
~s(<div class="wrapper">my content</div>)
```

```elixir
iex> Floki.raw_html({"div", [{"class", "wrapper"}], ["10 > 5"]})
~s(<div class="wrapper">10 &gt; 5</div>)
```

```elixir
iex> Floki.raw_html({"div", [{"class", "wrapper"}], ["10 > 5"]}, encode: false)
~s(<div class="wrapper">10 > 5</div>)
```

```elixir
iex> Floki.raw_html({"div", [], ["\n   ", {"span", [], "Fully indented"}, "    \n"]}, pretty: true)
"""
<div>
  <span>
    Fully indented
  </span>
</div>
"""
```

--------------------------------

### Parse HTML document with Floki

Source: https://floki.hexdocs.pm/

Converts a raw HTML string into a traversable node tree structure.

```elixir
html = """
  <html>
  <body>
    <div class="example"></div>
  </body>
  </html>
"""

{:ok, document} = Floki.parse_document(html)
# => {:ok, [{"html", [], [{"body", [], [{"div", [{"class", "example"}], []}]}]}]}
```

--------------------------------

### Find elements with find

Source: https://floki.hexdocs.pm/Floki.md

Locates elements within an HTML tree using CSS selectors.

```elixir
iex> {:ok, html} = Floki.parse_fragment("<p><span class=hint>hello</span></p>")
iex> Floki.find(html, ".hint")
[{"span", [{"class", "hint"}], ["hello"]}]
```

```elixir
iex> {:ok, html} = Floki.parse_fragment("<div id=important><div>Content</div></div>")
iex> Floki.find(html, "#important")
[{"div", [{"id", "important"}], [{"div", [], ["Content"]}]}]
```

```elixir
iex> {:ok, html} = Floki.parse_fragment("<p><a href='https://google.com'>Google</a></p>")
iex> Floki.find(html, "a")
[{"a", [{"href", "https://google.com"}], ["Google"]}]
```

```elixir
iex> Floki.find([{ "div", [], [{"a", [{"href", "https://google.com"}], ["Google"]}]}], "div a")
[{"a", [{"href", "https://google.com"}], ["Google"]}]
```

--------------------------------

### Floki.parse_document/1

Source: https://floki.hexdocs.pm/

Parses a raw HTML string into a node tree structure.

```APIDOC
## Floki.parse_document(html)

### Description
Parses an HTML document string into a tuple containing the status and the parsed node tree.

### Parameters
- **html** (String) - Required - The raw HTML string to parse.

### Response
- **{:ok, document}** (Tuple) - Returns a tuple with the status and the parsed document structure.
```

--------------------------------

### Floki.parse_fragment/2

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML fragment from a string, returning an ok/error tuple.

```APIDOC
## Floki.parse_fragment(html_string, options)

### Description
Pareses a section or fragment of an HTML document.

### Parameters
- **html_string** (binary) - Required - The HTML fragment to parse.
- **options** (Keyword.t) - Optional - Configuration options:
  - `:attributes_as_maps` (boolean) - Return attributes as maps instead of lists.
  - `:html_parser` (module) - The backend parser module.
  - `:parser_args` (list) - Parser-specific arguments.

### Response
- Returns `{:ok, html_tree()}` on success or `{:error, String.t()}` on failure.
```

--------------------------------

### HTML Node Representation

Source: https://floki.hexdocs.pm/

The internal tuple structure used by Floki to represent parsed HTML nodes.

```elixir
{tag_name, attributes, children_nodes}
```

```elixir
{"p", [{"class", "headline"}], ["Floki"]}
```

--------------------------------

### Floki.children/2

Source: https://floki.hexdocs.pm/Floki.md

Returns the direct child nodes of a HTML node.

```APIDOC
## Floki.children(html_node, options)

### Description
Returns the direct child nodes of a HTML node. By default, it includes all text nodes, which can be disabled using the `include_text` option.

### Signature
`@spec children(html_node(), Keyword.t()) :: html_tree() | nil`

### Options
- **include_text** (boolean) - Optional - Whether to include text nodes in the result. Defaults to true.

### Examples
```elixir
Floki.children({"div", [], ["text", {"span", [], []}]}, include_text: false)
# => [{"span", [], []}]
```
```

--------------------------------

### find_and_update/3

Source: https://floki.hexdocs.pm/Floki.md

Searches for elements inside the HTML tree matching a CSS selector and updates them using a provided function. If the function returns :delete, the node is removed.

```APIDOC
## find_and_update(html_tree, css_selector, fun)

### Description
Searches for elements inside the HTML tree and updates those that match the selector. It returns the updated HTML tree.

### Parameters
- **html_tree** (html_tree()) - The HTML tree to search.
- **css_selector** (css_selector()) - The CSS selector to match nodes.
- **fun** (({String.t(), html_attributes()} -> {String.t(), html_attributes()} | :delete)) - A function that receives the tag and attributes of a matching node and returns the updated version or :delete to remove the node.
```

--------------------------------

### Parse HTML document

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML string into a tuple-based representation using Floki.parse_document/1.

```elixir
{:ok, html} = Floki.parse_document(doc)
# =>
# [{"html", [],
#   [
#     {"body", [],
#      [
#        {"section", [{"id", "content"}],
#         [
#           {"p", [{"class", "headline"}], ["Floki"]},
#           {"a", [{"href", "http://github.com/philss/floki"}], ["Github page"]},
#           {"span", [{"data-model", "user"}], ["philss"]}
#         ]}
#      ]}
#   ]}]
```

--------------------------------

### Deleting and Modifying Nodes

Source: https://floki.hexdocs.pm/Floki.md

Shows how to remove specific nodes and transform comments into tags during tree traversal.

```elixir
iex> html = [{"div", [], [{:comment, "I am comment"}, {"span", [], ["hello"]}]}]
iex> Floki.traverse_and_update(html, fn
...>   {"span", _attrs, _children} -> nil
...>   {:comment, text} -> {"span", [], text}
...>   other -> other
...> end)
[{"div", [], [{"span", [], "I am comment"}]}]
```

--------------------------------

### find/2

Source: https://floki.hexdocs.pm/Floki.md

Finds elements inside an HTML tree based on a CSS selector.

```APIDOC
## find(html_tree | html_node, css_selector)

### Description
Find elements inside an HTML tree.

### Signature
`find(html_tree() | html_node(), css_selector()) :: html_tree()`

### Examples
```elixir
{:ok, html} = Floki.parse_fragment("<p><span class=hint>hello</span></p>")
Floki.find(html, ".hint") # => [{"span", [{"class", "hint"}], ["hello"]}]
```
```

--------------------------------

### Floki.text/1

Source: https://floki.hexdocs.pm/

Extracts the text content from a node or list of nodes.

```APIDOC
## Floki.text(nodes)

### Description
Retrieves the text content from the provided nodes.

### Parameters
- **nodes** (Term) - Required - The node or list of nodes to extract text from.
```

--------------------------------

### Floki.find/2

Source: https://floki.hexdocs.pm/

Finds elements within a document or node tree that match a given CSS selector.

```APIDOC
## Floki.find(document, selector)

### Description
Queries the provided document or node tree for elements matching the specified CSS selector.

### Parameters
- **document** (Term) - Required - The parsed document or node tree.
- **selector** (String) - Required - The CSS selector string to match elements against.

### Response
- **List** - Returns a list of matching nodes.
```

--------------------------------

### Convert node tree to raw HTML

Source: https://floki.hexdocs.pm/

Transforms a filtered node tree back into a raw HTML string.

```elixir
document
|> Floki.find(".example")
|> Floki.raw_html()
# =>  <div class="example"></div>
```

--------------------------------

### Floki.attribute/2-3

Source: https://floki.hexdocs.pm/readme.md

Extracts attributes from elements.

```APIDOC
## Floki.attribute(document, selector, attribute)
## Floki.attribute(nodes, attribute)

### Description
Retrieves the value of a specific attribute from elements found via selector or from a provided list of nodes.

### Parameters
- **document/nodes** (Term) - Required - The document or list of nodes.
- **selector** (String) - Optional - The CSS selector to filter elements.
- **attribute** (String) - Required - The name of the attribute to retrieve.
```

--------------------------------

### Extract attributes by selector

Source: https://floki.hexdocs.pm/Floki.md

Retrieves attribute values for elements matching a specific CSS selector.

```elixir
iex> Floki.attribute([{"a", [{"href", "https://google.com"}], ["Google"]}], "a", "href")
["https://google.com"]
```

```elixir
iex> Floki.attribute(
iex>   [{"a", [{"class", "foo"}, {"href", "https://google.com"}], ["Google"]}],
iex>   "a",
iex>   "class"
iex> )
["foo"]
```

```elixir
iex> Floki.attribute(
iex>   [{"a", [{"href", "https://e.corp.com"}, {"data-name", "e.corp"}], ["E.Corp"]}],
iex>   "a[data-name]",
iex>   "data-name"
iex> )
["e.corp"]
```

--------------------------------

### HTML Type Definitions

Source: https://floki.hexdocs.pm/Floki.md

Core type definitions for representing HTML structures including nodes, tags, attributes, and trees.

```elixir
@type html_attribute() :: {String.t(), String.t()}
```

```elixir
@type html_attributes() :: [html_attribute()] | html_attributes_map()
```

```elixir
@type html_attributes_map() :: %{required(String.t()) => String.t()}
```

```elixir
@type html_comment() :: {:comment, String.t()}
```

```elixir
@type html_declaration() :: {:pi, String.t(), html_attributes()}
```

```elixir
@type html_doctype() :: {:doctype, String.t(), String.t(), String.t()}
```

```elixir
@type html_node() ::
  html_tag()
  | html_comment()
  | html_doctype()
  | html_declaration()
  | html_text()
```

```elixir
@type html_tag() :: {String.t(), html_attributes(), [html_node()]}
```

```elixir
@type html_text() :: String.t()
```

```elixir
@type html_tree() :: [html_node()]
```

--------------------------------

### Function Specification

Source: https://floki.hexdocs.pm/Floki.md

Defines the type signature for the traverse_and_update function.

```elixir
@spec traverse_and_update(
  html_node() | html_tree(),
  (html_node() -> html_node() | [html_node()] | nil)
) :: html_node() | html_tree()
```

--------------------------------

### Parse HTML Fragment with parse_fragment

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML fragment, returning an ok/error tuple. Supports custom attributes as maps and alternative backend parsers.

```elixir
@spec parse_fragment(binary(), Keyword.t()) ::
  {:ok, html_tree()} | {:error, String.t()}
```

--------------------------------

### Floki.attr/4

Source: https://floki.hexdocs.pm/Floki.md

Changes the attribute values of the elements matched by a CSS selector using a mutation function and returns the modified element tree.

```APIDOC
## Floki.attr(tree, selector, attribute, mutation)

### Description
Changes the attribute values of the elements matched by `selector` with the function `mutation` and returns the whole element tree.

### Parameters
- **tree** (html_tree | html_node) - The HTML tree or node to modify.
- **selector** (css_selector) - The CSS selector to match elements.
- **attribute** (binary) - The name of the attribute to modify.
- **mutation** ((binary -> binary)) - A function that takes the current attribute value and returns the new value.

### Returns
- **html_tree** - The modified HTML tree.

### Example
```elixir
Floki.attr([{"div", [{"id", "a"}], []}], "#a", "id", fn(id) -> String.replace(id, "a", "b") end)
# => [{"div", [{"id", "b"}], []}]
```
```

--------------------------------

### Floki.text/2

Source: https://floki.hexdocs.pm/Floki.md

Extracts text nodes from an HTML tree. Supports deep search, inclusion of script/style tags, custom separators, and input field values.

```APIDOC
## Floki.text(html, options)

### Description
Returns the text nodes from an HTML tree. By default, it performs a deep search through the tree.

### Parameters
- **html** (html_tree | html_node) - Required - The HTML structure to extract text from.
- **options** (Keyword.t) - Optional - Configuration options:
  - **:deep** (boolean) - Whether to perform a deep search. Defaults to true.
  - **:js** (boolean) - Whether to include content of <script> tags. Defaults to false.
  - **:style** (boolean) - Whether to include content of <style> tags. Defaults to true.
  - **:sep** (string) - Separator string added between text nodes. Defaults to "".
  - **:include_inputs** (boolean) - Whether to include <input> or <textarea> values. Defaults to false.
```

--------------------------------

### Define CSS selector type

Source: https://floki.hexdocs.pm/Floki.md

The type definition for CSS selectors supported by Floki.

```elixir
@type css_selector() ::
  String.t()
  | %Floki.Selector{
      attributes: term(),
      classes: term(),
      combinator: term(),
      id: term(),
      namespace: term(),
      pseudo_classes: term(),
      type: term()
    }
  | [
      %Floki.Selector{
        attributes: term(),
        classes: term(),
        combinator: term(),
        id: term(),
        namespace: term(),
        pseudo_classes: term(),
        type: term()
      }
    ]
```

--------------------------------

### Parse HTML document specification

Source: https://floki.hexdocs.pm/Floki.md

Type specification for the parse_document function.

```elixir
@spec parse_document(binary(), Keyword.t()) ::
  {:ok, html_tree()} | {:error, String.t()}
```

--------------------------------

### Escape CSS identifiers with css_escape

Source: https://floki.hexdocs.pm/Floki.md

Escapes a string for safe use as a CSS identifier.

```elixir
iex> Floki.css_escape("hello world")
"hello\\ world"
```

```elixir
iex> Floki.css_escape("-123")
"-\\31 23"
```

--------------------------------

### Extract text content from elements

Source: https://floki.hexdocs.pm/

Retrieves the inner text content from a selected element.

```elixir
document
|> Floki.find(".headline")
|> Floki.text()

# => "Floki"
```

--------------------------------

### get_by_id/2

Source: https://floki.hexdocs.pm/Floki.md

Finds the first element in an HTML tree by its ID attribute, handling special characters that might be invalid in CSS selectors.

```APIDOC
## get_by_id(html_tree_or_node, id)

### Description
Finds the first element in an HTML tree by id. Returns nil if no element is found.

### Parameters
- **html_tree_or_node** (html_tree() | html_node()) - The HTML tree or node to search within.
- **id** (String.t()) - The ID string to search for.
```

--------------------------------

### css_escape/1

Source: https://floki.hexdocs.pm/Floki.md

Escapes a string for use as a CSS identifier.

```APIDOC
## css_escape(string)

### Description
Escapes a string for use as a CSS identifier.

### Signature
`css_escape(String.t()) :: String.t()`

### Examples
```elixir
Floki.css_escape("hello world") # => "hello\\ world"
Floki.css_escape("-123") # => "-\\31 23"
```
```

--------------------------------

### Retrieve child nodes

Source: https://floki.hexdocs.pm/Floki.md

Returns direct child nodes of an HTML node, with an option to exclude text nodes.

```elixir
iex> Floki.children({"div", [], ["text", {"span", [], []}]})
["text", {"span", [], []}]
```

```elixir
iex> Floki.children({"div", [], ["text", {"span", [], []}]}, include_text: false)
[{"span", [], []}]
```

```elixir
iex> Floki.children({:comment, "comment"})
nil
```

--------------------------------

### Extract attributes from elements

Source: https://floki.hexdocs.pm/Floki.md

Retrieves a list of attribute values from the provided HTML tree or node.

```elixir
iex> Floki.attribute([{"a", [{"href", "https://google.com"}], ["Google"]}], "href")
["https://google.com"]
```

```elixir
iex> Floki.attribute([{"a", [{"href", "https://google.com"}, {"data-name", "google"}], ["Google"]}], "data-name")
["google"]
```

--------------------------------

### parse_document/2

Source: https://floki.hexdocs.pm/Floki.md

Parses an HTML document from a string into an HTML tree structure.

```APIDOC
## parse_document(binary(), Keyword.t())

### Description
Parses an HTML document from a string. This is the main function to get a tree from an HTML string.

### Signature
`parse_document(html_string, options)`

### Parameters
- **html_string** (binary) - Required - The HTML content to parse.
- **options** (Keyword.t) - Optional - Configuration options for the parser.
  - **:attributes_as_maps** (boolean) - Optional - If true, returns attributes as maps instead of lists. Default: false.
  - **:html_parser** (module) - Optional - The backend module responsible for parsing. Default: Floki.HTMLParser.Mochiweb.
  - **:parser_args** (list) - Optional - Parser-specific arguments. Default: [].

### Returns
- `{:ok, html_tree()}` on success.
- `{:error, String.t()}` on failure.

### Example
```elixir
Floki.parse_document("<html><body>hello</body></html>")
# => {:ok, [{"html", [], [{"body", [], ["hello"]}]}]}
```
```

--------------------------------

### Define traverse_and_update specification

Source: https://floki.hexdocs.pm/Floki.md

Type specification for the traverse_and_update function.

```elixir
@spec traverse_and_update(
  html_node() | html_tree(),
  traverse_acc,
  (html_node(), traverse_acc ->
     {html_node() | [html_node()] | nil, traverse_acc})
) :: {html_node() | html_tree(), traverse_acc}
when traverse_acc: any()
```

--------------------------------

### Update HTML elements with find_and_update

Source: https://floki.hexdocs.pm/Floki.md

Updates tags and attributes of nodes matching a CSS selector. Returning :delete from the callback function removes the node from the tree.

```elixir
@spec find_and_update(
  html_tree(),
  css_selector(),
  ({String.t(), html_attributes()} -> {String.t(), html_attributes()} | :delete)
) :: html_tree()
```

```elixir
iex> Floki.find_and_update([{"a", [{"href", "http://elixir-lang.com"}], ["Elixir"]}], "a", fn
iex>   {"a", [{"href", href}]} ->
iex>     {"a", [{"href", String.replace(href, "http://", "https://")}]}
iex>   other ->
iex>     other
iex> end)
[{"a", [{"href", "https://elixir-lang.com"}], ["Elixir"]}]
```

--------------------------------

### Extract attributes from elements

Source: https://floki.hexdocs.pm/

Retrieves specific attribute values from elements found within the document.

```elixir
Floki.attribute(document, ".example", "class")
# => ["example"]
```

```elixir
document
|> Floki.find(".example")
|> Floki.attribute("class")
# => ["example"]
```

--------------------------------

### Modify HTML Attributes with Floki.attr/4

Source: https://floki.hexdocs.pm/Floki.md

Updates attribute values for elements matching a CSS selector using a mutation function.

```elixir
@spec attr(html_tree() | html_node(), css_selector(), binary(), (binary() -> binary())) ::
  html_tree()
```

```elixir
iex> Floki.attr([{"div", [{"id", "a"}], []}], "#a", "id", fn(id) -> String.replace(id, "a", "b") end)
[{"div", [{"id", "b"}], []}]
```

```elixir
iex> Floki.attr([{"div", [{"class", "name"}], []}], "div", "id", fn _ -> "b" end)
[{"div", [{"id", "b"}, {"class", "name"}], []}]
```

--------------------------------

### Floki.attribute/3

Source: https://floki.hexdocs.pm/

Extracts the value of a specific attribute from elements matching a selector.

```APIDOC
## Floki.attribute(document, selector, attribute)

### Description
Retrieves the values of a specified attribute from elements found by the selector within the document.

### Parameters
- **document** (Term) - Required - The parsed document or node tree.
- **selector** (String) - Required - The CSS selector to find elements.
- **attribute** (String) - Required - The name of the attribute to extract.
```

--------------------------------

### filter_out/2

Source: https://floki.hexdocs.pm/Floki.md

Returns the nodes from a HTML tree that do not match the provided filter selector.

```APIDOC
## filter_out(html_node | html_tree, filter)

### Description
Returns the nodes from a HTML tree that don't match the filter selector.

### Signature
`filter_out(html_node() | html_tree(), :comment | :text | css_selector()) :: html_node() | html_tree()`

### Examples
```elixir
Floki.filter_out({"div", [], [{"script", [], ["hello"]}, " world"]}, "script") # => {"div", [], [" world"]}
Floki.filter_out({"div", [], [{:comment, "comment"}, " text"]}, :comment) # => {"div", [], [" text"]}
```
```

--------------------------------

### Extract text nodes from HTML tree

Source: https://floki.hexdocs.pm/Floki.md

Extracts text content from an HTML tree, supporting deep search and optional inclusion of script or style tag contents.

```elixir
@spec text(html_tree() | html_node(), Keyword.t()) :: binary()
```

```elixir
iex> Floki.text({"div", [], [{"span", [], ["hello"]}, " world"]})
"hello world"
```

```elixir
iex> Floki.text({"div", [], [{"span", [], ["hello"]}, " world"]}, deep: false)
" world"
```

```elixir
iex> Floki.text({"div", [], [{"script", [], ["hello"]}, " world"]})
" world"
```

```elixir
iex> Floki.text([{"input", [{"type", "date"}, {"value", "2017-06-01"}], []}], include_inputs: true)
"2017-06-01"
```

```elixir
iex> Floki.text({"div", [], [{"script", [], ["hello"]}, " world"]}, js: true)
"hello world"
```

```elixir
iex> Floki.text({"ul", [], [{"li", [], ["hello"]}, {"li", [], ["world"]}]}, sep: "-")
"hello-world"
```

```elixir
iex> Floki.text([{"div", [], ["hello world"]}])
"hello world"
```

```elixir
iex> Floki.text([{"p", [], ["1"]},{"p", [], ["2"]}])
"12"
```

```elixir
iex> Floki.text({"div", [], [{"style", [], ["hello"]}, " world"]}, style: false)
" world"
```

```elixir
iex> Floki.text({"div", [], [{"style", [], ["hello"]}, " world"]}, style: true)
"hello world"
```

--------------------------------

### Filter HTML nodes with filter_out

Source: https://floki.hexdocs.pm/Floki.md

Removes nodes from an HTML tree that match the provided selector or type.

```elixir
iex> Floki.filter_out({"div", [], [{"script", [], ["hello"]}, " world"]}, "script")
{"div", [], [" world"]}
```

```elixir
iex> Floki.filter_out([{"body", [], [{"script", [], []}, {"div", [], []}]}], "script")
[{"body", [], [{"div", [], []}]}]
```

```elixir
iex> Floki.filter_out({"div", [], [{:comment, "comment"}, " text"]}, :comment)
{"div", [], [" text"]}
```

```elixir
iex> Floki.filter_out({"div", [], ["text"]}, :text)
{"div", [], []}
```
Tokens:
Raw