defmodule XmlQuery do
  # @related [tests](test/xml_query_test.exs)

  @moduledoc """
  A concise API for querying XML. XML parsing is handled by Erlang/OTP’s built-in
  [xmerl](https://www.erlang.org/doc/man/xmerl) library.

  We created a related library called [HtmlQuery](https://hexdocs.pm/html_query/readme.html) which has the same API but
  is used for querying HTML. You can read more about them in
  [Querying HTML and XML in Elixir with HtmlQuery and XmlQuery](https://eahanson.com/articles/html-query-xml-query).

  ## Data types

  All functions accept XML in the form of a string, an `Xmerl.xml_attribute`, an `Xmerl.xml_document`, an
  `Xmerl.xml_element`, an `Xmler.xml_text`, an `XmlQuery.Element`, or anything that implements the `String.Chars`
  protocol.

  ## Query functions

  | `all/2`   | return all elements matching the selector                   |
  | `find/2`  | return the first element that matches the selector          |
  | `find!/2` | return the only element that matches the selector, or raise |

  ## Extraction functions

  | `attr/2` | returns the attribute value as a string      |
  | `text/1` | returns the text contents as a single string |

  ## Parsing & utility functions

  | `parse/1` | parses XML into an `XmlQuery.Element`, `XmlQuery.Attribute`, or XmlQuery.Text.t() |
  | `pretty/1` | prettifies XML |

  ## Alias

  If you use XmlQuery a lot, you may want to alias it to the recommended shortcut "Xq":

  ```elixir
  alias XmlQuery, as: Hq
  ```
  """

  import Record
  alias XmlQuery.QueryError
  alias XmlQuery.Xmerl
  require XmlQuery.Xmerl

  @type xml() :: xml_binary() | xml_document() | xml_element() | XmlQuery.Element.t() | String.Chars.t()
  @type xml_attribute() :: Xmerl.xml_attribute()
  @type xml_binary() :: binary()
  @type xml_document() :: Xmerl.xml_document()
  @type xml_element() :: Xmerl.xml_element()
  @type xml_text() :: Xmerl.xml_text()
  @type xpath() :: binary() | charlist()

  @module_name __MODULE__ |> Module.split() |> Enum.join(".")

  defguard is_xml_struct(struct)
           when is_struct(struct) and
                  struct.__struct__ in [XmlQuery.Attribute, XmlQuery.Element, XmlQuery.Text]

  @doc """
  Finds all elements in an XML document that match `xpath`, returning a list of records.
  Depending on the given xpath, the type of the record may be different.

  ``` elixir
  iex> xml = ~s|<cart id="123"> <fruit name="apple" color="red"/> <fruit name="banana" color="yellow"/> </cart>|
  iex> XmlQuery.all(xml, "//fruit") |> Enum.map(&to_string/1)
  ["<fruit name=\\"apple\\" color=\\"red\\"/>",
   "<fruit name=\\"banana\\" color=\\"yellow\\"/>"]
  ```
  """
  @spec all(xml(), xpath()) :: [XmlQuery.Element.t()]
  def all(xml, xpath) when is_binary(xpath),
    do: xml |> all(String.to_charlist(xpath))

  def all(xml, xpath) when is_binary(xml) or is_tuple(xml),
    do: xml |> parse() |> all(xpath)

  def all(xml, xpath) when is_struct(xml),
    do: :xmerl_xpath.string(xpath, xml.shadows) |> Enum.map(&into/1)

  @doc """
  Returns the value of `attr` from the outermost element of `xml`.

  ``` elixir
  iex> xml = ~s|<cart id="123"> <fruit name="apple" color="red"/> <fruit name="banana" color="yellow"/> </cart>|
  iex> XmlQuery.attr(xml, :id)
  "123"
  ```
  """
  @spec attr(xml(), String.t()) :: XmlQuery.Attribute.t() | nil
  def attr(xml, attr) do
    case xml
         |> parse()
         |> first!("Consider using Enum.map(xml, &#{@module_name}.attr(&1, #{inspect(attr)}))")
         |> find("@#{attr}") do
      %XmlQuery.Attribute{value: value} -> to_string(value)
      nil -> nil
    end
  end

  @doc """
  Finds the first element, attribute, or element text in `xml` that matches `xpath`.

  ``` elixir
  iex> alias XmlQuery, as: Xq
  iex> xml = \"""
  ...> <?xml version="1.0"?>
  ...> <root><child property="oldest" /><child property="youngest" /></root>
  ...> \"""
  iex> %Xq.Element{name: :child, attributes: [%Xq.Attribute{value: ~c"oldest"}]} = Xq.find(xml, "//child")

  ```
  """
  @spec find(xml(), xpath()) :: XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t() | nil
  def find(xml, xpath),
    do: xml |> all(xpath) |> List.first()

  @doc """
  Like `find/2` but raises unless exactly one node is found.
  """
  @spec find!(xml(), xpath()) :: XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t()
  def find!(xml, xpath),
    do: all(xml, xpath) |> first!("XPath: #{xpath}")

  @doc """
  Parses an XML document using `:xmerl_scan.string/2`, returning an `XmlQuery.Element` struct.

  Given an xml tuple that has already been created by `:xmerl`, wraps the tuple in an
  `XmlQuery`-specific struct.

  ``` elixir
  iex> xml = \"""
  ...> <?xml version="1.0"?>
  ...> <root />
  ...> \"""
  iex> %Xq.Element{name: :root} = XmlQuery.parse(xml)

  iex> xml = \"""
  ...> <?xml version="1.0"?>
  ...> <root property="root-value" />
  ...> \"""
  iex> %Xq.Attribute{name: :property, value: ~c"root-value"} = XmlQuery.find(xml, "//root/@property") |> XmlQuery.parse()

  ```
  """
  @spec parse(xml()) :: XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t()
  def parse(node) when is_xml_struct(node),
    do: node

  def parse([node | _] = list) when is_xml_struct(node),
    do: list

  def parse(xml) when is_tuple(xml),
    do: xml |> into()

  def parse(xml) when is_binary(xml) do
    {doc, []} =
      xml
      |> String.to_charlist()
      |> :xmerl_scan.string(acc_fun: &accumulate_xml/3, quiet: true, space: :normalize, xmlbase: ~c"/")

    into(doc)
  end

  def parse(%_{} = xml),
    do: xml |> implements!(String.Chars) |> to_string() |> parse()

  @doc """
  Returns `xml` as a prettified string.

  Elements and text nodes are sorted and indented relative to parent elements.
  """
  @spec pretty(xml()) :: binary()
  def pretty(node)
      when is_struct(node, XmlQuery.Element) or is_struct(node, XmlQuery.Attribute) or is_struct(node, XmlQuery.Text),
      do: node.__struct__.pretty(node)

  def pretty(xml) when is_binary(xml) or is_tuple(xml),
    do: xml |> parse() |> pretty()

  @doc """
  Returns the text value of `xml`.

  ``` elixir
  iex> xml = "<name><first>Alice</first><middle>A.</middle><last>Aliceston</last></name>"
  iex> XmlQuery.text(xml)
  "Alice A. Aliceston"
  iex> xml |> XmlQuery.find("//name/first") |> XmlQuery.text()
  "Alice"
  ```
  """
  @spec text(xml()) :: binary()
  def text(xml) do
    case xml
         |> parse()
         |> first!("Consider using Enum.map(xml, &#{@module_name}.text/1)") do
      %XmlQuery.Element{shadows: doc} ->
        :xmerl_xpath.string(~c"//text()", doc)
        |> Enum.reduce("", fn node, acc ->
          case XmlQuery.Text.to_string(node) do
            "" -> acc
            text -> String.trim(acc <> " " <> text)
          end
        end)
    end
  end

  # # #

  @doc false
  def into(nil), do: nil

  def into(attribute) when is_record(attribute, :xmlAttribute),
    do: XmlQuery.Attribute.new(attribute)

  def into(element) when is_record(element, :xmlElement),
    do: XmlQuery.Element.new(element)

  def into(text) when is_record(text, :xmlText),
    do: XmlQuery.Text.new(text)

  # # #

  defp accumulate_xml({:xmlText, _, _, _, ~c" ", _} = text, acc, str) do
    {acc, XmlQuery.Xmerl.xmlText(text, :pos), str}
  end

  defp accumulate_xml(node, acc, str),
    do: {[node | acc], str}

  defp first!([], hint) do
    raise(QueryError, """
    Expected a single XML element but found none.

    #{hint}
    """)
  end

  defp first!([element], _hint),
    do: element

  defp first!(node, _hint) when is_xml_struct(node),
    do: node

  defp first!(_xml, hint) do
    raise QueryError, """
    Expected a single XML node but found multiple:

    #{hint}
    """
  end

  defp implements!(x, protocol) do
    if protocol.impl_for(x) == nil,
      do: raise("Expected #{inspect(x)} to implement protocol #{inspect(protocol)}"),
      else: x
  end
end