aboutsummaryrefslogtreecommitdiff
path: root/lib/fragment_graph/rdf_fragment_graph.mli
blob: 44edddd001730afce25379ef5aea8cbc549b663e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
(*
 * SPDX-FileCopyrightText: 2021 petites singularités <ps-dream@lesoiseaux.io>
 * SPDX-FileCopyrightText: 2021 pukkamustard <pukkamustard@posteo.net>
 *
 * SPDX-License-Identifier: AGPL-3.0-or-later
 *)

(** Fragment Graph
 **
 ** This defines a data structure that can hold statements about a base subject
 ** as well as statements about subjecs that are fragments of the base
 ** subject.
 **
 ** This allows a representation of the statements without including the base
 ** subject - enabling this grouping of statements to be used for
 ** content-addressing.
 **
 ** See [Content-addressable RDF](http://purl.org/ca-rdf) for more information.
 **
 ** WARNING: This module implements a sketch of an undocumented CBOR based
 **  canonical representation (instead of a CSexp based on as presented in the
 **  v.0.1.0 of the document linked above). This serialization is not stable and
 **  is bound to change - so will the identifiers of fragment graphs. An updated
 **  version of the document that describes the CBOR based serialization is
 **  planned.  *)

module type HASH = sig
  (*** Signature of a hash that is used to compute identifiers. *)

  val hash : string -> Rdf.Iri.t
  (** [hash v] returns the hash of [v] as an iri. *)
end

module type T = sig
  (** RDF Fragment Graph  *)

  module Predicate : sig
    type t =
      | FragmentReference of string
      | Iri of Rdf.Iri.t
      (** Predicate that can appear in a Fragment Graph *)

    val of_iri : Rdf.Iri.t -> t
    (** [of_iri iri] creates an Iri predicate  *)

    val make_fragment_reference : string -> t
    (** [make_fragment_reference fragment] creates a reference to [fragment] *)

  end

  module Object : sig
    type t =
      | FragmentReference of string
      | Iri of Rdf.Iri.t
      | Literal of Rdf.Literal.t
      (** Object that can appear in a Fragment Graph  *)

    val of_iri : Rdf.Iri.t -> t
    (** [of_iri iri] creates an iri object *)

    val of_literal : Rdf.Literal.t -> t
    (** [of_iri iri] creates an literal object *)

    val make_fragment_reference : string -> t
    (** [make_fragment_reference fragment] creates a reference to [fragment] *)
  end

  type t
  (** Type of a Fragment Graph *)

  val empty : t
  (** [empty] is the empty fragment graph *)

  val equal : t -> t -> bool
  (** [equal a b] returns true if [a] is the same Fragment Graph as [b]. *)

  val add_statement : Predicate.t -> Object.t -> t -> t
  (** [add_statement fragment_graph predicate object'] adds a statement to the fragment graph *)

  val add_fragment_statement : string -> Predicate.t -> Object.t -> t -> t
  (** [add_fragment_statement] adds a fragment statement to the fragment graph *)

  val statements : t -> (Predicate.t * Object.t) list
  (** [statements fragment_graph] returns a list of statements in
      [fragment_graph]. *)

  val fragment_statements : t -> (string * Predicate.t * Object.t) list
  (** [fragment_statements fragment_graph] returns a list of fragment statements
      in [fragment_graph]. *)

  val base_subject : t -> Rdf.Iri.t
  (** [base_subject fragment_graph] returns the base subject of the fragment graph. *)

  val canonical : t -> string
  (** [canonical fragment_graph] returns the canonical serialization of the fragment graph.  *)

  val of_canonical : string -> (t,  string) result
  (** [of_canonical s] attempts to decode the fragment graph from the canonical serialization in [s]*)

  val to_triples : t -> Rdf.Triple.t list
  (** [to_triples fragment_graph] returns a list of statements in [fragment_graph] as triples. *)

  val pp : t Fmt.t
  [@@ocaml.toplevel_printer]
  (** [pp ppf t] will output a debug output of the Fragment Graph [t] to the formatter [ppf] *)
end

module Make(H: HASH) : T