RDF.IRI (RDF.ex v2.1.0)

View Source

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

Summary

Types

coercible()
t()

Functions

absolute(iri, base)

Resolves a relative IRI against a base IRI.

absolute?(iri)

Checks if the given value is an absolute IRI.

append(iri, string)

Appends a String to a RDF.IRI.

coerce_base(base_iri)

Coerces an IRI serving as a base IRI.

default_base()

The default base IRI to be used when reading a serialization and no base_iri option is provided.

ends_with?(iri, suffix)

Checks whether iri end with any of the given suffixes.

equal_value?(left, right)

Tests for value equality of IRIs.

in_namespace?(iri, namespace)

Checks whether iri lies in namespace.

merge(base, rel)

Merges two IRIs.

merge!(base, rel)

Merges two IRIs and fails when the given base or the result of the merge is not a valid IRI.

new(iri)

Creates a RDF.IRI.

new!(iri)

Creates a RDF.IRI, but checks if the given IRI is valid.

parse(iri)

Parses an IRI into its components and returns them as an URI struct.

scheme(iri)

Returns the scheme of the given IRI

starts_with?(iri, prefix)

Checks whether iri starts with any of the given prefixes.

to_string(iri)

Returns the given IRI as a string.

valid!(iri)

Returns the given value unchanged if it's a valid IRI, otherwise raises an exception.

valid?(iri)

Checks if the given IRI is valid according to RFC 3987.

Types

coercible()

@type coercible() :: String.t() | URI.t() | module() | t()

t()

@type t() :: %RDF.IRI{value: String.t()}

Functions

absolute(iri, base)

@spec absolute(coercible(), coercible()) :: t() | nil

Resolves a relative IRI against a base IRI.

as specified in section 5.1 Establishing a Base URI of RFC3986. Only the basic algorithm in section 5.2 of RFC3986 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

If the given base is not an absolute IRI nil is returned.

absolute?(iri)

@spec absolute?(any()) :: boolean()

Checks if the given value is an absolute IRI.

An absolute IRI is defined in RFC3987 containing a scheme along with a path and optional query and fragment segments.

append(iri, string)

@spec append(t() | module(), String.t()) :: t()

Appends a String to a RDF.IRI.

Example 

iex> ~I<http://example.com/> |> RDF.IRI.append("foo")
~I<http://example.com/foo>

iex> EX.foo |> RDF.IRI.append("bar")
EX.foobar

iex> EX.Foo |> RDF.IRI.append("bar")
RDF.iri(EX.Foobar)

coerce_base(base_iri)

@spec coerce_base(coercible()) :: t()

Coerces an IRI serving as a base IRI.

As opposed to new/1 this also accepts bare RDF.Vocabulary.Namespace modules and uses the base IRI from their definition.

default_base()

The default base IRI to be used when reading a serialization and no base_iri 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/"

You can also set :default_base_iri to a module-function tuple {mod, fun} with a function which should be called to determine the default base IRI.

See section 5.1.4 of RFC 3987

ends_with?(iri, suffix)

@spec ends_with?(t() | module(), String.t() | [String.t()]) :: boolean()

Checks whether iri end with any of the given suffixes.

Examples 

iex> RDF.IRI.ends_with?(~I<http://example.com/foo>, "foo")
true
iex> RDF.IRI.ends_with?(EX.Foo, "Foo")
true
iex> RDF.IRI.ends_with?(~I<http://example.com/foo>, ["foo", "bar"])
true
iex> RDF.IRI.ends_with?(~I<http://example.com/foo>, "bar")
false

equal_value?(left, right)

@spec equal_value?(
  t() | RDF.Literal.t() | atom(),
  t() | RDF.Literal.t() | URI.t() | atom()
) ::
  boolean() | nil

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

in_namespace?(iri, namespace)

@spec in_namespace?(t() | module(), String.t() | t() | module()) :: boolean()

Checks whether iri lies in namespace.

Examples 

iex> RDF.IRI.in_namespace?(~I<http://example.com/foo>, ~I<http://example.com/>)
true
iex> RDF.IRI.in_namespace?(EX.Foo, ~I<http://example.com/>)
true
iex> RDF.IRI.in_namespace?(~I<http://example.com/foo/bar>, "http://example.com/")
true
iex> RDF.IRI.in_namespace?(~I<http://example.com/#foo>, EX)
true

merge(base, rel)

@spec merge(coercible(), coercible()) :: t()

Merges two IRIs.

This function merges two IRIs as per RFC 3986, section 5.2.

merge!(base, rel)

@spec merge!(coercible(), coercible()) :: t()

Merges two IRIs and fails when the given base or the result of the merge is not a valid IRI.

This function merges two IRIs as per RFC 3986, section 5.2.

new(iri)

@spec new(coercible()) :: t()

Creates a RDF.IRI.

new!(iri)

@spec new!(coercible()) :: t()

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

parse(iri)

@spec parse(coercible()) :: URI.t()

Parses an IRI into its components and returns them as an URI struct.

scheme(iri)

@spec scheme(coercible()) :: String.t() | nil

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

starts_with?(iri, prefix)

@spec starts_with?(t() | module(), String.pattern()) :: boolean()

Checks whether iri starts with any of the given prefixes.

Examples 

iex> RDF.IRI.starts_with?(~I<http://example.com/foo>, "http://example.com/")
true
iex> RDF.IRI.starts_with?(EX.Foo, "http://example.com/")
true
iex> RDF.IRI.starts_with?(~I<http://example.com/foo/bar>, ["http://example.com/", "http://example.org/"])
true
iex> RDF.IRI.starts_with?(~I<http://example.com/#foo>, "http://example.org/")
false

to_string(iri)

@spec to_string(t() | module()) :: String.t()

Returns the given IRI as a string.

Note that this function can also handle RDF.Vocabulary.Namespace terms.

Examples 

iex> RDF.IRI.to_string RDF.IRI.new("http://example.com/#foo")
"http://example.com/#foo"
iex> RDF.IRI.to_string EX.foo
"http://example.com/#foo"
iex> RDF.IRI.to_string EX.Foo
"http://example.com/#Foo"

valid!(iri)

@spec valid!(coercible()) :: coercible()

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"

valid?(iri)

@spec valid?(coercible()) :: boolean()

Checks if the given IRI is valid according to RFC 3987.

Examples 

iex> RDF.IRI.valid?("http://www.example.com/foo")
true

iex> RDF.IRI.valid?("urn:isbn:0451450523")
true

iex> RDF.IRI.valid?("http://example.com/path with spaces")
false

iex> RDF.IRI.valid?("example.com")
false