235 lines
7 KiB
Elixir
235 lines
7 KiB
Elixir
defmodule RDF.IRI do
|
|
@moduledoc """
|
|
A structure for IRIs.
|
|
|
|
This structure just wraps a plain IRI string and doesn't bother with the
|
|
components of the IRI, since in the context of RDF there are usually very many
|
|
IRIs and parsing them isn't needed in most cases. For these reasons we don't
|
|
use Elixirs built-in `URI` structure, because it would be unnecessary
|
|
expensive in terms of performance and memory.
|
|
|
|
The component parts can always be retrieved with the `RDF.IRI.parse/1`
|
|
function, which returns Elixirs built-in `URI` structure. Note, that `URI`
|
|
doesn't escape Unicode characters by default, so it's a suitable structure for
|
|
IRIs.
|
|
|
|
see <https://tools.ietf.org/html/rfc3987>
|
|
"""
|
|
|
|
@enforce_keys [:value]
|
|
defstruct [:value]
|
|
|
|
alias RDF.Namespace
|
|
|
|
@type t :: module
|
|
|
|
# see https://tools.ietf.org/html/rfc3986#appendix-B
|
|
@scheme_regex Regex.recompile!(~r/^([a-z][a-z0-9\+\-\.]*):/i)
|
|
|
|
@doc """
|
|
The default base IRI to be used when reading a serialization and no `base` option is provided.
|
|
|
|
The value can be set via the `default_base_iri` configuration. For example:
|
|
|
|
config :rdf,
|
|
default_base_iri: "http://my_app.example/"
|
|
|
|
See [section 5.1.4 of RFC 3987](https://tools.ietf.org/html/rfc3986#page-29)
|
|
"""
|
|
@default_base Application.get_env(:rdf, :default_base_iri)
|
|
def default_base, do: @default_base
|
|
|
|
|
|
@doc """
|
|
Creates a `RDF.IRI`.
|
|
"""
|
|
def new(iri)
|
|
def new(iri) when is_binary(iri), do: %RDF.IRI{value: iri}
|
|
def new(qname) when is_atom(qname) and qname not in [nil, true, false],
|
|
do: Namespace.resolve_term(qname)
|
|
def new(%URI{} = uri), do: uri |> URI.to_string |> new
|
|
def new(%RDF.IRI{} = iri), do: iri
|
|
|
|
@doc """
|
|
Creates a `RDF.IRI`, but checks if the given IRI is valid.
|
|
|
|
If the given IRI is not valid a `RDF.IRI.InvalidError` is raised.
|
|
|
|
see `valid?/1`
|
|
"""
|
|
def new!(iri)
|
|
def new!(iri) when is_binary(iri), do: iri |> valid!() |> new()
|
|
def new!(qname) when is_atom(qname) and qname not in [nil, true, false],
|
|
do: new(qname) # since terms of a namespace are already validated
|
|
def new!(%URI{} = uri), do: uri |> valid!() |> new()
|
|
def new!(%RDF.IRI{} = iri), do: valid!(iri)
|
|
|
|
|
|
@doc """
|
|
Returns the given value unchanged if it's a valid IRI, otherwise raises an exception.
|
|
|
|
## Examples
|
|
|
|
iex> RDF.IRI.valid!("http://www.example.com/foo")
|
|
"http://www.example.com/foo"
|
|
iex> RDF.IRI.valid!(RDF.IRI.new("http://www.example.com/foo"))
|
|
RDF.IRI.new("http://www.example.com/foo")
|
|
iex> RDF.IRI.valid!("not an iri")
|
|
** (RDF.IRI.InvalidError) Invalid IRI: "not an iri"
|
|
"""
|
|
def valid!(iri) do
|
|
if not valid?(iri), do: raise RDF.IRI.InvalidError, "Invalid IRI: #{inspect iri}"
|
|
iri
|
|
end
|
|
|
|
|
|
@doc """
|
|
Checks if the given IRI is valid.
|
|
|
|
Note: This currently checks only if the given IRI is absolute.
|
|
|
|
## Examples
|
|
|
|
iex> RDF.IRI.valid?("http://www.example.com/foo")
|
|
true
|
|
iex> RDF.IRI.valid?("not an iri")
|
|
false
|
|
"""
|
|
def valid?(iri), do: absolute?(iri) # TODO: Provide a more elaborate validation
|
|
|
|
|
|
@doc """
|
|
Checks if the given value is an absolute IRI.
|
|
|
|
An absolute IRI is defined in [RFC3987](http://www.ietf.org/rfc/rfc3987.txt)
|
|
containing a scheme along with a path and optional query and fragment segments.
|
|
"""
|
|
def absolute?(iri)
|
|
|
|
def absolute?(value) when is_binary(value), do: not is_nil(scheme(value))
|
|
def absolute?(%RDF.IRI{value: value}), do: absolute?(value)
|
|
def absolute?(%URI{scheme: nil}), do: false
|
|
def absolute?(%URI{scheme: _}), do: true
|
|
def absolute?(qname) when is_atom(qname) and qname not in [nil, true, false] do
|
|
qname |> Namespace.resolve_term |> absolute?()
|
|
rescue
|
|
_ -> false
|
|
end
|
|
def absolute?(_), do: false
|
|
|
|
|
|
@doc """
|
|
Resolves a relative IRI against a base IRI.
|
|
|
|
as specified in [section 5.1 Establishing a Base URI of RFC3986](http://tools.ietf.org/html/rfc3986#section-5.1).
|
|
Only the basic algorithm in [section 5.2 of RFC3986](http://tools.ietf.org/html/rfc3986#section-5.2)
|
|
is used; neither Syntax-Based Normalization nor Scheme-Based Normalization are performed.
|
|
|
|
Characters additionally allowed in IRI references are treated in the same way that unreserved
|
|
characters are treated in URI references, per [section 6.5 of RFC3987](http://tools.ietf.org/html/rfc3987#section-6.5)
|
|
|
|
If the given is not an absolute IRI `nil` is returned.
|
|
"""
|
|
def absolute(iri, base) do
|
|
cond do
|
|
absolute?(iri) -> new(iri)
|
|
not absolute?(base) -> nil
|
|
true -> merge(base, iri)
|
|
end
|
|
end
|
|
|
|
|
|
@doc """
|
|
Merges two IRIs.
|
|
|
|
This function merges two IRIs as per
|
|
[RFC 3986, section 5.2](https://tools.ietf.org/html/rfc3986#section-5.2).
|
|
"""
|
|
def merge(base, rel) do
|
|
base
|
|
|> parse()
|
|
|> URI.merge(parse(rel))
|
|
|> empty_fragment_shim(rel)
|
|
|> new()
|
|
end
|
|
|
|
|
|
@doc false
|
|
# shim for https://github.com/elixir-lang/elixir/pull/6419
|
|
def empty_fragment_shim(_, %URI{} = uri), do: uri
|
|
def empty_fragment_shim(uri, %RDF.IRI{value: value}),
|
|
do: empty_fragment_shim(uri, value)
|
|
def empty_fragment_shim(uri, original) do
|
|
if String.ends_with?(original, "#") do
|
|
%URI{uri | fragment: ""}
|
|
else
|
|
uri
|
|
end
|
|
end
|
|
|
|
|
|
@doc """
|
|
Returns the scheme of the given IRI
|
|
|
|
If the given string is not a valid absolute IRI, `nil` is returned.
|
|
|
|
## Examples
|
|
|
|
iex> RDF.IRI.scheme("http://www.example.com/foo")
|
|
"http"
|
|
iex> RDF.IRI.scheme("not an iri")
|
|
nil
|
|
"""
|
|
def scheme(iri)
|
|
def scheme(%RDF.IRI{value: value}), do: scheme(value)
|
|
def scheme(%URI{scheme: scheme}), do: scheme
|
|
def scheme(qname) when is_atom(qname), do: Namespace.resolve_term(qname) |> scheme()
|
|
def scheme(iri) when is_binary(iri) do
|
|
with [_, scheme] <- Regex.run(@scheme_regex, iri) do
|
|
scheme
|
|
end
|
|
end
|
|
|
|
|
|
@doc """
|
|
Parses an IRI into its components and returns them as an `URI` struct.
|
|
"""
|
|
def parse(iri)
|
|
def parse(iri) when is_binary(iri), do: URI.parse(iri) |> empty_fragment_shim(iri)
|
|
def parse(qname) when is_atom(qname) and qname not in [nil, true, false],
|
|
do: Namespace.resolve_term(qname) |> parse()
|
|
def parse(%RDF.IRI{value: value}), do: URI.parse(value) |> empty_fragment_shim(value)
|
|
def parse(%URI{} = uri), do: uri
|
|
|
|
|
|
@doc """
|
|
Tests for value equality of IRIs.
|
|
|
|
Returns `nil` when the given arguments are not comparable as IRIs.
|
|
|
|
see <https://www.w3.org/TR/rdf-concepts/#section-Graph-URIref>
|
|
"""
|
|
def equal_value?(left, right)
|
|
|
|
def equal_value?(%RDF.IRI{value: left}, %RDF.IRI{value: right}),
|
|
do: left == right
|
|
|
|
@xsd_any_uri "http://www.w3.org/2001/XMLSchema#anyURI"
|
|
|
|
def equal_value?(%RDF.Literal{datatype: %RDF.IRI{value: @xsd_any_uri}, value: left}, right),
|
|
do: equal_value?(new(left), right)
|
|
|
|
def equal_value?(left, %RDF.Literal{datatype: %RDF.IRI{value: @xsd_any_uri}, value: right}),
|
|
do: equal_value?(left, new(right))
|
|
|
|
def equal_value?(_, _),
|
|
do: nil
|
|
|
|
|
|
defimpl String.Chars do
|
|
def to_string(%RDF.IRI{value: value}) do
|
|
value
|
|
end
|
|
end
|
|
|
|
end
|