@type attr_key() :: any()

An attribute key (i.e. %Value{}) can be anything, normally it will be an id or string though

@type attr_value() :: any()

An attribute value can be anything

@type document() :: Kuddle.Decoder.document()

A Kuddle document is a list of nodes, nothing fancy.

@type document_node() :: Kuddle.Decoder.document_node()

A single node in a document

@type node_attributes() :: [attribute_path() | {any(), any()} | any()]

In addition to the attribute_path, node attributes can also use shorthands for {:attr, key, value} and {:value, value}, as {key, value} and value respectively.

@type node_name() :: String.t()

Node names are strings

@type path() :: [selector()]

A path is a list of selectors that should be used when matching against the document.

It allows different fragments which can be used to match different properties of the node.

Fragments:

• node_name - the node name can be passed as a plain string in the path to select a node based on its name

  Example:

  [%Kuddle.Node{name: "node"}] = Kuddle.select(document, ["node"])
  [] = Kuddle.select(document, ["doesnt_exist"])

• {:attr, key} - a node with an attribute key can be looked up as well, this will ignore the

               value and only look for key value pairs with the key

  Example:

  [%Kuddle.Node{attributes: [{%{value: "id"}, _value}]}] = Kuddle.select(document, [{:attr, "id"}])
  [] = Kuddle.select(document, [{:attr, "cid"}])

• {:attr, key, value} - an attribute of key and value can be looked up as well

  Example:

  [%Kuddle.Node{attributes: [{%{value: "id"}, %{value: "egg"}}]}] = Kuddle.select(document, [{:attr, "id", "egg"}])
  [] = Kuddle.select(document, [{:attr, "cid", "8847"}])

• {:value, value} - for nodes with normal values, the loose value can be looked up as well

  Example:

  [%Kuddle.Node{attributes: [%{value: 1}]}] = Kuddle.select(document, [{:value, 1}])
  [] = Kuddle.select(document, [{:value, 2}])

• {:node, node_name} - equivalent to just providing the node_name

  Example:

  [%Kuddle.Node{name: "node"}] = Kuddle.select(document, [{:node, "node"}])
  [] = Kuddle.select(document, [{:node, "doesnt_exist"}])

• {:node, node_name, attrs} - lookup a node with attributes

  Example:

  [%Kuddle.Node{name: "node", attributes: [1]}] = Kuddle.select(document, [{:node, "node", [1]}])
  [%Kuddle.Node{name: "node", attributes: [1]}] = Kuddle.select(document, [{:node, "node", [{:value, 1}]}])
  [%Kuddle.Node{name: "node2", attributes: [{%{value: "id"}, _value}]}] = Kuddle.select(document, [{:node, "node2", [{:attr, "id"}]}])
  [%Kuddle.Node{name: "node3", attributes: [{%{value: "id"}, %{value: "bacon"}}]}] = Kuddle.select(document, [{:node, "node3", [{:attr, "id", "bacon"}]}])
  [%Kuddle.Node{name: "node3", attributes: [{%{value: "id"}, %{value: "bacon"}}]}] = Kuddle.select(document, [{:node, "node3", [{"id", "bacon"}]}])
  [] = Kuddle.select(document, [{:node, "node3", [{"id", "fries"}]}])

@type selector() ::
  node_name()
  | attribute_path()
  | {:node, node_name()}
  | {:node, node_name(), node_attributes()}

Any single path selector