Add documentation to RDF.Serialization, RDF.Reader, RDF.Decoder and RDF.Encoder
This commit is contained in:
parent
31851d3630
commit
1fdb64c646
5 changed files with 121 additions and 8 deletions
|
@ -1,15 +1,38 @@
|
||||||
defmodule RDF.Reader do
|
defmodule RDF.Reader do
|
||||||
|
@moduledoc """
|
||||||
|
General serialization-independent functions for reading a `RDF.Graph` or `RDF.Dataset` from a file or encoded-string.
|
||||||
|
|
||||||
|
You probably won't use these functions directly, but instead use the automatically
|
||||||
|
generated functions with same name on a `RDF.Serialization`, which implicitly
|
||||||
|
use the proper `RDF.Serialization.Decoder` module.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Reads and decodes a serialized graph or dataset from a string.
|
||||||
|
|
||||||
|
It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
|
||||||
|
dataset, or `{:error, reason}` if an error occurs.
|
||||||
|
"""
|
||||||
def read_string(decoder, content, opts \\ []) do
|
def read_string(decoder, content, opts \\ []) do
|
||||||
decoder.decode(content, opts)
|
decoder.decode(content, opts)
|
||||||
end
|
end
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Reads and decodes a serialized graph or dataset from a string.
|
||||||
|
|
||||||
|
As opposed to `read_string`, it raises an exception if an error occurs.
|
||||||
|
"""
|
||||||
def read_string!(decoder, content, opts \\ []) do
|
def read_string!(decoder, content, opts \\ []) do
|
||||||
decoder.decode!(content, opts)
|
decoder.decode!(content, opts)
|
||||||
end
|
end
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Reads and decodes a serialized graph or dataset from a file.
|
||||||
|
|
||||||
|
It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
|
||||||
|
dataset, or `{:error, reason}` if an error occurs.
|
||||||
|
"""
|
||||||
def read_file(decoder, file, opts \\ []) do
|
def read_file(decoder, file, opts \\ []) do
|
||||||
case File.read(file) do
|
case File.read(file) do
|
||||||
{:ok, content} -> read_string(decoder, content, opts)
|
{:ok, content} -> read_string(decoder, content, opts)
|
||||||
|
@ -17,6 +40,11 @@ defmodule RDF.Reader do
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Reads and decodes a serialized graph or dataset from a file.
|
||||||
|
|
||||||
|
As opposed to `read_file`, it raises an exception if an error occurs.
|
||||||
|
"""
|
||||||
def read_file!(decoder, file, opts \\ []) do
|
def read_file!(decoder, file, opts \\ []) do
|
||||||
with content = File.read!(file) do
|
with content = File.read!(file) do
|
||||||
read_string!(decoder, content, opts)
|
read_string!(decoder, content, opts)
|
||||||
|
|
|
@ -1,11 +1,59 @@
|
||||||
defmodule RDF.Serialization do
|
defmodule RDF.Serialization do
|
||||||
|
@moduledoc """
|
||||||
|
A behaviour for RDF serialization formats.
|
||||||
|
|
||||||
|
A `RDF.Serialization` for a format can be implemented like this
|
||||||
|
|
||||||
|
defmodule SomeFormat do
|
||||||
|
use RDF.Serialization
|
||||||
|
import RDF.Sigils
|
||||||
|
|
||||||
|
@id ~I<http://example.com/some_format>
|
||||||
|
@extension "ext"
|
||||||
|
@content_type "application/some-format"
|
||||||
|
end
|
||||||
|
|
||||||
|
When `@id`, `@extension` and `@content_type` module attributes are defined the
|
||||||
|
resp. behaviour functions are generated automatically and return these values.
|
||||||
|
|
||||||
|
Then you'll have to do the main work by implementing a
|
||||||
|
`RDF.Serialization.Encoder` and a `RDF.Serialization.Decoder` for the format.
|
||||||
|
|
||||||
|
By default it is assumed that these are defined in `Encoder` and `Decoder`
|
||||||
|
moduler under the `RDF.Serialization` module of the format, i.e. in the example
|
||||||
|
above in `SomeFormat.Encoder` and `SomeFormat.Decoder`. If you want them in
|
||||||
|
another module, you'll have to override the `encoder/0` and/or `decoder/0`
|
||||||
|
functions in your `RDF.Serialization` module.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
An URI of the serialization format.
|
||||||
|
"""
|
||||||
@callback id :: URI.t
|
@callback id :: URI.t
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
The usual file extension for the serialization format.
|
||||||
|
"""
|
||||||
@callback extension :: binary
|
@callback extension :: binary
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
The MIME type of the serialization format.
|
||||||
|
"""
|
||||||
@callback content_type :: binary
|
@callback content_type :: binary
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
A map with the supported options of the `Encoder` and `Decoder` for the serialization format.
|
||||||
|
"""
|
||||||
@callback options :: map
|
@callback options :: map
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
The `RDF.Serialization.Decoder` module for the serialization format.
|
||||||
|
"""
|
||||||
@callback decoder :: module
|
@callback decoder :: module
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
The `RDF.Serialization.Encoder` module for the serialization format.
|
||||||
|
"""
|
||||||
@callback encoder :: module
|
@callback encoder :: module
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,26 @@
|
||||||
defmodule RDF.Serialization.Decoder do
|
defmodule RDF.Serialization.Decoder do
|
||||||
@moduledoc false
|
@moduledoc """
|
||||||
|
A behaviour for decoder of strings encoded in a specific `RDF.Serialization` format.
|
||||||
|
"""
|
||||||
|
|
||||||
@callback decode(String.t, keyword) :: keyword(RDF.Graph)
|
|
||||||
@callback decode!(String.t, keyword) :: RDF.Graph
|
@doc """
|
||||||
|
Decodes a serialized `RDF.Graph` or `RDF.Dataset` from the given string.
|
||||||
|
|
||||||
|
It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
|
||||||
|
dataset, or `{:error, reason}` if an error occurs.
|
||||||
|
"""
|
||||||
|
@callback decode(String.t, keyword) :: keyword(RDF.Graph.t | RDF.Dataset.t)
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Decodes a serialized `RDF.Graph` or `RDF.Dataset` from the given string.
|
||||||
|
|
||||||
|
As opposed to `decode`, it raises an exception if an error occurs.
|
||||||
|
|
||||||
|
Note: The `__using__` macro automatically provides an overridable default
|
||||||
|
implementation based on the non-bang `decode` function.
|
||||||
|
"""
|
||||||
|
@callback decode!(String.t, keyword) :: RDF.Graph.t | RDF.Dataset.t
|
||||||
|
|
||||||
|
|
||||||
defmacro __using__(_) do
|
defmacro __using__(_) do
|
||||||
|
|
|
@ -1,8 +1,27 @@
|
||||||
defmodule RDF.Serialization.Encoder do
|
defmodule RDF.Serialization.Encoder do
|
||||||
@moduledoc false
|
@moduledoc """
|
||||||
|
A behaviour for encoders of `RDF.Graph`s or `RDF.Dataset`s in a specific
|
||||||
|
`RDF.Serialization` format.
|
||||||
|
"""
|
||||||
|
|
||||||
@callback encode(RDF.Dataset, keyword) :: keyword(String.t)
|
|
||||||
@callback encode!(RDF.Dataset, keyword) :: String.t
|
@doc """
|
||||||
|
Encodes a `RDF.Graph` or `RDF.Dataset`.
|
||||||
|
|
||||||
|
It returns an `{:ok, string}` tuple, with `string` being the serialized
|
||||||
|
`RDF.Graph` or `RDF.Dataset`, or `{:error, reason}` if an error occurs.
|
||||||
|
"""
|
||||||
|
@callback encode(RDF.Graph.t | RDF.Dataset.t, keyword) :: keyword(String.t)
|
||||||
|
|
||||||
|
@doc """
|
||||||
|
Encodes a `RDF.Graph` or `RDF.Dataset`.
|
||||||
|
|
||||||
|
As opposed to `encode`, it raises an exception if an error occurs.
|
||||||
|
|
||||||
|
Note: The `__using__` macro automatically provides an overridable default
|
||||||
|
implementation based on the non-bang `encode` function.
|
||||||
|
"""
|
||||||
|
@callback encode!(RDF.Graph.t | RDF.Dataset.t, keyword) :: String.t
|
||||||
|
|
||||||
|
|
||||||
defmacro __using__(_) do
|
defmacro __using__(_) do
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
defmodule RDF.NTriples do
|
defmodule RDF.NTriples do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
`RDF.NTriples` provides support for reading the N-Triples serialization
|
`RDF.NTriples` provides support for reading and writing the N-Triples
|
||||||
format.
|
serialization format.
|
||||||
|
|
||||||
N-Triples is a line-based plain-text format for encoding an RDF graph.
|
N-Triples is a line-based plain-text format for encoding an RDF graph.
|
||||||
It is a very restricted, explicit and well-defined subset of both
|
It is a very restricted, explicit and well-defined subset of both
|
||||||
|
|
Loading…
Reference in a new issue