source/modules/lilv/sord-0.16.0/sord/sord.h

   1 /*
   2   Copyright 2011-2016 David Robillard <http://drobilla.net>
   3
   4   Permission to use, copy, modify, and/or distribute this software for any
   5   purpose with or without fee is hereby granted, provided that the above
   6   copyright notice and this permission notice appear in all copies.
   7
   8   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 */
  16
  17 /**
  18    @file sord.h API for Sord, a lightweight RDF model library.
  19 */
  20
  21 #ifndef SORD_SORD_H
  22 #define SORD_SORD_H
  23
  24 #include <stddef.h>
  25 #include <stdint.h>
  26 #include <stdio.h>
  27
  28 #include "serd/serd.h"
  29
  30 #ifdef SORD_SHARED
  31 #    ifdef _WIN32
  32 #        define SORD_LIB_IMPORT __declspec(dllimport)
  33 #        define SORD_LIB_EXPORT __declspec(dllexport)
  34 #    else
  35 #        define SORD_LIB_IMPORT __attribute__((visibility("default")))
  36 #        define SORD_LIB_EXPORT __attribute__((visibility("default")))
  37 #    endif
  38 #    ifdef SORD_INTERNAL
  39 #        define SORD_API SORD_LIB_EXPORT
  40 #    else
  41 #        define SORD_API SORD_LIB_IMPORT
  42 #    endif
  43 #else
  44 #    define SORD_API
  45 #endif
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #else
  50 #    include <stdbool.h>
  51 #endif
  52
  53 /**
  54    @defgroup sord Sord
  55    A lightweight RDF model library.
  56
  57    Sord stores RDF (subject object predicate context) quads, where the context
  58    may be omitted (to represent triples in the default graph).
  59    @{
  60 */
  61
  62 /**
  63    Sord World.
  64    The World represents all library state, including interned strings.
  65 */
  66 typedef struct SordWorldImpl SordWorld;
  67
  68 /**
  69    Sord Model.
  70
  71    A model is an indexed set of Quads (i.e. it can contain several RDF
  72    graphs).  It may be searched using various patterns depending on which
  73    indices are enabled.
  74 */
  75 typedef struct SordModelImpl SordModel;
  76
  77 /**
  78    Model Inserter.
  79
  80    An inserter is used for writing statements to a model using the Serd sink
  81    interface.  This makes it simple to write to a model directly using a
  82    SerdReader, or any other code that writes statements to a SerdStatementSink.
  83 */
  84 typedef struct SordInserterImpl SordInserter;
  85
  86 /**
  87    Model Iterator.
  88 */
  89 typedef struct SordIterImpl SordIter;
  90
  91 /**
  92    RDF Node.
  93    A Node is a component of a Quad.  Nodes may be URIs, blank nodes, or
  94    (in the case of quad objects only) string literals. Literal nodes may
  95    have an associate language or datatype (but not both).
  96 */
  97 typedef struct SordNodeImpl SordNode;
  98
  99 /**
 100    Quad of nodes (a statement), or a quad pattern.
 101
 102    Nodes are ordered (S P O G).  The ID of the default graph is 0.
 103 */
 104 typedef const SordNode* SordQuad[4];
 105
 106 /**
 107    Index into a SordQuad.
 108 */
 109 typedef enum {
 110         SORD_SUBJECT   = 0,  /**< Subject */
 111         SORD_PREDICATE = 1,  /**< Predicate ("key") */
 112         SORD_OBJECT    = 2,  /**< Object    ("value") */
 113         SORD_GRAPH     = 3   /**< Graph     ("context") */
 114 } SordQuadIndex;
 115
 116 /**
 117    Type of a node.
 118 */
 119 typedef enum {
 120         SORD_URI     = 1,  /**< URI */
 121         SORD_BLANK   = 2,  /**< Blank node identifier */
 122         SORD_LITERAL = 3   /**< Literal (string with optional lang or datatype) */
 123 } SordNodeType;
 124
 125 /**
 126    Indexing option.
 127 */
 128 typedef enum {
 129         SORD_SPO = 1,       /**< Subject,   Predicate, Object */
 130         SORD_SOP = 1 << 1,  /**< Subject,   Object,    Predicate */
 131         SORD_OPS = 1 << 2,  /**< Object,    Predicate, Subject */
 132         SORD_OSP = 1 << 3,  /**< Object,    Subject,   Predicate */
 133         SORD_PSO = 1 << 4,  /**< Predicate, Subject,   Object */
 134         SORD_POS = 1 << 5   /**< Predicate, Object,    Subject */
 135 } SordIndexOption;
 136
 137 /**
 138    @name World
 139    @{
 140 */
 141
 142 /**
 143    Create a new Sord World.
 144    It is safe to use multiple worlds in one process, though no data
 145    (e.g. nodes) can be shared between worlds, and this should be avoided if
 146    possible for performance reasons.
 147 */
 148 SORD_API
 149 SordWorld*
 150 sord_world_new(void);
 151
 152 /**
 153    Free `world`.
 154 */
 155 SORD_API
 156 void
 157 sord_world_free(SordWorld* world);
 158
 159 /**
 160    Set a function to be called when errors occur.
 161
 162    The `error_sink` will be called with `handle` as its first argument.  If
 163    no error function is set, errors are printed to stderr.
 164 */
 165 SORD_API
 166 void
 167 sord_world_set_error_sink(SordWorld*    world,
 168                           SerdErrorSink error_sink,
 169                           void*         handle);
 170
 171 /**
 172    @}
 173    @name Node
 174    @{
 175 */
 176
 177 /**
 178    Get a URI node from a string.
 179
 180    Note this function measures `str`, which is a common bottleneck.
 181    Use sord_node_from_serd_node() instead if `str` is already measured.
 182 */
 183 SORD_API
 184 SordNode*
 185 sord_new_uri(SordWorld* world, const uint8_t* uri);
 186
 187 /**
 188    Get a URI node from a relative URI string.
 189 */
 190 SORD_API
 191 SordNode*
 192 sord_new_relative_uri(SordWorld*     world,
 193                       const uint8_t* str,
 194                       const uint8_t* base_uri);
 195
 196 /**
 197    Get a blank node from a string.
 198
 199    Note this function measures `str`, which is a common bottleneck.
 200    Use sord_node_from_serd_node() instead if `str` is already measured.
 201 */
 202 SORD_API
 203 SordNode*
 204 sord_new_blank(SordWorld* world, const uint8_t* str);
 205
 206 /**
 207    Get a literal node from a string.
 208
 209    Note this function measures `str`, which is a common bottleneck.
 210    Use sord_node_from_serd_node() instead if `str` is already measured.
 211 */
 212 SORD_API
 213 SordNode*
 214 sord_new_literal(SordWorld*     world,
 215                  SordNode*      datatype,
 216                  const uint8_t* str,
 217                  const char*    lang);
 218
 219 /**
 220    Copy a node (obtain a reference).
 221
 222    Node that since nodes are interned and reference counted, this does not
 223    actually create a deep copy of `node`.
 224 */
 225 SORD_API
 226 SordNode*
 227 sord_node_copy(const SordNode* node);
 228
 229 /**
 230    Free a node (drop a reference).
 231 */
 232 SORD_API
 233 void
 234 sord_node_free(SordWorld* world, SordNode* node);
 235
 236 /**
 237    Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL).
 238 */
 239 SORD_API
 240 SordNodeType
 241 sord_node_get_type(const SordNode* node);
 242
 243 /**
 244    Return the string value of a node.
 245 */
 246 SORD_API
 247 const uint8_t*
 248 sord_node_get_string(const SordNode* node);
 249
 250 /**
 251    Return the string value of a node, and set `bytes` to its length in bytes.
 252 */
 253 SORD_API
 254 const uint8_t*
 255 sord_node_get_string_counted(const SordNode* node, size_t* bytes);
 256
 257 /**
 258    Return the string value of a node, and set `bytes` to its length in bytes,
 259    and `count` to its length in characters.
 260 */
 261 SORD_API
 262 const uint8_t*
 263 sord_node_get_string_measured(const SordNode* node,
 264                               size_t*         bytes,
 265                               size_t*         chars);
 266
 267 /**
 268    Return the language of a literal node (or NULL).
 269 */
 270 SORD_API
 271 const char*
 272 sord_node_get_language(const SordNode* node);
 273
 274 /**
 275    Return the datatype URI of a literal node (or NULL).
 276 */
 277 SORD_API
 278 SordNode*
 279 sord_node_get_datatype(const SordNode* node);
 280
 281 /**
 282    Return the flags (string attributes) of a node.
 283 */
 284 SORD_API
 285 SerdNodeFlags
 286 sord_node_get_flags(const SordNode* node);
 287
 288 /**
 289    Return true iff node can be serialised as an inline object.
 290
 291    More specifically, this returns true iff the node is the object field
 292    of exactly one statement, and therefore can be inlined since it needn't
 293    be referred to by name.
 294 */
 295 SORD_API
 296 bool
 297 sord_node_is_inline_object(const SordNode* node);
 298
 299 /**
 300    Return true iff `a` is equal to `b`.
 301
 302    Note this is much faster than comparing the node's strings.
 303 */
 304 SORD_API
 305 bool
 306 sord_node_equals(const SordNode* a,
 307                  const SordNode* b);
 308
 309 /**
 310    Return a SordNode as a SerdNode.
 311
 312    The returned node is shared and must not be freed or modified.
 313 */
 314 SORD_API
 315 const SerdNode*
 316 sord_node_to_serd_node(const SordNode* node);
 317
 318 /**
 319    Create a new SordNode from a SerdNode.
 320
 321    The returned node must be freed using sord_node_free().
 322 */
 323 SORD_API
 324 SordNode*
 325 sord_node_from_serd_node(SordWorld*      world,
 326                          SerdEnv*        env,
 327                          const SerdNode* node,
 328                          const SerdNode* datatype,
 329                          const SerdNode* lang);
 330
 331 /**
 332    @}
 333    @name Model
 334    @{
 335 */
 336
 337 /**
 338    Create a new model.
 339
 340    @param world The world in which to make this model.
 341
 342    @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS).  Be sure to
 343    enable an index where the most significant node(s) are not variables in your
 344    queries (e.g. to make (? P O) queries, enable either SORD_OPS or SORD_POS).
 345
 346    @param graphs If true, store (and index) graph contexts.
 347 */
 348 SORD_API
 349 SordModel*
 350 sord_new(SordWorld* world,
 351          unsigned  indices,
 352          bool      graphs);
 353
 354 /**
 355    Close and free `model`.
 356 */
 357 SORD_API
 358 void
 359 sord_free(SordModel* model);
 360
 361 /**
 362    Get the world associated with `model`.
 363 */
 364 SORD_API
 365 SordWorld*
 366 sord_get_world(SordModel* model);
 367
 368 /**
 369    Return the number of nodes stored in `world`.
 370
 371    Nodes are included in this count iff they are a part of a quad in `world`.
 372 */
 373 SORD_API
 374 size_t
 375 sord_num_nodes(const SordWorld* world);
 376
 377 /**
 378    Return the number of quads stored in `model`.
 379 */
 380 SORD_API
 381 size_t
 382 sord_num_quads(const SordModel* model);
 383
 384 /**
 385    Return an iterator to the start of `model`.
 386 */
 387 SORD_API
 388 SordIter*
 389 sord_begin(const SordModel* model);
 390
 391 /**
 392    Search for statements by a quad pattern.
 393    @return an iterator to the first match, or NULL if no matches found.
 394 */
 395 SORD_API
 396 SordIter*
 397 sord_find(SordModel* model, const SordQuad pat);
 398
 399 /**
 400    Search for statements by nodes.
 401    @return an iterator to the first match, or NULL if no matches found.
 402 */
 403 SORD_API
 404 SordIter*
 405 sord_search(SordModel*      model,
 406             const SordNode* s,
 407             const SordNode* p,
 408             const SordNode* o,
 409             const SordNode* g);
 410 /**
 411    Search for a single node that matches a pattern.
 412    Exactly one of `s`, `p`, `o` must be NULL.
 413    This function is mainly useful for predicates that only have one value.
 414    The returned node must be freed using sord_node_free().
 415    @return the first matching node, or NULL if no matches are found.
 416 */
 417 SORD_API
 418 SordNode*
 419 sord_get(SordModel*      model,
 420          const SordNode* s,
 421          const SordNode* p,
 422          const SordNode* o,
 423          const SordNode* g);
 424
 425 /**
 426    Return true iff a statement exists.
 427 */
 428 SORD_API
 429 bool
 430 sord_ask(SordModel*      model,
 431          const SordNode* s,
 432          const SordNode* p,
 433          const SordNode* o,
 434          const SordNode* g);
 435
 436 /**
 437    Return the number of matching statements.
 438 */
 439 SORD_API
 440 uint64_t
 441 sord_count(SordModel*      model,
 442            const SordNode* s,
 443            const SordNode* p,
 444            const SordNode* o,
 445            const SordNode* g);
 446
 447 /**
 448    Check if `model` contains a triple pattern.
 449
 450    @return true if `model` contains a match for `pat`, otherwise false.
 451 */
 452 SORD_API
 453 bool
 454 sord_contains(SordModel* model, const SordQuad pat);
 455
 456 /**
 457    Add a quad to a model.
 458
 459    Calling this function invalidates all iterators on `model`.
 460
 461    @return true on success, false, on error.
 462 */
 463 SORD_API
 464 bool
 465 sord_add(SordModel* model, const SordQuad quad);
 466
 467 /**
 468    Remove a quad from a model.
 469
 470    Calling this function invalidates all iterators on `model`.  To remove quads
 471    while iterating, use sord_erase() instead.
 472 */
 473 SORD_API
 474 void
 475 sord_remove(SordModel* model, const SordQuad quad);
 476
 477 /**
 478    Remove a quad from a model via an iterator.
 479
 480    Calling this function invalidates all iterators on `model` except `iter`.
 481
 482    @param model The model which `iter` points to.
 483    @param iter Iterator to the element to erase, which is incremented to the
 484    next value on return.
 485 */
 486 SORD_API
 487 SerdStatus
 488 sord_erase(SordModel* model, SordIter* iter);
 489
 490 /**
 491    @}
 492    @name Inserter
 493    @{
 494 */
 495
 496 /**
 497    Create an inserter for writing statements to a model.
 498 */
 499 SORD_API
 500 SordInserter*
 501 sord_inserter_new(SordModel* model,
 502                   SerdEnv*   env);
 503
 504 /**
 505    Free an inserter.
 506 */
 507 SORD_API
 508 void
 509 sord_inserter_free(SordInserter* inserter);
 510
 511 /**
 512    Set the current base URI for writing to the model.
 513
 514    Note this function can be safely casted to SerdBaseSink.
 515 */
 516 SORD_API
 517 SerdStatus
 518 sord_inserter_set_base_uri(SordInserter*   inserter,
 519                            const SerdNode* uri);
 520
 521 /**
 522    Set a namespace prefix for writing to the model.
 523
 524    Note this function can be safely casted to SerdPrefixSink.
 525 */
 526 SORD_API
 527 SerdStatus
 528 sord_inserter_set_prefix(SordInserter*   inserter,
 529                          const SerdNode* name,
 530                          const SerdNode* uri);
 531
 532 /**
 533    Write a statement to the model.
 534
 535    Note this function can be safely casted to SerdStatementSink.
 536 */
 537 SORD_API
 538 SerdStatus
 539 sord_inserter_write_statement(SordInserter*      inserter,
 540                               SerdStatementFlags flags,
 541                               const SerdNode*    graph,
 542                               const SerdNode*    subject,
 543                               const SerdNode*    predicate,
 544                               const SerdNode*    object,
 545                               const SerdNode*    object_datatype,
 546                               const SerdNode*    object_lang);
 547
 548 /**
 549    @}
 550    @name Iteration
 551    @{
 552 */
 553
 554 /**
 555    Set `quad` to the quad pointed to by `iter`.
 556 */
 557 SORD_API
 558 void
 559 sord_iter_get(const SordIter* iter, SordQuad quad);
 560
 561 /**
 562    Return a field of the quad pointed to by `iter`.
 563
 564    Returns NULL if `iter` is NULL or is at the end.
 565 */
 566 SORD_API
 567 const SordNode*
 568 sord_iter_get_node(const SordIter* iter, SordQuadIndex index);
 569
 570 /**
 571    Return the store pointed to by `iter`.
 572 */
 573 SORD_API
 574 const SordModel*
 575 sord_iter_get_model(SordIter* iter);
 576
 577 /**
 578    Increment `iter` to point to the next statement.
 579 */
 580 SORD_API
 581 bool
 582 sord_iter_next(SordIter* iter);
 583
 584 /**
 585    Return true iff `iter` is at the end of its range.
 586 */
 587 SORD_API
 588 bool
 589 sord_iter_end(const SordIter* iter);
 590
 591 /**
 592    Free `iter`.
 593 */
 594 SORD_API
 595 void
 596 sord_iter_free(SordIter* iter);
 597
 598 /**
 599    @}
 600    @name Utilities
 601    @{
 602 */
 603
 604 /**
 605    Match two quads (using ID comparison only).
 606
 607    This function is a straightforward and fast equivalence match with wildcard
 608    support (ID 0 is a wildcard). It does not actually read node data.
 609    @return true iff `x` and `y` match.
 610 */
 611 SORD_API
 612 bool
 613 sord_quad_match(const SordQuad x, const SordQuad y);
 614
 615 /**
 616    @}
 617    @name Serialisation
 618    @{
 619 */
 620
 621 /**
 622    Return a reader that will read into `model`.
 623 */
 624 SORD_API
 625 SerdReader*
 626 sord_new_reader(SordModel* model,
 627                 SerdEnv*   env,
 628                 SerdSyntax syntax,
 629                 SordNode*  graph);
 630
 631 /**
 632    Write a model to a writer.
 633 */
 634 SORD_API
 635 bool
 636 sord_write(SordModel*  model,
 637            SerdWriter* writer,
 638            SordNode*   graph);
 639
 640 /**
 641    Write a range to a writer.
 642
 643    This increments `iter` to its end, then frees it.
 644 */
 645 SORD_API
 646 bool
 647 sord_write_iter(SordIter*   iter,
 648                 SerdWriter* writer);
 649
 650 /**
 651    @}
 652    @}
 653 */
 654
 655 #ifdef __cplusplus
 656 }  /* extern "C" */
 657 #endif
 658
 659 #endif  /* SORD_SORD_H */