# `RDF.XML`
[🔗](https://github.com/rdf-elixir/rdf-xml-ex/blob/v1.2.1/lib/rdf/xml.ex#L1)

An implementation of the RDF 1.1 XML Syntax.

It is implemented as a `RDF.Serialization.Format`, so it can be used like any other
serialization format of RDF.ex.

    graph = RDF.XML.read_file!("file.rdf")
    RDF.XML.write_file!(graph, "file.rdf")

For a description of the capabilities and options (which can be passed also to
the `read` and `write` functions) see `RDF.XML.Decoder` and `RDF.XML.Encoder`.

For more on the RDF-XML format see <http://www.w3.org/TR/rdf-syntax-grammar/>.

# `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

General 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]`)

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `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`.

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

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `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.

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `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.

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `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.

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `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.

See the [module documentation of the decoder](`Elixir.RDF.XML.Decoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the decoder.

# `write_file`

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

Serializes an RDF data structure to a file.

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

## Options

General 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]`)

See the [module documentation of the encoder](`Elixir.RDF.XML.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_file!`

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

Serializes an 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.

See the [module documentation of the encoder](`Elixir.RDF.XML.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_stream`

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

Serializes an RDF data structure to a stream.

See the [module documentation of the encoder](`Elixir.RDF.XML.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_string`

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

Serializes an 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.

See the [module documentation of the encoder](`Elixir.RDF.XML.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

# `write_string!`

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

Serializes an RDF data structure to a string.

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

See the [module documentation of the encoder](`Elixir.RDF.XML.Encoder`) for the
available format-specific options, all of which can be used in this
function and will be passed them through to the encoder.

---

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