Fixing IO typeclasses

Hey guys,

It is time to fix our reader and writer typeclasses. We have a few
outstanding issues on Github, and I have spent some time thinking on
how to move forwards. So please find here my proposal.

Please review, comment, ask questions, I am planning to start hacking
on those as soon as possible. I want this stuff to be ready way before
my Scaladays talk, along with the tutorial I am planning for
banana-rdf.

Alexandre



* rdf/common/src/main/scala/org/w3/banana/io/package.scala

```
package org.w3.banana

/** Types for IO operations on RDF objects.
  *
  * RDF syntaxes like Turtle or JSON-LD do allow for the use of
  * relative IRIs but there are no relative IRIs in the RDF model
  * itself. So instead of failing on a relative IRI without a known
  * base, RDF parsers would usually *silently* pick a default base IRI
  * on their own.
  *
  * In `banana-rdf`, we standardize the behaviour by **always** using
  * `rel:` as the default base IRI for IO operations when no base
  * was provided. RDF applications can then look at the scheme and
  * know what happened.
  */
package object io {

  /** `rel:`, the special base IRI used when no base is provided. */
  final val DEFAULT_BASE: String = "rel:"

}
```

* rdf/common/src/main/scala/org/w3/banana/io/RDFReader.scala

```package org.w3.banana
package io

import java.io._

/** An RDF reader.
  *
  * All functions return results in the context `M`. `S` is a phantom
  * type for the RDF syntax.
  */
trait RDFReader[Rdf <: RDF, M[_], +S] {

  /** reads a RDF Graph from a [[java.io.InputStream]] and a base IRI */
  def read(is: InputStream, base: String): M[Rdf#Graph]

  /** reads an RDF Graph from a [[java.io.Reader]] and a base IRI */
  def read(reader: Reader, base: String): M[Rdf#Graph]

  /** reads an RDF Graph from a [[java.io.InputStream]] using the `rel:`
    * base IRI
    */
  final def read(is: InputStream): M[Rdf#Graph] = read(is, DEFAULT_BASE)

  /** reads an RDF Graph from a [[java.io.Reader]] using the `rel:` base
    * IRI
    */
  final def read(reader: Reader): M[Rdf#Graph] = read(reader, DEFAULT_BASE)

}
```

* rdf/common/src/main/scala/org/w3/banana/io/RDFWriter.scala

```
package org.w3.banana
package io

import java.io.OutputStream

/** An RDF writer.
  *
  * All functions return results in the context `M`. `S` is a phantom
  * type for the RDF syntax.
  */
trait RDFWriter[Rdf <: RDF, M[_], +T] {

  /** writes `graph` in a [[java.io.OutputStream]] with the provided
    * `base`
    */
  def write(graph: Rdf#Graph, os: OutputStream, base: String): M[Unit]

  /** writes `graph` in a [[java.io.OutputStream]] where IRIs are
    * relative to the provided `base`
    */
  def writeAsRelative(graph: Rdf#Graph, os: OutputStream, base: String): M[Unit]

  /** returns `graph` as a [[java.lang.String]] */
  def asString(graph: Rdf#Graph, base: String): M[String]

  /** returns `graph` as a [[java.lang.String]] where IRIs are relative
    * to the provided `base`
    */
  def asRelativeString(graph: Rdf#Graph, base: String): M[String]

}
```

Received on Thursday, 29 January 2015 19:42:32 UTC