core: add documentation for RDF.Namespace and RDF.Vocabulary.Namespace
This commit is contained in:
Marcel Otto
parent
7b794e77fd
commit
f3d0ce35f5
5 changed files with 40 additions and 75 deletions
|
|
@ -7,6 +7,7 @@ defmodule RDF.Datatype.NS do
|
|||
|
||||
use RDF.Vocabulary.Namespace
|
||||
|
||||
@vocabdoc false
|
||||
defvocab XSD,
|
||||
base_uri: "http://www.w3.org/2001/XMLSchema#",
|
||||
terms: ~w[
|
||||
|
|
|
|||
|
|
@ -1,49 +1,30 @@
|
|||
defmodule RDF.Namespace do
|
||||
@moduledoc """
|
||||
A `RDF.Namespace` is a module ...
|
||||
|
||||
TODO: Rewrite this
|
||||
|
||||
A `RDF.Namespace` is a collection of URIs and serves as a namespace for its
|
||||
elements, called terms. The terms can be accessed by qualification on the
|
||||
resp. namespace module.
|
||||
|
||||
## Using a `RDF.Namespace`
|
||||
|
||||
There are two types of terms in a `RDF.Namespace`, which are resolved
|
||||
differently:
|
||||
|
||||
1. Lowercased terms (usually used for RDF properties, but this is not
|
||||
enforced) are represented as functions on a Vocabulary module and return the
|
||||
URI directly.
|
||||
2. Capitalized terms are by standard Elixir semantics modules names, i.e.
|
||||
atoms. In all places in RDF.ex, where an URI is expected, you can use atoms
|
||||
qualified with a `RDF.Namespace` directly, but if you want to resolve it
|
||||
manually, you can pass the `RDF.Namespace` qualified atom to `RDF.uri`.
|
||||
|
||||
Examples:
|
||||
|
||||
iex> RDF.NS.RDFS.subClassOf
|
||||
%URI{authority: "www.w3.org", fragment: "subClassOf", host: "www.w3.org",
|
||||
path: "/2000/01/rdf-schema", port: 80, query: nil, scheme: "http",
|
||||
userinfo: nil}
|
||||
iex> RDF.NS.RDFS.Class
|
||||
RDF.NS.RDFS.Class
|
||||
iex> RDF.uri(RDF.NS.RDFS.Class)
|
||||
%URI{authority: "www.w3.org", fragment: "Class", host: "www.w3.org",
|
||||
path: "/2000/01/rdf-schema", port: 80, query: nil, scheme: "http",
|
||||
userinfo: nil}
|
||||
iex> alias RDF.NS.RDFS
|
||||
iex> RDF.triple(RDFS.Class, RDFS.subClassOf, RDFS.Resource)
|
||||
{RDF.uri(RDFS.Class), RDF.uri(RDFS.subClassOf), RDF.uri(RDFS.Resource)}
|
||||
A behaviour for resolvers of module atoms to URIs.
|
||||
|
||||
Currently there's only one type of such namespaces: `RDF.Vocabulary.Namespace`,
|
||||
but other types are thinkable and might be implemented in the future, eg.
|
||||
namespaces for JSON-LD contexts.
|
||||
"""
|
||||
|
||||
@doc """
|
||||
Resolves a term to an URI.
|
||||
"""
|
||||
@callback __resolve_term__(atom) :: URI.t
|
||||
|
||||
@doc """
|
||||
All terms of a `RDF.Namespace`.
|
||||
"""
|
||||
@callback __terms__() :: [atom]
|
||||
|
||||
|
||||
@doc """
|
||||
Resolves a qualified term to an URI.
|
||||
|
||||
It determines a `RDF.Namespace` from the qualifier of the given term and
|
||||
delegates to remaining part of the term to `__resolve_term__/1` of this
|
||||
determined namespace.
|
||||
"""
|
||||
def resolve_term(expr)
|
||||
|
||||
def resolve_term(uri = %URI{}),
|
||||
|
|
|
|||
|
|
@ -1,4 +1,16 @@
|
|||
defmodule RDF.NS do
|
||||
@moduledoc """
|
||||
`RDF.Namespace`s for fundamental RDF vocabularies.
|
||||
|
||||
Namely:
|
||||
|
||||
- `RDF.NS.RDF`
|
||||
- `RDF.NS.RDFS`
|
||||
- `RDF.NS.OWL`
|
||||
- `RDF.NS.SKOS`
|
||||
- `RDF.NS.XSD`
|
||||
"""
|
||||
|
||||
use RDF.Vocabulary.Namespace
|
||||
|
||||
@vocabdoc """
|
||||
|
|
|
|||
|
|
@ -1,43 +1,14 @@
|
|||
defmodule RDF.Vocabulary.Namespace do
|
||||
@moduledoc """
|
||||
Defines a RDF Vocabulary as a `RDF.Namespace`.
|
||||
A RDF vocabulary as a `RDF.Namespace`.
|
||||
|
||||
`RDF.Vocabulary.Namespace` modules represent a RDF vocabulary as a `RDF.Namespace`.
|
||||
They can be defined with the `defvocab/2` macro of this module.
|
||||
|
||||
## Strict vocabularies
|
||||
|
||||
What is a strict vocabulary and why should I use them over non-strict
|
||||
vocabularies and define all terms ...
|
||||
|
||||
|
||||
## Defining a vocabulary
|
||||
|
||||
There are two basic ways to define a vocabulary:
|
||||
|
||||
1. You can define all terms manually.
|
||||
2. You can load all terms from a specified namespace in a given dataset or
|
||||
graph.
|
||||
|
||||
Either way, you'll first have to define a new module for your vocabulary:
|
||||
|
||||
defmodule Example do
|
||||
use RDF.Vocabulary.Namespace
|
||||
|
||||
defvocab EX,
|
||||
base_uri: "http://www.example.com/ns/",
|
||||
terms: ~w[Foo bar]
|
||||
|
||||
# Your term definitions
|
||||
end
|
||||
|
||||
The `base_uri` argument with the URI prefix of all the terms in the defined
|
||||
vocabulary is required and expects a valid URI ending with either a `"/"` or
|
||||
a `"#"`.
|
||||
|
||||
|
||||
## Reflection
|
||||
|
||||
`__base_uri__` and `__terms__` ...
|
||||
|
||||
RDF.ex comes with predefined modules for some fundamentals vocabularies in
|
||||
the `RDF.NS` module.
|
||||
Furthermore, the [rdf_vocab](https://hex.pm/packages/rdf_vocab) package
|
||||
contains predefined modules for popular vocabularies.
|
||||
"""
|
||||
|
||||
@vocabs_dir "priv/vocabs"
|
||||
|
|
@ -59,7 +30,7 @@ defmodule RDF.Vocabulary.Namespace do
|
|||
case source!(opts) do
|
||||
{:terms, terms} -> {terms, nil}
|
||||
{:data, data} -> {rdf_data_vocab_terms(data, base_uri), data}
|
||||
end #|> IO.inspect()
|
||||
end
|
||||
|
||||
terms =
|
||||
terms
|
||||
|
|
@ -135,6 +106,7 @@ defmodule RDF.Vocabulary.Namespace do
|
|||
end
|
||||
end
|
||||
|
||||
@doc false
|
||||
defmacro define_vocab_terms(terms, base_uri) do
|
||||
terms
|
||||
|> Stream.map(fn
|
||||
|
|
@ -448,7 +420,7 @@ defmodule RDF.Vocabulary.Namespace do
|
|||
end
|
||||
|
||||
|
||||
def filename!(opts) do
|
||||
defp filename!(opts) do
|
||||
if filename = Keyword.get(opts, :file) do
|
||||
cond do
|
||||
File.exists?(filename) ->
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
defmodule RDF.NamespaceTest do
|
||||
use ExUnit.Case
|
||||
|
||||
alias RDF.NS.RDFS
|
||||
doctest RDF.Namespace
|
||||
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue