aboutsummaryrefslogtreecommitdiff
path: root/lib/core/rdf.mli
blob: 4ec8f21c5cafb42ebd93696bfaeba99163b8e52b (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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
(*
 * 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
 *)

(** RDF *)

module Iri = Uri

module Blank_node : sig
  type t
  (** A blank node. Don't use this. *)

  val of_string : string -> t
  (** Create a blank node using a string as identifier. *)

  val identifier: t -> string
  (** [identifier blank_node] returns the identifier from a BlankNode. *)

  val equal : t -> t -> bool
  (** [equal a b] returns true if [a] and [b] identify the same blank node. *)

  val pp : t Fmt.t
  [@@ocaml.toplevel_printer]
  (**  [pp ppf t] will output a human readable version of the Blank_node [t] to the formatter [ppf] *)
end

module Literal : sig
  type t
  (** A literal. *)

  val make : string -> ?language:string -> Iri.t -> t
  (** Create a new literal. *)

  val canonical : t -> string
  (** [canonical literal] returns the canonical representation of the literal. *)

  val datatype : t -> Iri.t
  (** [datatype literal] returns the datatype of the literal. *)

  val language : t -> string option
  (** [language literal] returns the language tag of the literal. *)

  val equal : t -> t -> bool
  (** [equal a b] returns true if [a] and [b] are the same literal. *)

  val compare : t -> t -> int
  (** [compare a b] compares two literals by using the lexicographical sorting
      of the canonical values. *)

  val pp : t Fmt.t
  [@@ocaml.toplevel_printer]
  (**  [pp ppf t] will output a human readable version of the Literal [t] to the formatter [ppf] *)
end

module Term : sig
  (** A RDF term is either an IRI, a blank node or a literal. *)

  type t
  (** A RDF term *)

  val of_iri : Iri.t -> t
  (** [of_iri iri] casts the IRI [iri] to a term. *)

  val to_iri : t -> Iri.t option
  (** [to_iri term] attempts to casts [term] to an IRI. *)

  val of_blank_node : Blank_node.t  -> t
  (** [of_blank_node bnode] casts the Blank Node [bnode] to a term. *)

  val to_blank_node: t -> Blank_node.t option
  (** [to_blank_node term] attempts to casts [term] to an Blank Node. *)

  val of_literal : Literal.t -> t
  (** [of_literal literal] casts the literal [literal] to a term. *)

  val to_literal: t -> Literal.t option
  (** [to_literal] attempts to casts [term] to a literal. *)

  val map : t -> (Iri.t -> 'a) -> (Blank_node.t -> 'a) -> (Literal.t -> 'a) -> 'a
  (** Map a term *)

  val equal : t -> t -> bool
  (** [equal a b] returns true if [a] and [b] are the equal. *)

  val compare : t -> t -> int
  (** [compare a b] defines a total order on terms. Returns 0 if [a] and [b] are
      equal, a negative integer if [a] is less than [b] and a positive integer if
      [a] is greater than [b].

      For RDF terms, IRI's are greater than Literals and Blank nodes and Literals are greater than Blank nodes.
  *)

  val pp : t Fmt.t
  [@@ocaml.toplevel_printer]
  (**  [pp ppf t] will output a human readable version of the Term [t] to the formatter [ppf] *)
end

module Triple : sig
  (** A triple is the basic building block of RDF data.
   **
   ** A triple consists of three components:
   ** - A subject which is either an IRI or a blank node
   ** - A predicate which is an IRI
   ** - An object which is a literal, an IRI or a blank node
   **
   **  *)


  module Subject : sig
    type t
    (** The subject of a triple. A subject may be either an IRI or a Blank Node.*)

    val of_iri : Iri.t -> t
    (** Create a subject from an Iri. *)

    val of_blank_node : Blank_node.t -> t
    (** Create a subject from a Blank Node*)

    val map: t -> (Iri.t -> 'a) -> (Blank_node.t -> 'a) -> 'a
    (** [map s f_iri f_bnode] maps the subject [s] by applying [f_iri] or
        [f_bnode] depending on wheter subject is an IRI or blank node.*)

    val to_term : t -> Term.t
    (** [to_term s] casts the subject to a Term. *)

    val equal : t -> t -> bool

    val pp : t Fmt.t
    [@@ocaml.toplevel_printer]
    (**  [pp ppf t] will output a human readable version of the Subject [t] to the formatter [ppf] *)
  end


  module Predicate : sig
    type t
    (** The predicate of a triple which must be an Iri. *)

    val of_iri : Iri.t -> t
    (** Create an predicate from an Iri.*)

    val map: t -> (Iri.t -> 'a) -> 'a
    (** [map_predicate p f] applies [f] to the predicate IRI. *)

    val to_term : t -> Term.t
    (** [to_term s] casts the predicate to a Term. *)

    val equal : t -> t -> bool

    val pp : t Fmt.t
    [@@ocaml.toplevel_printer]
    (**  [pp ppf t] will output a human readable version of the Predicate [t] to the formatter [ppf] *)
  end

  module Object : sig

    type t
    (** The object of a triple is either an IRI, a Blank Node or a literal.*)

    val of_iri : Iri.t -> t
    (** Create an object from an Iri.*)

    val of_blank_node : Blank_node.t -> t
    (** Create an object from a Blank Node.*)

    val of_literal : Literal.t -> t
    (** Create an object from a literal*)

    val map: t -> (Iri.t -> 'a) -> (Blank_node.t -> 'a) -> (Literal.t -> 'a) -> 'a
    (** Map an object *)

    val to_term : t -> Term.t
    (** [to_term s] casts the object to a Term. *)

    val equal : t -> t -> bool

    val pp : t Fmt.t
    [@@ocaml.toplevel_printer]
    (**  [pp ppf t] will output a human readable version of the Object [t] to the formatter [ppf] *)
  end

  type t = {subject: Subject.t;
            predicate: Predicate.t;
            object': Object.t}
  (** A triple. *)

  val make : Subject.t -> Predicate.t -> Object.t -> t
  (** Create a triple from a subject, predicate and object.*)

  val equal: t -> t -> bool

  val pp : t Fmt.t
  [@@ocaml.toplevel_printer]
  (**  [pp ppf t] will output a human readable version of the Triple [t] to the formatter [ppf] *)

end


module Namespace : sig
  (** RDF namespaces *)

  val make_namespace : string -> string -> Iri.t
  (** [make_namespace base_iri] returns a function that can be used to create IRIs in a namespace. *)

  val rdf : string -> Iri.t
  (** Create an IRI in the RDF namespace (`http://www.w3.org/1999/02/22-rdf-syntax-ns#`).*)

  val rdfs : string -> Iri.t
  (** Create an IRI in the RDFS namespace (`http://www.w3.org/2000/01/rdf-schema#`). *)

  val owl: string -> Iri.t
  (** Create an IRI in the OWL namespace (`http://www.w3.org/2002/07/owl#`). *)

  val xsd: string -> Iri.t
  (** Create an IRI in the XSD namespace (`http://www.w3.org/2001/XMLSchema#`). *)

end

module Graph : sig
  (** A simple (and rather inefficient) implementation of an RDF graph. *)

  type t
  (** An RDF graph *)

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

  val singleton : Triple.t -> t
  (** [singleton triple] returns a graph containg only [triple]. *)

  val union : t -> t -> t
  (** [union a b] returns the union of the graphs. *)

  val add : t -> Triple.t -> t
  (** [add graph triple] returns a new graph containing [triple] (and everything in [graph]).*)

  val add_seq : t -> Triple.t Seq.t -> t
  (** [add_seq graph triples] returns a new graph containing all triples in the
      sequence [triples]. *)

  val remove: t -> Triple.t -> t
  (** [remove_triple graph triple] removes [triple] from [graph]. *)

  val subjects : t -> Term.t Seq.t
  (** [subjects graph] returns a sequence of subjects that appear in the graph. *)

  val to_triples: t -> Triple.t Seq.t
  (** [to_triples graph] returns a sequence of triples in [graph].*)

  val to_triples_s : t -> Term.t -> Triple.t Seq.t
  (** [to_seq_s graph subject] returns a sequence of triples in [graph] with
      [subject] in subject position.*)

  val to_triples_sp : t -> Term.t -> Term.t -> Triple.t Seq.t
  (** [to_seq_sp graph subject predicate] returns a sequence of triples in [graph] with
      [subject] in subject position and [predicate] in predicate position.*)
end