rdf-ex/lib/rdf/query.ex

defmodule RDF.Query do
  @moduledoc """
  The RDF Graph query API.
  """

  alias RDF.Graph
  alias RDF.Query.{BGP, Builder}

  @default_matcher RDF.Query.BGP.Stream

  @doc """
  Execute the given `query` against the given `graph`.

  The `query` can be given directly as `RDF.Query.BGP` struct created with one
  of the builder functions in this module or as basic graph pattern expression
  accepted by `bgp/1`.

  The result is a list of maps with the  solutions for the variables in the graph
  pattern query and will be returned in a `:ok` tuple. In case of an error a
  `:error` tuple is returned.

  ## Example

  Let's assume we have an `example_graph` with these triples:

  ```turtle
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix ex:   <http://example.com/> .

  ex:Outlaw
    foaf:name   "Johnny Lee Outlaw" ;
    foaf:mbox   <mailto:jlow@example.com> .

  ex:Goodguy
    foaf:name   "Peter Goodguy" ;
    foaf:mbox   <mailto:peter@example.org> ;
    foaf:friend ex:Outlaw .
  ```

      iex> {:_, FOAF.name, :name?} |> RDF.Query.execute(example_graph())
      {:ok, [%{name: ~L"Peter Goodguy"}, %{name: ~L"Johnny Lee Outlaw"}]}

      iex> [
      ...>   {:_, FOAF.name, :name?},
      ...>   {:_, FOAF.mbox, :mbox?},
      ...> ] |> RDF.Query.execute(example_graph())
      {:ok, [
        %{name: ~L"Peter Goodguy", mbox: ~I<mailto:peter@example.org>},
        %{name: ~L"Johnny Lee Outlaw", mbox: ~I<mailto:jlow@example.com>}
      ]}

      iex> query = [
      ...>   {:_, FOAF.name, :name?},
      ...>   {:_, FOAF.mbox, :mbox?},
      ...> ] |> RDF.Query.bgp()
      ...> RDF.Query.execute(query, example_graph())
      {:ok, [
        %{name: ~L"Peter Goodguy", mbox: ~I<mailto:peter@example.org>},
        %{name: ~L"Johnny Lee Outlaw", mbox: ~I<mailto:jlow@example.com>}
      ]}

      iex> [
      ...>   EX.Goodguy, FOAF.friend, FOAF.name, :name?
      ...> ] |> RDF.Query.path() |> RDF.Query.execute(example_graph())
      {:ok, [%{name: ~L"Johnny Lee Outlaw"}]}

  """
  def execute(query, graph, opts \\ [])

  def execute(%BGP{} = query, %Graph{} = graph, opts) do
    matcher = Keyword.get(opts, :matcher, @default_matcher)
    {:ok, matcher.execute(query, graph, opts)}
  end

  def execute(query, graph, opts) do
    with {:ok, bgp} <- Builder.bgp(query) do
      execute(bgp, graph, opts)
    end
  end

  @doc """
  Execute the given `query` against the given `graph`.

  As opposed to `execute/3` this returns the results directly or fails with an
  exception.
  """
  def execute!(query, graph, opts \\ []) do
    case execute(query, graph, opts) do
      {:ok, results} -> results
      {:error, error} -> raise error
    end
  end

  @doc """
  Returns a `Stream` for the execution of the given `query` against the given `graph`.

  Just like on `execute/3` the `query` can be given directly as `RDF.Query.BGP` struct
  created with one of the builder functions in this module or as basic graph pattern
  expression accepted by `bgp/1`.

  The stream of solutions for variable bindings will be returned in a `:ok` tuple.
  In case of an error a `:error` tuple is returned.

  ## Example

  Let's assume we have an `example_graph` with these triples:

  ```turtle
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix ex:   <http://example.com/> .

  ex:Outlaw
    foaf:name   "Johnny Lee Outlaw" ;
    foaf:mbox   <mailto:jlow@example.com> .

  ex:Goodguy
    foaf:name   "Peter Goodguy" ;
    foaf:mbox   <mailto:peter@example.org> ;
    foaf:friend ex:Outlaw .
  ```

      iex> {:ok, stream} = {:_, FOAF.name, :name?} |> RDF.Query.stream(example_graph())
      ...> Enum.to_list(stream)
      [%{name: ~L"Peter Goodguy"}, %{name: ~L"Johnny Lee Outlaw"}]

      iex> {:ok, stream} = [
      ...>   {:_, FOAF.name, :name?},
      ...>   {:_, FOAF.mbox, :mbox?},
      ...> ] |> RDF.Query.stream(example_graph())
      ...> Enum.take(stream, 1)
      [
        %{name: ~L"Peter Goodguy", mbox: ~I<mailto:peter@example.org>},
      ]

  """
  def stream(query, graph, opts \\ [])

  def stream(%BGP{} = query, %Graph{} = graph, opts) do
    matcher = Keyword.get(opts, :matcher, @default_matcher)
    {:ok, matcher.stream(query, graph, opts)}
  end

  def stream(query, graph, opts) do
    with {:ok, bgp} <- Builder.bgp(query) do
      stream(bgp, graph, opts)
    end
  end

  @doc """
  Returns a `Stream` for the execution of the given `query` against the given `graph`.

  As opposed to `stream/3` this returns the stream directly or fails with an
  exception.
  """
  def stream!(query, graph, opts \\ []) do
    case stream(query, graph, opts) do
      {:ok, results} -> results
      {:error, error} -> raise error
    end
  end

  @doc """
  Creates a `RDF.Query.BGP` struct.

  A basic graph pattern consist of single or list of triple patterns.
  A triple pattern is a tuple which consists of RDF terms or variables for
  the subject, predicate and object of a RDF triple.

  As RDF terms `RDF.IRI`s, `RDF.BlankNode`s, `RDF.Literal`s or all Elixir
  values which can be coerced to any of those are allowed, i.e.
  `RDF.Vocabulary.Namespace` atoms or Elixir values which can be coerced to RDF
  literals with `RDF.Literal.coerce/1` (only on object position). On predicate
  position the `:a` atom can be used for the `rdf:type` property.

  Variables are written as atoms ending with a question mark. Blank nodes which
  in a graph query patterns act like a variable which doesn't show up in the
  results can be written as atoms starting with an underscore.

  Here's a basic graph pattern example:

  ```elixir
  [
    {:s?, :a, EX.Foo},
    {:s?, :a, EX.Bar},
    {:s?, RDFS.label, "foo"},
    {:s?, :p?, :o?}
  ]
  ```

  Multiple triple patterns sharing the same subject and/or predicate can be grouped:

  - Multiple objects to the same subject-predicate pair can be written by just
    writing them one by one in the same triple pattern.
  - Multiple predicate-objects pair on the same subject can be written by
    grouping them with square brackets.

  With these, the previous example can be shortened to:

  ```elixir
  {
    :s?,
      [:a, EX.Foo, EX.Bar],
      [RDFS.label, "foo"],
      [:p?, :o?]
  }
  ```

  """
  defdelegate bgp(query), to: Builder, as: :bgp!

  @doc """
  Creates a `RDF.Query.BGP` struct for a path through a graph.

  The elements of the path can consist of the same RDF terms and variable
  expressions allowed in `bgp/1` expressions.

  ## Example

  The `RDF.Query.BGP` struct build with this:

      RDF.Query.path [EX.S, EX.p, RDFS.label, :name?]

  is the same as the one build by this `bgp/1` call:

      RDF.Query.bgp [
        {EX.S, EX.p, :_o},
        {:_o, RDFS.label, :name?},
      ]

  """
  defdelegate path(query, opts \\ []), to: Builder, as: :path!
end