# `RDF.Serialization`
[🔗](https://github.com/rdf-elixir/rdf-ex/blob/v3.0.1/lib/rdf/serialization/serialization.ex#L1)

Functions for working with RDF serializations generically.

Besides some reflection functions regarding available serialization formats,
this module includes the full serialization reader and writer API from the
serialization format modules.
As opposed to calling the reader and writer functions statically on the
serialization format module, they can be used more dynamically on this module
either by providing the format by name or media type with the `:format` option
or in the case of the read and write function on files by relying on detection
of the format by file extension.

# `format`

```elixir
@type format() :: module()
```

# `available_formats`

```elixir
@spec available_formats() :: [format()]
```

The list of all available `RDF.Serialization.Format`s in an application.

A known format might not be available in an application, when the format is
implemented in an external library and this not specified as a Mix dependency
of this application.

## Examples

    iex> RDF.Serialization.available_formats
    [RDF.Turtle, RDF.TriG, RDF.NTriples, RDF.NQuads]

# `format`

```elixir
@spec format(String.t() | atom()) :: format() | nil
```

Returns the `RDF.Serialization.Format` with the given name, if available.

## Examples

    iex> RDF.Serialization.format(:turtle)
    RDF.Turtle
    iex> RDF.Serialization.format("turtle")
    RDF.Turtle
    iex> RDF.Serialization.format(:jsonld)
    nil  # unless json_ld is defined as a dependency of the application

# `format_by_extension`

```elixir
@spec format_by_extension(String.t()) :: format() | nil
```

Returns the proper `RDF.Serialization.Format` for the given file extension, if available.

## Examples

    iex> RDF.Serialization.format_by_extension("ttl")
    RDF.Turtle
    iex> RDF.Serialization.format_by_extension(".ttl")
    RDF.Turtle
    iex> RDF.Serialization.format_by_extension("jsonld")
    nil  # unless json_ld is defined as a dependency of the application

# `format_by_media_type`

```elixir
@spec format_by_media_type(String.t()) :: format() | nil
```

Returns the `RDF.Serialization.Format` with the given media type, if available.

## Examples

    iex> RDF.Serialization.format_by_media_type("text/turtle")
    RDF.Turtle
    iex> RDF.Serialization.format_by_media_type("application/ld+json")
    nil  # unless json_ld is defined as a dependency of the application

# `formats`

```elixir
@spec formats() :: [format()]
```

The list of all known `RDF.Serialization.Format`s in the RDF.ex eco-system.

Note: Not all known formats might be available to an application, see `available_formats/0`.

## Examples

    iex> RDF.Serialization.formats
    [RDF.Turtle, RDF.TriG, JSON.LD, RDF.NTriples, RDF.NQuads, RDF.XML]

# `read_file`

```elixir
@spec read_file(
  Path.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a 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.

## Options

The format can be specified with the `format` option and a format name or the
`media_type` option and the media type of the format. If none of these are 
given, the format gets inferred from the extension of the given file name. 

Other available serialization-independent options:

- `:stream`: Allows to enable reading the data from a file directly via a
  stream (default: `false` on this function, `true` on the bang version)
- `:gzip`: Allows to read directly from a gzipped file (default: `false`)
- `:file_mode`: A list with the Elixir `File.open` modes to be used for reading
  (default: `[:read, :utf8]`)

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `read_file!`

```elixir
@spec read_file!(
  Path.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a file.

As opposed to `read_file/2`, it raises an exception if an error occurs and
defaults to `stream: true`.

The format can be specified with the `format` option and a format name or the 
`media_type` option and the media type of the format. If none of these are 
given, the format gets inferred from the extension of the given file name. 

See `read_file/3` for the available format-independent options.

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `read_stream`

```elixir
@spec read_stream(
  Enumerable.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a graph or dataset from a stream.

It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
dataset, or `{:error, reason}` if an error occurs.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `read_stream!`

```elixir
@spec read_stream!(
  Enumerable.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a stream.

As opposed to `read_stream/2`, it raises an exception if an error occurs.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `read_string`

```elixir
@spec read_string(
  String.t(),
  keyword()
) :: {:ok, RDF.Graph.t() | RDF.Dataset.t()} | {:error, any()}
```

Deserializes a 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.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `read_string!`

```elixir
@spec read_string!(
  String.t(),
  keyword()
) :: RDF.Graph.t() | RDF.Dataset.t()
```

Deserializes a graph or dataset from a string.

As opposed to `read_string/2`, it raises an exception if an error occurs.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the decoder of a RDF serialization format
for format-specific options.

# `write_file`

```elixir
@spec write_file(RDF.Data.Source.t(), Path.t(), keyword()) :: :ok | {:error, any()}
```

Serializes a RDF data structure to a file.

It returns `:ok` if successful or `{:error, reason}` if an error occurs.

## Options

The format can be specified with the `format` option and a format name or the
`media_type` option and the media type of the format. If none of these are
given, the format gets inferred from the extension of the given file name.

Other available serialization-independent options:

- `:stream`: Allows to enable writing the serialized data to the file directly
  via a stream. Possible values: `:string` or `:iodata` for writing to the file
  with a stream of strings respective IO lists, `true` if you want to use streams,
  but don't care for the exact method or `false` for not writing with
  a stream (default: `false` on this function, `:iodata` on the bang version)
- `:gzip`: Allows to write directly to a gzipped file (default: `false`)
- `:force`: If not set to `true`, an error is raised when the given file
  already exists (default: `false`)
- `:file_mode`: A list with the Elixir `File.open` modes to be used for writing
  (default: `[:write, :exclusive]`)

Please refer to the documentation of the encoder of a RDF serialization format
for format-specific options.

# `write_file!`

```elixir
@spec write_file!(RDF.Data.Source.t(), Path.t(), keyword()) :: :ok
```

Serializes a RDF data structure to a file.

As opposed to `write_file/3`, it raises an exception if an error occurs.

See `write_file/3` for the available format-independent options.

Please refer to the documentation of the encoder of a RDF serialization format
for format-specific options.

# `write_stream`

```elixir
@spec write_stream(
  RDF.Data.Source.t(),
  keyword()
) :: Enumerable.t()
```

Serializes a RDF data structure to a stream.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the encoder of a RDF serialization format
for format-specific options and what the stream emits.

# `write_string`

```elixir
@spec write_string(
  RDF.Data.Source.t(),
  keyword()
) :: {:ok, String.t()} | {:error, any()}
```

Serializes a RDF data structure to a string.

It returns an `{:ok, string}` tuple, with `string` being the serialized graph or
dataset, or `{:error, reason}` if an error occurs.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the encoder of a RDF serialization format
for format-specific options.

# `write_string!`

```elixir
@spec write_string!(
  RDF.Data.Source.t(),
  keyword()
) :: String.t()
```

Serializes a RDF data structure to a string.

As opposed to `write_string/2`, it raises an exception if an error occurs.

The format must be specified with the `format` option and a format name or the
`media_type` option and the media type of the format.

Please refer to the documentation of the encoder of a RDF serialization format
for format-specific options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*