aboutsummaryrefslogtreecommitdiff
path: root/lib/fragment_graph/rdf_fragment_graph.mli
blob: 77dadbf25de4abb1c155599e122de45430b79325 (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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
(*
 * 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 S = sig
  (** RDF Fragment Graph  *)

  (** {1 Predicate and Object} *)

  (** Fragment Graphs can not reuse the {!module:Rdf.Triple.Predicate} and
      {!module:Rdf.Triple.Object} modules as they do not allow Blank Nodes and in
      addition to IRIs, references to fragments are allowed.*)

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

    val of_iri : ?base_subject:Rdf.Iri.t -> 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] *)

    val pp : t Fmt.t
    [@@ocaml.toplevel_printer]
  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 : ?base_subject:Rdf.Iri.t -> 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] *)

    val pp : t Fmt.t
    [@@ocaml.toplevel_printer]
  end

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

  (** {1 Constructors} *)

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

  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 of_triples : Rdf.Triple.t Seq.t -> (Rdf.Iri.t * t) Seq.t
  (** [of_triples triples] returns a sequence of fragment graphs for each base
      subject appearing in [triples]. *)

  (** {1 Accessors}  *)

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

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

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

  (** {1 Content-addressing}  *)

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

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

  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]*)

  (** {1 (Pretty) Printing}  *)

  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) : S
(** Constructor of a Fragment Graph  *)