diff options
109 files changed, 3673 insertions, 3997 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 16b3373eb..a473dc69e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -82,13 +82,35 @@ check-merge-request: .tracker.fedora@common: variables: - BASE_TAG: '2022-02-10.0' - FDO_DISTRIBUTION_PACKAGES: 'clang clang-analyzer gcovr git libasan libubsan python3-gobject python3-pip umockdev-devel xmlto uncrustify patch diffutils cmake python-devel' + BASE_TAG: '2023-02-27.1' + FDO_DISTRIBUTION_PACKAGES: + clang + clang-analyzer + cmake + diffutils + gcovr + git + libasan + libubsan + patch + python-devel + python3-gobject + python3-jinja2 + python3-markdown + python3-markupsafe + python3-pip + python3-pygments + python3-typogrify + umockdev-devel + xmlto + uncrustify + FDO_DISTRIBUTION_EXEC: | dnf install -y 'dnf-command(builddep)' 'dnf-command(download)' && dnf builddep -y tracker tracker-miners --setopt=install_weak_deps=False && dnf clean all && - pip3 install beautifulsoup4 mkdocs mkdocs-cinder tap.py meson hotdoc && + + pip3 install beautifulsoup4 mkdocs mkdocs-cinder tap.py meson tomli && # Installing gtk-doc docs with dnf does not end up with docs at # /usr/share/gtk-doc, https://gitlab.gnome.org/GNOME/tracker/-/issues/324 dnf download glib2-doc && @@ -220,8 +242,6 @@ check-code-style: script: - meson . build -Ddocs=$([ -z "$NO_DOCS" ] && echo "true" || echo "false") -Db_coverage=true -Db_lto=true -Dsystemd_user_services=false -Dtests_tap_protocol=true --prefix /usr - ninja -C build - - | - if [ -z "$NO_DOCS" ]; then ninja -C build docs/reference/libtracker-sparql/Tracker-doc; fi artifacts: expire_in: 1 day paths: @@ -380,14 +400,12 @@ test-website: - | export tracker_commit=$CI_COMMIT_SHA export tracker_miners_commit=$(git -C ./extra/tracker-miners rev-parse HEAD) - ./docs/website/build.py --output=website --api-docs="$install_prefix/share/doc/Tracker/html" --tracker-commit=${tracker_commit} --man-pages ./docs/manpages/*.txt ./extra/tracker-miners/docs/manpages/*.txt + ./docs/website/build.py --output=website --api-docs="$install_prefix/share/doc/Tracker-3.0" --tracker-commit=${tracker_commit} --man-pages ./docs/manpages/*.txt ./extra/tracker-miners/docs/manpages/*.txt artifacts: paths: - website needs: - build-fedora-container@x86_64 - only: - - master coverage: extends: diff --git a/config.h.meson.in b/config.h.meson.in index befa786a5..df4b880b0 100644 --- a/config.h.meson.in +++ b/config.h.meson.in @@ -10,15 +10,9 @@ /* Defined if Sqlite has FTS5 compiled in */ #mesondefine HAVE_BUILTIN_FTS -/* libicu Unicode support library */ -#mesondefine HAVE_LIBICU - /* Define if we have libstemmer */ #mesondefine HAVE_LIBSTEMMER -/* libunistring Unicode support library */ -#mesondefine HAVE_LIBUNISTRING - /* Define to 1 if you have the `statvfs64' function. */ #mesondefine HAVE_STATVFS64 diff --git a/docs/reference/libtracker-sparql/base-ontology.md b/docs/reference/libtracker-sparql/base-ontology.md deleted file mode 100644 index 8eec6a707..000000000 --- a/docs/reference/libtracker-sparql/base-ontology.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Base ontology -short-description: Base for defining ontologies -... - -# Base ontology - -The base ontology is the seed for defining application-specific -ontologies. It defines the basic types and property/class -definitions themselves, so that classes and properties may be -created. - diff --git a/docs/reference/libtracker-sparql/defining-ontologies.md b/docs/reference/libtracker-sparql/defining-ontologies.md deleted file mode 100644 index 24746453d..000000000 --- a/docs/reference/libtracker-sparql/defining-ontologies.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: Defining ontologies -short-description: Defining Ontologies -... - -# Defining ontologies - -An ontology defines the entities that a Tracker endpoint can store, as -well as their properties and the relationships between different entities. - -Tracker internally uses the following ontologies as its base, all ontologies -defined by the user of the endpoint are recommended to be build around this -base: - -- XML Schema (XSD), defining basic types -- Resource Description Framework (RDF), defining classes, properties and - inheritance -- Nepomuk Resource Language (NRL), defining resource uniqueness, inheritance - and indexes. -- Dublin Core (DC), defining common superproperties for documents - -Ontologies are Turtle files with the .ontology extension, Tracker parses all -ontology files from the given directory. The individual ontology files may -not be self-consistent (i.e. use missing definitions), but -all the ontology files as a whole must be. - -Tracker loads the ontology files in alphanumeric order, it is advisable -that those have a numbered prefix in order to load those at a consistent -order despite future additions. - -## Creating an ontology - -### Defining a namespace - -A namespace is the topmost layer of an individual ontology, it will -contain all classes and properties defined by it. In order to define -a namespace you can do: - -```turtle -# These prefixes will be used in the definition of the ontology, -# thus must be explicitly defined -@prefix nrl: <http://tracker.api.gnome.org/ontology/v3/nrl#> . -@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . -@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . -@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . - -# This is our example namespace -@prefix ex: <http://example.org/#> - -ex: a nrl:Namespace, nrl:Ontology - nrl:prefix "ex" - rdfs:comment "example ontology" - nrl:lastModified "2017-01-01T15:00:00Z" -``` - -### Defining classes - -Classes are the base of an ontology, all stored resources must define -themselves as "being" at least one of these classes. They all derive -from the base rdfs:Resource type. To eg. define classes representing -animals and plants, you can do: - -```turtle -ex:Eukaryote a rdfs:Class; - rdfs:subClassOf rdfs:Resource; - rdfs:comment "An eukaryote". -``` - -By convention all classes use CamelCase names, although class names -are not restricted. The allowed charset is UTF-8. - -Declaring subclasses is possible: - -```turtle -ex:Animal a rdfs:Class; - rdfs:subClassOf ex:Eukaryote; - rdfs:comment "An animal". - -ex:Plant a rdfs:Class; - rdfs:subClassOf ex:Eukaryote; - rdfs:comment "A plant". - -ex:Mammal a rdfs:Class; - rdfs:subClassOf ex:Animal; - rdfs:comment "A mammal". -``` - -With such classes defined, resources may be inserted to the endpoint, -eg. with the SPARQL: - -```SPARQL -INSERT DATA { <merry> a ex:Mammal } -INSERT DATA { <treebeard> a ex:Animal, ex:Plant } -``` - -Note that multiple inheritance is possible, resources will just inherit -all properties from all classes and superclasses. - -### Defining properties - -Properties relate to a class, so all resources pertaining to that class -can define values for these. - -```turtle -ex:cromosomes a rdf:Property; - rdfs:domain ex:Eukaryote; - rdfs:range xsd:integer. - -ex:unicellular a rdf:Property; - rdfs:domain ex:Eukaryote; - rdfs:range xsd:bool; - -ex:dateOfBirth a rdf:Property; - rdfs:domain ex:Mammal; - rdfs:range xsd:dateTime; -``` - -The class the property belongs to is defined by `rdfs:domain`, while the -data type contained is defined by `rdfs:range`. By convention all -properties use dromedaryCase names, although property names are not -restricted. The allowed charset is UTF-8. - -The following basic types are supported: - -- `xsd:boolean` -- `xsd:string` and `rdf:langString` -- `xsd:integer`, ranging from -2^63 to 2^63-1. -- `xsd:double`, able to store a 8 byte IEEE floating point number. -- `xsd:date` and `xsd:dateTime`, able to store dates and times since - January 1st 1 AD, with microsecond resolution. - -Of course, properties can also point to resources of the same or -other classes, so stored resources can conform a graph: - -```turtle -ex:parent a rdf:Property; - rdfs:domain ex:Mammal; - rdfs:range ex:Mammal; - -ex:pet a rdf:Property; - rdfs:domain ex:Mammal; - rdfs:range ex:Eukaryote; -``` - -There is also inheritance of properties, an example would be a property -in a subclass concretizing a more generic property from a superclass. - -```turtle -ex:geneticInformation a rdf:Property; - rdfs:domain ex:Eukaryote; - rdfs:range xsd:string; - -ex:dna a rdf:Property; - rdfs:domain ex:Mammal; - rdfs:range xsd:string; - rdfs:subPropertyOf ex:geneticInformation. -``` - -SPARQL queries are expected to provide the same result when queried -for a property or one of its superproperties. - -```SPARQL -# These two queries should provide the exact same result(s) -SELECT { ?animal a ex:Animal; - ex:geneticInformation "AGCT" } -SELECT { ?animal a ex:Animal; - ex:dna "AGCT" } -``` - -### Defining cardinality of properties - -By default, properties are multivalued, there are no restrictions in -the number of values a property can store. - -```SPARQL -INSERT DATA { - <cat> a ex:Mammal . - <dog> a ex:Mammal . - - <peter> a ex:Mammal ; - ex:pets <cat>, <dog> -} -``` - -Wherever this is not desirable, cardinality can be limited on properties -through nrl:maxCardinality. - -```turtle -ex:cromosomes a rdf:Property; - rdfs:domain ex:Eukaryote; - rdfs:range xsd:integer; - nrl:maxCardinality 1. -``` - -This will raise an error if the SPARQL updates in the endpoint end up -in the property inserted multiple times. - -```SPARQL -# This will fail -INSERT DATA { <cat> a ex:Mammal; - ex:cromosomes 38; - ex:cromosomes 42 } - -# This will succeed -INSERT DATA { <donald> a ex:Mammal; - ex:cromosomes 47 } -``` - -Tracker does not implement support for other maximum cardinalities -than 1. - -<!--- - XXX: explain how cardinality affects subproperties, superproperties ----> - -### Defining uniqueness - -It is desirable for certain properties to keep their values unique -across all resources, this can be expressed by defining the properties -as being a nrl:InverseFunctionalProperty. - -```turtle -ex:geneticInformation a rdf:Property, nrl:InverseFunctionalProperty; - rdfs:domain ex:Eukaryote; - rdfs:range xsd:string; -``` - -With that in place, no two resources can have the same value on the -property. - -```SPARQL -# First insertion, this will succeed -INSERT DATA { <drosophila> a ex:Eukariote; - ex:geneticInformation "AGCT" } - -# This will fail -INSERT DATA { <melanogaster> a ex:Eukariote; - ex:geneticInformation "AGCT" } -``` - -<!--- - XXX: explain how inverse functional proeprties affect sub/superproperties ----> - -### Defining indexes - -It may be the case that SPARQL queries performed on the endpoint are -known to match, sort, or filter on certain properties more often than others. -In this case, the ontology may use nrl:domainIndex in the class definition: - -```turtle -# Make queries on ex:dateOfBirth faster -ex:Mammal a rdfs:Class; - rdfs:subClassOf ex:Animal; - rdfs:comment "A mammal"; - nrl:domainIndex ex:dateOfBirth. -``` - -Classes may define multiple domain indexes. - -**Note**: Be frugal with indexes, do not add these proactively. An index in the wrong -place might not affect query performance positively, but all indexes come at -a cost in disk size. - -### Defining full-text search properties - -Tracker provides nonstandard full-text search capabilities, in order to use -these, the string properties can use nrl:fulltextIndexed: - -```turtle -ex:name a rdf:Property; - rdfs:domain ex:Mammal; - rdfs:range xsd:string; - nrl:fulltextIndexed true; - nrl:weight 10. -``` - -Weighting can also be applied, so certain properties rank higher than others -in full-text search queries. With nrl:fulltextIndexed in place, sparql -queries may use full-text search capabilities: - -```SPARQL -SELECT { ?mammal a ex:Mammal; - fts:match "timmy" } -``` - -### Predefined elements - -It may be desirable for the ontology to offer predefined elements of a -certain class, which can then be used by the endpoint. - -```turtle -ex:self a ex:Mammal. -``` - -Usage does not differ in use from the elements of that same class that -could be inserted in the endpoint. - -```SPARQL -INSERT DATA { ex:self ex:pets <cat> . - <cat> ex:pets ex:self } -``` - -### Accompanying metadata - -Ontology files are optionally accompanied by description files, those have -the same basename, but the ".description" extension. - -```turtle -@prefix dsc: <http://tracker.api.gnome.org/ontology/v3/dsc#> . - -<virtual-ontology-uri:30-nie.ontology> a dsc:Ontology ; - dsc:title "Example ontology" ; - dsc:description "A little bit of this and that." ; - dsc:upstream "http://www.example.org/ontologies"; - dsc:author "John doe, <john@example.org>"; - dsc:editor "Jane doe, <jane@example.org>"; - dsc:gitlog "http://git.example.org/cgit/tracker/log/example.ontology"; - dsc:contributor "someone else, <some1@example.org>"; - - dsc:localPrefix "ex" ; - dsc:baseUrl "http://www.example.org/ontologies/ex#"; - dsc:relativePath "./10-ex.ontology" ; - - dsc:copyright "All rights given away". -``` - -## Updating an ontology - -As software evolves, sometimes changes in the ontology are unavoidable. -Tracker can transparently handle certain ontology changes on existing -databases. - -1. Adding a class. -2. Removing a class. - All resources will be removed from this class, and all related - properties will disappear. -3. Adding a property. -4. Removing a property. - The property will disappear from all elements pertaining to the - class in domain of the property. -5. Changing rdfs:range of a property. - The following conversions are allowed: - - - `xsd:integer` to `xsd:bool`, `xsd:double` and `xsd:string`</listitem></varlistentry> - - `xsd:double` to `xsd:bool`, `xsd:integer` and `xsd:string`</listitem></varlistentry> - - `xsd:string` to `xsd:bool`, `xsd:integer` and `xsd:double`</listitem></varlistentry> - -6. Adding and removing `nrl:domainIndex` from a class. -7. Adding and removing `nrl:fulltextIndexed` from a property. -8. Changing the `nrl:weight` on a property. -9. Removing `nrl:maxCardinality` from a property. - -<!--- - XXX: these need documenting too - add intermediate superproperties - add intermediate superclasses - remove intermediate superproperties - remove intermediate superclasses ----> - -However, there are certain ontology changes that Tracker will find -incompatible. Either because they are incoherent or resulting into -situations where it can not deterministically satisfy the change -in the stored data. Tracker will error out and refuse to do any data -changes in these situations: - -- Properties with rdfs:range being `xsd:bool`, `xsd:date`, `xsd:dateTime`, - or any other custom class are not convertible. Only conversions - covered in the list above are accepted. -- You can not add `rdfs:subClassOf` in classes that are not being - newly added. You can not remove `rdfs:subClassOf` from classes. - The only allowed change to `rdfs:subClassOf` is to correct - subclasses when deleting a class, so they point a common - superclass. -- You can not add `rdfs:subPropertyOf` to properties that are not - being newly added. You can not change an existing - `rdfs:subPropertyOf` unless it is made to point to a common - superproperty. You can however remove `rdfs:subPropertyOf` from - non-new properties. -- Properties can not move across classes, thus any change in - `rdfs:domain` is forbidden. -- You can not add `nrl:maxCardinality` restrictions on properties that - are not being newly added. -- You can not add nor remove `nrl:InverseFunctionalProperty` from a - property that is not being newly added. - -The recommendation to bypass these situations is the same for all, -use different property and class names and use SPARQL to manually -migrate the old data to the new format if necessary. - -High level code is in a better position to solve the -possible incoherences (e.g. picking a single value if a property -changes from multiple values to single value). After the manual -data migration has been completed, the old classes and properties -can be dropped. - -Once changes are made, the nrl:lastModified value should be updated -so Tracker knows to reprocess the ontology. diff --git a/docs/reference/libtracker-sparql/dist-docs.sh b/docs/reference/libtracker-sparql/dist-docs.sh index 49e04aa8a..5511d5427 100644 --- a/docs/reference/libtracker-sparql/dist-docs.sh +++ b/docs/reference/libtracker-sparql/dist-docs.sh @@ -1,33 +1,13 @@ #!/bin/sh -docs_name=$1 - -pushd ${MESON_SOURCE_ROOT} -files=`git clean -nx docs/reference/libtracker-sparql/theme-extra/` -if [ -n "$files" ] -then - echo "Directory 'theme-extra' is unclean:" - echo -e "$files" - exit -1 -fi -popd - pushd $MESON_BUILD_ROOT # Ensure the build tree is compiled, we need generated files ninja -# Run hotdoc manually -pushd docs/reference/libtracker-sparql -hotdoc run --conf-file ${docs_name}-doc.json - # Generate fixed .devhelp2 file -${MESON_SOURCE_ROOT}/docs/reference/libtracker-sparql/generate-devhelp.sh $1 +. ${MESON_SOURCE_ROOT}/docs/reference/libtracker-sparql/generate-devhelp.sh $1 $2 # And copy the resulting devhelp documentation into the dist location -mv ${docs_name}-doc/devhelp/ ${MESON_DIST_ROOT}/docs/reference/libtracker-sparql/ - -# Delete the remaining docs -rm -rf ${docs_name}-doc/ +cp -a $2 ${MESON_DIST_ROOT}/docs/reference/libtracker-sparql/ popd -popd diff --git a/docs/reference/libtracker-sparql/embed-files.py b/docs/reference/libtracker-sparql/embed-files.py new file mode 100644 index 000000000..05354d91d --- /dev/null +++ b/docs/reference/libtracker-sparql/embed-files.py @@ -0,0 +1,29 @@ +#!/bin/env python3 + +import os, sys, re + +f = open(sys.argv[1]) +content = f.read() +f.close() + +dirname = os.path.dirname(sys.argv[1]) + +regex = re.compile('{{(.*)}}') +matches = regex.findall(content) +replacements = {} + +for m in matches: + try: + f = open(os.path.join(dirname, m.strip())) + embedded = f.read() + except: + embedded = '' + + escaped = embedded.replace('\\', '\\\\') + replace = re.compile('{{' + m + '}}') + content = replace.sub(escaped, content) + f.close() + +f = open(sys.argv[2], 'w') +f.write(content) +f.close() diff --git a/docs/reference/libtracker-sparql/examples.md b/docs/reference/libtracker-sparql/examples.md deleted file mode 100644 index 474ac46d8..000000000 --- a/docs/reference/libtracker-sparql/examples.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Examples -short-description: Examples -... - -# Examples - -This chapters shows some real examples of usage of the Tracker -SPARQL Library. - -## Querying a remote endpoint - -All SPARQL queries happen on a [](TrackerSparqlConnection), often these -connections represent a remote endpoints maintained by another process or -server. - -This example demonstrates the use of these connections on a remote -endpoint. Concretely creating a D-Bus [](TrackerSparqlConnection), -creating a prepared statement from a SPARQL query string, executing -the query, and obtaining the query results from the cursor. - -The [](tracker_sparql_connection_query_statement) function can be used -to obtain a [](TrackerSparqlStatement) object holding a prepared SPARQL -query that can then be executed with [](tracker_sparql_statement_execute). -The query string can contain `~name` placeholders which can be replaced with -arbitrary values before query execution with -[](tracker_sparql_statement_bind_string) and similar functions. -This allows parsing the query string only once and to execute it multiple -times with different parameters with potentially significant performance gains. - -Multiple functions offer asynchronous variants, so the application -main loop is not blocked while these operations are executed. - -Once you end up with the query, remember to call [](tracker_sparql_cursor_close). -The same applies to [](tracker_sparql_connection_close) when no longer needed. - -<div class="gi-lang-c"> - -{{ examples/connection-example.c }} - -</div> -<div class="gi-lang-python"> - -{{ examples/connection-example.py }} - -</div> -<div class="gi-lang-javascript"> - -{{ examples/connection-example.js }} - -</div> - -## Creating a private database - -Applications may create private stores via the [](tracker_sparql_connection_new) -constructor. - -This example demonstrates the creation of a private store, for simplicity the -example uses the builtin Nepomuk ontology, but the data structures may be defined -by the application, see the documentation on -[defining ontologies](defining-ontologies.md) for more information about this. - -The example also demonstrates the use of [](TrackerResource) and [](TrackerBatch) -for insertion of RDF data. It is also possible the direct use of SPARQL update -strings via [](tracker_sparql_connection_update). - -Multiple functions offer asynchronous variants, so the application -main loop is not blocked while these operations are executed. - -Once you no longer need the connection, remember to call -[](tracker_sparql_connection_close) on the [](TrackerSparqlConnection). - -<div class="gi-lang-c"> - -{{ examples/private-store-example.c }} - -</div> -<div class="gi-lang-python"> - -{{ examples/private-store-example.py }} - -</div> -<div class="gi-lang-javascript"> - -{{ examples/private-store-example.js }} - -</div> - -## Creating a SPARQL endpoint - -For some applications and services, it might be desirable to export a -SPARQL store as an endpoint. Making it possible for other applications to -query the data they hold. - -This example demonstrates the use of [](TrackerEndpoint) subclasses, -concretely the creation of a D-Bus endpoint, that other applications -may query e.g. through a connection created with -[](tracker_sparql_connection_bus_new). - -<div class="gi-lang-c"> - -{{ examples/endpoint-example.c }} - -</div> -<div class="gi-lang-python"> - -{{ examples/endpoint-example.py }} - -</div> -<div class="gi-lang-javascript"> - -{{ examples/endpoint-example.js }} - -</div> - -## Receiving notification on changes - -As an additional feature over SPARQL endpoints, Tracker allows for -users of private and D-Bus SPARQL connections to receive notifications -on changes of certain RDF classes (Those with the -[nrl:notify](nrl-ontology.md#nrl:notify) property, like -[nmm:MusicPiece](nmm-ontology.md#nmm:MusicPiece)). - -This example demonstrates the use of [](TrackerNotifier) to receive -notifications on database updates. - -<div class="gi-lang-c"> - -{{ examples/notifier-example.c }} - -</div> -<div class="gi-lang-python"> - -{{ examples/notifier-example.py }} - -</div> -<div class="gi-lang-javascript"> - -{{ examples/notifier-example.js }} - -</div> diff --git a/docs/reference/libtracker-sparql/examples.md.in b/docs/reference/libtracker-sparql/examples.md.in new file mode 100644 index 000000000..37e4ca22b --- /dev/null +++ b/docs/reference/libtracker-sparql/examples.md.in @@ -0,0 +1,132 @@ +Title: Examples + +This document shows some real examples of usage of the Tracker +SPARQL Library. + +## Querying a remote endpoint + +All SPARQL queries happen through a [class@Tracker.SparqlConnection], often +these connections represent a remote endpoints maintained by another process or +server. + +This example demonstrates the use of these connections on a remote +endpoint. Concretely creating a D-Bus [class@Tracker.SparqlConnection], +creating a prepared statement from a SPARQL query string, executing +the query, and obtaining the query results from the cursor. + +The [method@Tracker.SparqlConnection.query_statement] method can be used +to obtain a [class@Tracker.SparqlStatement] object holding a prepared SPARQL +query that can then be executed with [method@Tracker.SparqlStatement.execute]. +The query string can contain `~name` placeholders which can be replaced with +arbitrary values before query execution with +[method@Tracker.SparqlStatement.bind_string] and similar functions. +This allows parsing the query string only once and to execute it multiple +times with different parameters with potentially significant performance gains. + +Multiple functions offer asynchronous variants, so the application +main loop is not blocked while these operations are executed. + +Once you end up with the query, remember to call [method@Tracker.SparqlCursor.close]. +The same applies to [method@Tracker.SparqlConnection.close] when no longer needed. + +In C: +```c +{{ examples/connection-example.c }} +``` + +In Python: +```python +{{ examples/connection-example.py }} +``` + +In Javascript: +```js +{{ examples/connection-example.js }} +``` + +## Creating a private database + +Applications may create private RDF triple stores via the [ctor@Tracker.SparqlConnection.new] +constructor. + +This example demonstrates the creation of a private store, for simplicity the +example uses the builtin Nepomuk ontology, but the data structures may be defined +by the application, see the documentation on +[creating custom ontologies](ontologies.html#creating-custom-ontologies) for more information about this. + +The example also demonstrates the use of [class@Tracker.Resource] and [class@Tracker.Batch] +for insertion of RDF data. It is also possible to use [class@Tracker.SparqlStatement] for +updates through the [method@Tracker.Batch.add_statement] methods, or plain SPARQL strings +through [method@Tracker.Batch.add_sparql]. + +Multiple functions offer asynchronous variants, so the application +main loop is not blocked while these operations are executed. + +Once you no longer need the connection, remember to call [method@Tracker.SparqlConnection.close]. + +In C: +```c +{{ examples/private-store-example.c }} +``` + +In Python: +```python +{{ examples/private-store-example.py }} +``` + +In Javascript: +```js +{{ examples/private-store-example.js }} +``` + +## Creating a SPARQL endpoint + +For some applications and services, it might be desirable to export a +RDF triple store as an endpoint. Making it possible for other applications to +query the data they hold. + +This example demonstrates the use of [class@Tracker.Endpoint] subclasses, +concretely the creation of a D-Bus endpoint, that other applications +may query e.g. through a connection created with +[ctor@Tracker.SparqlConnection.bus_new]. + +In C: +```c +{{ examples/endpoint-example.c }} +``` + +In Python: +``` python +{{ examples/endpoint-example.py }} +``` + +In Javascript: +```js +{{ examples/endpoint-example.js }} +``` + +## Receiving notification on changes + +As an additional feature over SPARQL endpoints, Tracker allows for +users of private and D-Bus SPARQL connections to receive notifications +on changes of certain RDF classes (Those with the +[nrl:notify](nrl-ontology.html#nrl:notify) property, like +[nmm:MusicPiece](nmm-ontology.html#nmm:MusicPiece)). + +This example demonstrates the use of [class@Tracker.Notifier] to receive +notifications on database updates. + +In C: +```c +{{ examples/notifier-example.c }} +``` + +In Python: +```python +{{ examples/notifier-example.py }} +``` + +In Javascript: +```js +{{ examples/notifier-example.js }} +``` diff --git a/docs/reference/libtracker-sparql/generate-devhelp.sh b/docs/reference/libtracker-sparql/generate-devhelp.sh index cb7010782..34581451a 100755 --- a/docs/reference/libtracker-sparql/generate-devhelp.sh +++ b/docs/reference/libtracker-sparql/generate-devhelp.sh @@ -1,27 +1,23 @@ #!/bin/sh -cd ${MESON_BUILD_ROOT}/docs/reference/libtracker-sparql/ - docs_name=$1 -docs_path="${docs_name}-doc/devhelp/books/${docs_name}" -devhelp_file="${docs_path}/*.devhelp2" - -# Step 1. Build devhelp documentation (we let meson do this) -# hotdoc run --conf-file '${docs_name}-doc.json' --devhelp-activate - -# Step 2. Fix .devhelp2 file so it contains keywords from out ontologies -cat $devhelp_file | sed "s/<\/functions>//" - | sed "s/<\/book>//" - >fixed.devhelp2 +docs_path=$2 +devhelp_file="${docs_name}/${docs_name}.devhelp2" -for i in *-ontology.keywords -do - cat $i >>fixed.devhelp2 -done +pushd $docs_path >/dev/null +# Fix .devhelp2 file so it contains keywords from out ontologies +cat $devhelp_file | sed "s/<\/functions>//" - | sed "s/<\/book>//" - >fixed.devhelp2 2>/dev/null +cat ../*-ontology.keywords >>fixed.devhelp2 2>/dev/null +rm ../*-ontology.keywords 2>/dev/null echo -e " </functions>\n</book>" >>fixed.devhelp2 + +# Replace devhelp2 file mv fixed.devhelp2 $devhelp_file -# Step 3. Trim unnecessary data -rm ${docs_path}/assets/fonts/*.woff* -rm ${docs_path}/assets/fonts/*.svg -rm -rf ${docs_path}/assets/js/search -find ${docs_path} -name "dumped.trie" -delete +# Also fix index.json file for web UI search +index_json="${docs_name}/index.json" +python3 ${MESON_SOURCE_ROOT}/docs/reference/libtracker-sparql/merge-json.py $index_json ../*-ontology.index.json +rm ../*-ontology.index.json 2>/dev/null + +popd >/dev/null diff --git a/docs/reference/libtracker-sparql/generate-svgs.sh b/docs/reference/libtracker-sparql/generate-svgs.sh new file mode 100644 index 000000000..c1e15c182 --- /dev/null +++ b/docs/reference/libtracker-sparql/generate-svgs.sh @@ -0,0 +1,13 @@ +#!/bin/sh +command=$1 +docs_path=$2 + +pushd $docs_path >/dev/null + +for i in *.dot +do + filename=`basename -s ".dot" "$i"` + $command -Tsvg $i >$filename.svg +done + +popd >/dev/null diff --git a/docs/reference/libtracker-sparql/gi-index.md b/docs/reference/libtracker-sparql/gi-index.md deleted file mode 100644 index 8913fd4b8..000000000 --- a/docs/reference/libtracker-sparql/gi-index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: API reference -... - -# API reference diff --git a/docs/reference/libtracker-sparql/images/triple-graph-1.dot b/docs/reference/libtracker-sparql/images/triple-graph-1.dot index 319417d5c..7625533fc 100644 --- a/docs/reference/libtracker-sparql/images/triple-graph-1.dot +++ b/docs/reference/libtracker-sparql/images/triple-graph-1.dot @@ -1,9 +1,9 @@ digraph G { rankdir=LR; - graph [bgcolor="#00000000"]; - node [fontname="Cantarell", style="filled", shape="ellipse", color="#000000", fillcolor="#d8e5e5"]; Subject; - node [shape="rectangle", color="#000000", fillcolor="#add8e6"]; Object; - edge [fontname="Cantarell"]; + bgcolor=transparent; + node [shape="box", border=0, fontname="sans-serif"]; Object; + node [shape="box", style="rounded", border=0, fontname="sans-serif"]; Subject; + edge [fontname="sans-serif", fontsize=10]; Subject -> Object [label=Predicate]; } diff --git a/docs/reference/libtracker-sparql/images/triple-graph-1.png b/docs/reference/libtracker-sparql/images/triple-graph-1.png Binary files differdeleted file mode 100644 index 2cf93dbe8..000000000 --- a/docs/reference/libtracker-sparql/images/triple-graph-1.png +++ /dev/null diff --git a/docs/reference/libtracker-sparql/images/triple-graph-1.svg b/docs/reference/libtracker-sparql/images/triple-graph-1.svg new file mode 100644 index 000000000..3dd8b9991 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/triple-graph-1.svg @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 7.1.0 (0) + --> +<!-- Title: G Pages: 1 --> +<svg width="213pt" height="44pt" + viewBox="0.00 0.00 213.00 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)"> +<title>G</title> +<!-- Object --> +<g id="node1" class="node"> +<title>Object</title> +<polygon fill="none" stroke="black" points="205,-36 145,-36 145,0 205,0 205,-36"/> +<text text-anchor="middle" x="175" y="-14.3" font-family="sans-serif" font-size="14.00">Object</text> +</g> +<!-- Subject --> +<g id="node2" class="node"> +<title>Subject</title> +<path fill="none" stroke="black" d="M53,-36C53,-36 12,-36 12,-36 6,-36 0,-30 0,-24 0,-24 0,-12 0,-12 0,-6 6,0 12,0 12,0 53,0 53,0 59,0 65,-6 65,-12 65,-12 65,-24 65,-24 65,-30 59,-36 53,-36"/> +<text text-anchor="middle" x="32.5" y="-14.3" font-family="sans-serif" font-size="14.00">Subject</text> +</g> +<!-- Subject->Object --> +<g id="edge1" class="edge"> +<title>Subject->Object</title> +<path fill="none" stroke="black" d="M65.38,-18C85.47,-18 111.59,-18 133.18,-18"/> +<polygon fill="black" stroke="black" points="133.13,-21.5 143.13,-18 133.13,-14.5 133.13,-21.5"/> +<text text-anchor="middle" x="105" y="-21" font-family="sans-serif" font-size="10.00">Predicate</text> +</g> +</g> +</svg> diff --git a/docs/reference/libtracker-sparql/images/triple-graph-2.dot b/docs/reference/libtracker-sparql/images/triple-graph-2.dot index 1187da0ec..70c981866 100644 --- a/docs/reference/libtracker-sparql/images/triple-graph-2.dot +++ b/docs/reference/libtracker-sparql/images/triple-graph-2.dot @@ -1,9 +1,9 @@ digraph G { rankdir=LR; - graph [bgcolor="#00000000"]; - node [fontname="Cantarell", style="filled", shape="ellipse", color="#000000", fillcolor="#d8e5e5"]; "http://example.com/Song", "nfo:FileDataObject", "nmm:MusicPiece", "http://example.com/Album", "http://example.com/Jason", "http://example.com/Marty", "http://example.com/Band"; - node [shape="rectangle", color="#000000", fillcolor="#add8e6"]; Images, "Go Off!", "Marty Friedman", "Jason Becker", "Cacophony"; - edge [fontname="Cantarell"]; + bgcolor=transparent; + node [shape="box", border=0, fontname="sans-serif"]; Images, "Go Off!", "Marty Friedman", "Jason Becker", "Cacophony"; + node [shape="box", style="rounded", border=0, fontname="sans-serif"]; "http://example.com/Song", "nfo:FileDataObject", "nmm:MusicPiece", "http://example.com/Album", "http://example.com/Jason", "http://example.com/Marty", "http://example.com/Band"; + edge [fontname="sans-serif", fontsize=10]; "http://example.com/Song" -> "nfo:FileDataObject" [label="rdf:type"]; "http://example.com/Song" -> "nmm:MusicPiece" [label="rdf:type"]; diff --git a/docs/reference/libtracker-sparql/images/triple-graph-2.png b/docs/reference/libtracker-sparql/images/triple-graph-2.png Binary files differdeleted file mode 100644 index d80ce6d90..000000000 --- a/docs/reference/libtracker-sparql/images/triple-graph-2.png +++ /dev/null diff --git a/docs/reference/libtracker-sparql/images/triple-graph-2.svg b/docs/reference/libtracker-sparql/images/triple-graph-2.svg new file mode 100644 index 000000000..94bfb3aff --- /dev/null +++ b/docs/reference/libtracker-sparql/images/triple-graph-2.svg @@ -0,0 +1,161 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 7.1.0 (0) + --> +<!-- Title: G Pages: 1 --> +<svg width="743pt" height="368pt" + viewBox="0.00 0.00 743.00 368.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 364)"> +<title>G</title> +<!-- Images --> +<g id="node1" class="node"> +<title>Images</title> +<polygon fill="none" stroke="black" points="433.5,-360 368.5,-360 368.5,-324 433.5,-324 433.5,-360"/> +<text text-anchor="middle" x="401" y="-338.3" font-family="sans-serif" font-size="14.00">Images</text> +</g> +<!-- Go Off! --> +<g id="node2" class="node"> +<title>Go Off!</title> +<polygon fill="none" stroke="black" points="706,-198 642,-198 642,-162 706,-162 706,-198"/> +<text text-anchor="middle" x="674" y="-176.3" font-family="sans-serif" font-size="14.00">Go Off!</text> +</g> +<!-- Marty Friedman --> +<g id="node3" class="node"> +<title>Marty Friedman</title> +<polygon fill="none" stroke="black" points="735,-90 613,-90 613,-54 735,-54 735,-90"/> +<text text-anchor="middle" x="674" y="-68.3" font-family="sans-serif" font-size="14.00">Marty Friedman</text> +</g> +<!-- Jason Becker --> +<g id="node4" class="node"> +<title>Jason Becker</title> +<polygon fill="none" stroke="black" points="724.5,-144 623.5,-144 623.5,-108 724.5,-108 724.5,-144"/> +<text text-anchor="middle" x="674" y="-122.3" font-family="sans-serif" font-size="14.00">Jason Becker</text> +</g> +<!-- Cacophony --> +<g id="node5" class="node"> +<title>Cacophony</title> +<polygon fill="none" stroke="black" points="719,-36 629,-36 629,0 719,0 719,-36"/> +<text text-anchor="middle" x="674" y="-14.3" font-family="sans-serif" font-size="14.00">Cacophony</text> +</g> +<!-- http://example.com/Song --> +<g id="node6" class="node"> +<title>http://example.com/Song</title> +<path fill="none" stroke="black" d="M172,-198C172,-198 12,-198 12,-198 6,-198 0,-192 0,-186 0,-186 0,-174 0,-174 0,-168 6,-162 12,-162 12,-162 172,-162 172,-162 178,-162 184,-168 184,-174 184,-174 184,-186 184,-186 184,-192 178,-198 172,-198"/> +<text text-anchor="middle" x="92" y="-176.3" font-family="sans-serif" font-size="14.00">http://example.com/Song</text> +</g> +<!-- http://example.com/Song->Images --> +<g id="edge3" class="edge"> +<title>http://example.com/Song->Images</title> +<path fill="none" stroke="black" d="M111.84,-198.33C132.65,-217.87 167.75,-248.87 202,-270 244.17,-296.02 257.37,-298.25 304,-315 321.08,-321.13 340.26,-326.77 356.97,-331.29"/> +<polygon fill="black" stroke="black" points="356.06,-334.67 366.62,-333.84 357.85,-327.9 356.06,-334.67"/> +<text text-anchor="middle" x="244" y="-310" font-family="sans-serif" font-size="10.00">nie:title</text> +</g> +<!-- nfo:FileDataObject --> +<g id="node7" class="node"> +<title>nfo:FileDataObject</title> +<path fill="none" stroke="black" d="M459,-306C459,-306 343,-306 343,-306 337,-306 331,-300 331,-294 331,-294 331,-282 331,-282 331,-276 337,-270 343,-270 343,-270 459,-270 459,-270 465,-270 471,-276 471,-282 471,-282 471,-294 471,-294 471,-300 465,-306 459,-306"/> +<text text-anchor="middle" x="401" y="-284.3" font-family="sans-serif" font-size="14.00">nfo:FileDataObject</text> +</g> +<!-- http://example.com/Song->nfo:FileDataObject --> +<g id="edge1" class="edge"> +<title>http://example.com/Song->nfo:FileDataObject</title> +<path fill="none" stroke="black" d="M132.21,-198.42C152.78,-207.79 178.52,-219.06 202,-228 246.53,-244.96 258.39,-247.21 304,-261 309.85,-262.77 315.92,-264.56 322.02,-266.34"/> +<polygon fill="black" stroke="black" points="320.99,-269.69 331.57,-269.1 322.93,-262.96 320.99,-269.69"/> +<text text-anchor="middle" x="244" y="-258" font-family="sans-serif" font-size="10.00">rdf:type</text> +</g> +<!-- nmm:MusicPiece --> +<g id="node8" class="node"> +<title>nmm:MusicPiece</title> +<path fill="none" stroke="black" d="M453.5,-252C453.5,-252 348.5,-252 348.5,-252 342.5,-252 336.5,-246 336.5,-240 336.5,-240 336.5,-228 336.5,-228 336.5,-222 342.5,-216 348.5,-216 348.5,-216 453.5,-216 453.5,-216 459.5,-216 465.5,-222 465.5,-228 465.5,-228 465.5,-240 465.5,-240 465.5,-246 459.5,-252 453.5,-252"/> +<text text-anchor="middle" x="401" y="-230.3" font-family="sans-serif" font-size="14.00">nmm:MusicPiece</text> +</g> +<!-- http://example.com/Song->nmm:MusicPiece --> +<g id="edge2" class="edge"> +<title>http://example.com/Song->nmm:MusicPiece</title> +<path fill="none" stroke="black" d="M184.28,-196.06C229.22,-203.96 282.73,-213.37 325.21,-220.85"/> +<polygon fill="black" stroke="black" points="324.38,-224.25 334.83,-222.54 325.59,-217.36 324.38,-224.25"/> +<text text-anchor="middle" x="244" y="-216" font-family="sans-serif" font-size="10.00">rdf:type</text> +</g> +<!-- http://example.com/Album --> +<g id="node9" class="node"> +<title>http://example.com/Album</title> +<path fill="none" stroke="black" d="M486,-198C486,-198 316,-198 316,-198 310,-198 304,-192 304,-186 304,-186 304,-174 304,-174 304,-168 310,-162 316,-162 316,-162 486,-162 486,-162 492,-162 498,-168 498,-174 498,-174 498,-186 498,-186 498,-192 492,-198 486,-198"/> +<text text-anchor="middle" x="401" y="-176.3" font-family="sans-serif" font-size="14.00">http://example.com/Album</text> +</g> +<!-- http://example.com/Song->http://example.com/Album --> +<g id="edge4" class="edge"> +<title>http://example.com/Song->http://example.com/Album</title> +<path fill="none" stroke="black" d="M184.28,-180C218.25,-180 257.11,-180 292.41,-180"/> +<polygon fill="black" stroke="black" points="292.22,-183.5 302.22,-180 292.22,-176.5 292.22,-183.5"/> +<text text-anchor="middle" x="244" y="-183" font-family="sans-serif" font-size="10.00">nmm:musicAlbum</text> +</g> +<!-- http://example.com/Jason --> +<g id="node10" class="node"> +<title>http://example.com/Jason</title> +<path fill="none" stroke="black" d="M482,-144C482,-144 320,-144 320,-144 314,-144 308,-138 308,-132 308,-132 308,-120 308,-120 308,-114 314,-108 320,-108 320,-108 482,-108 482,-108 488,-108 494,-114 494,-120 494,-120 494,-132 494,-132 494,-138 488,-144 482,-144"/> +<text text-anchor="middle" x="401" y="-122.3" font-family="sans-serif" font-size="14.00">http://example.com/Jason</text> +</g> +<!-- http://example.com/Song->http://example.com/Jason --> +<g id="edge5" class="edge"> +<title>http://example.com/Song->http://example.com/Jason</title> +<path fill="none" stroke="black" d="M184.28,-163.94C219.6,-157.73 260.21,-150.59 296.6,-144.19"/> +<polygon fill="black" stroke="black" points="297.01,-147.67 306.26,-142.49 295.8,-140.77 297.01,-147.67"/> +<text text-anchor="middle" x="244" y="-162" font-family="sans-serif" font-size="10.00">nmm:albumArtist</text> +</g> +<!-- http://example.com/Marty --> +<g id="node11" class="node"> +<title>http://example.com/Marty</title> +<path fill="none" stroke="black" d="M484,-90C484,-90 318,-90 318,-90 312,-90 306,-84 306,-78 306,-78 306,-66 306,-66 306,-60 312,-54 318,-54 318,-54 484,-54 484,-54 490,-54 496,-60 496,-66 496,-66 496,-78 496,-78 496,-84 490,-90 484,-90"/> +<text text-anchor="middle" x="401" y="-68.3" font-family="sans-serif" font-size="14.00">http://example.com/Marty</text> +</g> +<!-- http://example.com/Song->http://example.com/Marty --> +<g id="edge6" class="edge"> +<title>http://example.com/Song->http://example.com/Marty</title> +<path fill="none" stroke="black" d="M131.12,-161.53C151.84,-151.83 178.05,-140.1 202,-131 246.41,-114.12 258.46,-112.54 304,-99 310.06,-97.2 316.34,-95.36 322.67,-93.53"/> +<polygon fill="black" stroke="black" points="323.2,-97.02 331.85,-90.9 321.27,-90.29 323.2,-97.02"/> +<text text-anchor="middle" x="244" y="-134" font-family="sans-serif" font-size="10.00">nmm:albumArtist</text> +</g> +<!-- http://example.com/Band --> +<g id="node12" class="node"> +<title>http://example.com/Band</title> +<path fill="none" stroke="black" d="M481.5,-36C481.5,-36 320.5,-36 320.5,-36 314.5,-36 308.5,-30 308.5,-24 308.5,-24 308.5,-12 308.5,-12 308.5,-6 314.5,0 320.5,0 320.5,0 481.5,0 481.5,0 487.5,0 493.5,-6 493.5,-12 493.5,-12 493.5,-24 493.5,-24 493.5,-30 487.5,-36 481.5,-36"/> +<text text-anchor="middle" x="401" y="-14.3" font-family="sans-serif" font-size="14.00">http://example.com/Band</text> +</g> +<!-- http://example.com/Song->http://example.com/Band --> +<g id="edge7" class="edge"> +<title>http://example.com/Song->http://example.com/Band</title> +<path fill="none" stroke="black" d="M111.39,-161.76C132.09,-141.95 167.35,-110.31 202,-89 244.05,-63.13 257.47,-61.5 304,-45 308.99,-43.23 314.16,-41.5 319.39,-39.82"/> +<polygon fill="black" stroke="black" points="320.23,-43.23 328.74,-36.91 318.15,-36.54 320.23,-43.23"/> +<text text-anchor="middle" x="244" y="-92" font-family="sans-serif" font-size="10.00">nmm:performer</text> +</g> +<!-- http://example.com/Album->Go Off! --> +<g id="edge8" class="edge"> +<title>http://example.com/Album->Go Off!</title> +<path fill="none" stroke="black" d="M498.31,-180C543.41,-180 594.86,-180 630.18,-180"/> +<polygon fill="black" stroke="black" points="629.99,-183.5 639.99,-180 629.99,-176.5 629.99,-183.5"/> +<text text-anchor="middle" x="555.5" y="-183" font-family="sans-serif" font-size="10.00">nie:title</text> +</g> +<!-- http://example.com/Jason->Jason Becker --> +<g id="edge9" class="edge"> +<title>http://example.com/Jason->Jason Becker</title> +<path fill="none" stroke="black" d="M494.13,-126C533,-126 577.2,-126 611.94,-126"/> +<polygon fill="black" stroke="black" points="611.82,-129.5 621.82,-126 611.82,-122.5 611.82,-129.5"/> +<text text-anchor="middle" x="555.5" y="-129" font-family="sans-serif" font-size="10.00">nmm:artistName</text> +</g> +<!-- http://example.com/Marty->Marty Friedman --> +<g id="edge10" class="edge"> +<title>http://example.com/Marty->Marty Friedman</title> +<path fill="none" stroke="black" d="M496.4,-72C530.97,-72 569.49,-72 601.7,-72"/> +<polygon fill="black" stroke="black" points="601.3,-75.5 611.3,-72 601.3,-68.5 601.3,-75.5"/> +<text text-anchor="middle" x="555.5" y="-75" font-family="sans-serif" font-size="10.00">nmm:artistName</text> +</g> +<!-- http://example.com/Band->Cacophony --> +<g id="edge11" class="edge"> +<title>http://example.com/Band->Cacophony</title> +<path fill="none" stroke="black" d="M493.75,-18C534.9,-18 582.08,-18 617.71,-18"/> +<polygon fill="black" stroke="black" points="617.33,-21.5 627.33,-18 617.33,-14.5 617.33,-21.5"/> +<text text-anchor="middle" x="555.5" y="-21" font-family="sans-serif" font-size="10.00">nmm:artistName</text> +</g> +</g> +</svg> diff --git a/docs/reference/libtracker-sparql/images/triple-graph-3.dot b/docs/reference/libtracker-sparql/images/triple-graph-3.dot index 55ce34e70..9ad595bce 100644 --- a/docs/reference/libtracker-sparql/images/triple-graph-3.dot +++ b/docs/reference/libtracker-sparql/images/triple-graph-3.dot @@ -1,9 +1,10 @@ digraph G { rankdir=LR; - graph [bgcolor="#00000000"]; - node [fontname="Cantarell", style="filled", shape="ellipse", color="#000000", fillcolor="#d8e5e5"]; "nmm:MusicPiece"; - node [style="filled,dotted", color="#000000", fillcolor="#ffffff"]; song, songTitle, album, albumTitle; - edge [fontname="Cantarell"]; + bgcolor=transparent; + + node [shape="box", style="rounded", border=0, fontname="sans-serif"]; "nmm:MusicPiece"; + node [shape="ellipse", style="dashed", border=1, fillcolor="#000000"]; song, songTitle, album, albumTitle; + edge [fontname="sans-serif", fontsize=10]; song -> "nmm:MusicPiece" [label="rdf:type"]; song -> songTitle [label="nie:title"]; diff --git a/docs/reference/libtracker-sparql/images/triple-graph-3.png b/docs/reference/libtracker-sparql/images/triple-graph-3.png Binary files differdeleted file mode 100644 index 965694481..000000000 --- a/docs/reference/libtracker-sparql/images/triple-graph-3.png +++ /dev/null diff --git a/docs/reference/libtracker-sparql/images/triple-graph-3.svg b/docs/reference/libtracker-sparql/images/triple-graph-3.svg new file mode 100644 index 000000000..6fb0dc667 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/triple-graph-3.svg @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 7.1.0 (0) + --> +<!-- Title: G Pages: 1 --> +<svg width="504pt" height="152pt" + viewBox="0.00 0.00 504.48 152.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 148)"> +<title>G</title> +<!-- nmm:MusicPiece --> +<g id="node1" class="node"> +<title>nmm:MusicPiece</title> +<path fill="none" stroke="black" d="M300.69,-144C300.69,-144 195.69,-144 195.69,-144 189.69,-144 183.69,-138 183.69,-132 183.69,-132 183.69,-120 183.69,-120 183.69,-114 189.69,-108 195.69,-108 195.69,-108 300.69,-108 300.69,-108 306.69,-108 312.69,-114 312.69,-120 312.69,-120 312.69,-132 312.69,-132 312.69,-138 306.69,-144 300.69,-144"/> +<text text-anchor="middle" x="248.19" y="-122.3" font-family="sans-serif" font-size="14.00">nmm:MusicPiece</text> +</g> +<!-- song --> +<g id="node2" class="node"> +<title>song</title> +<ellipse fill="none" stroke="black" stroke-dasharray="5,2" cx="31.85" cy="-72" rx="31.7" ry="18"/> +<text text-anchor="middle" x="31.85" y="-68.3" font-family="sans-serif" font-size="14.00">song</text> +</g> +<!-- song->nmm:MusicPiece --> +<g id="edge1" class="edge"> +<title>song->nmm:MusicPiece</title> +<path fill="none" stroke="black" d="M60.14,-80.73C67.14,-82.87 74.67,-85.1 81.69,-87 111.12,-94.98 143.75,-102.87 172.2,-109.44"/> +<polygon fill="black" stroke="black" points="171.28,-112.82 181.81,-111.65 172.85,-106 171.28,-112.82"/> +<text text-anchor="middle" x="123.69" y="-110" font-family="sans-serif" font-size="10.00">rdf:type</text> +</g> +<!-- songTitle --> +<g id="node3" class="node"> +<title>songTitle</title> +<ellipse fill="none" stroke="black" stroke-dasharray="5,2" cx="248.19" cy="-72" rx="50.09" ry="18"/> +<text text-anchor="middle" x="248.19" y="-68.3" font-family="sans-serif" font-size="14.00">songTitle</text> +</g> +<!-- song->songTitle --> +<g id="edge2" class="edge"> +<title>song->songTitle</title> +<path fill="none" stroke="black" d="M64.02,-72C95.93,-72 146.37,-72 186.25,-72"/> +<polygon fill="black" stroke="black" points="186.21,-75.5 196.21,-72 186.21,-68.5 186.21,-75.5"/> +<text text-anchor="middle" x="123.69" y="-75" font-family="sans-serif" font-size="10.00">nie:title</text> +</g> +<!-- album --> +<g id="node4" class="node"> +<title>album</title> +<ellipse fill="none" stroke="black" stroke-dasharray="5,2" cx="248.19" cy="-18" rx="37.89" ry="18"/> +<text text-anchor="middle" x="248.19" y="-14.3" font-family="sans-serif" font-size="14.00">album</text> +</g> +<!-- song->album --> +<g id="edge3" class="edge"> +<title>song->album</title> +<path fill="none" stroke="black" d="M60.14,-63.27C67.14,-61.13 74.67,-58.9 81.69,-57 122.09,-46.05 168.51,-35.27 201.88,-27.82"/> +<polygon fill="black" stroke="black" points="202.63,-31.24 211.64,-25.66 201.11,-24.41 202.63,-31.24"/> +<text text-anchor="middle" x="123.69" y="-60" font-family="sans-serif" font-size="10.00">nmm:MusicAlbum</text> +</g> +<!-- albumTitle --> +<g id="node5" class="node"> +<title>albumTitle</title> +<ellipse fill="none" stroke="black" stroke-dasharray="5,2" cx="440.59" cy="-18" rx="55.79" ry="18"/> +<text text-anchor="middle" x="440.59" y="-14.3" font-family="sans-serif" font-size="14.00">albumTitle</text> +</g> +<!-- album->albumTitle --> +<g id="edge4" class="edge"> +<title>album->albumTitle</title> +<path fill="none" stroke="black" d="M286.36,-18C311.01,-18 344.05,-18 373.14,-18"/> +<polygon fill="black" stroke="black" points="372.97,-21.5 382.97,-18 372.97,-14.5 372.97,-21.5"/> +<text text-anchor="middle" x="348.69" y="-21" font-family="sans-serif" font-size="10.00">nie:title</text> +</g> +</g> +</svg> diff --git a/docs/reference/libtracker-sparql/implementation.md b/docs/reference/libtracker-sparql/implementation.md deleted file mode 100644 index 998f66dc8..000000000 --- a/docs/reference/libtracker-sparql/implementation.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Implementation details -short-description: Tracker implementation specifics -... - -# Implementation details - -This section highlights the chosen interpretations of the -SPARQL specification, and specifies how to get the best of -Tracker's implementation of the SPARQL standard. diff --git a/docs/reference/libtracker-sparql/index.md b/docs/reference/libtracker-sparql/index.md deleted file mode 100644 index 5da81f0cc..000000000 --- a/docs/reference/libtracker-sparql/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tracker library documentation - -Tracker is a low-footprint, yet complete implementation of the SPARQL -standard. It allows you to create triplestores (either in disk or in -memory), connect to remote SPARQL endpoints (via DBus or HTTP), or -be an endpoint yourself. - -- *License:* LGPL-2.1-or-later -- *Website:* [https://gnome.pages.gitlab.gnome.org/tracker/](https://gnome.pages.gitlab.gnome.org/tracker/) diff --git a/docs/reference/libtracker-sparql/install-devhelp.sh b/docs/reference/libtracker-sparql/install-devhelp.sh index 74aafaa54..837a9e311 100755 --- a/docs/reference/libtracker-sparql/install-devhelp.sh +++ b/docs/reference/libtracker-sparql/install-devhelp.sh @@ -1,12 +1,9 @@ #!/bin/sh # Generate fixed .devhelp2 file -${MESON_SOURCE_ROOT}/docs/reference/libtracker-sparql/generate-devhelp.sh $1 +. ${MESON_SOURCE_ROOT}/docs/reference/libtracker-sparql/generate-devhelp.sh $1 $2 # Install all files -docs_name=$1 -docs_path="${docs_name}-doc/devhelp/books/${docs_name}" - -cd ${MESON_BUILD_ROOT}/docs/reference/libtracker-sparql/ -mkdir -p ${MESON_INSTALL_DESTDIR_PREFIX}/share/devhelp/books -cp -a $docs_path ${MESON_INSTALL_DESTDIR_PREFIX}/share/devhelp/books/ +docs_path=$2 +mkdir -p ${MESON_INSTALL_DESTDIR_PREFIX}/share/doc +cp -a $docs_path/* ${MESON_INSTALL_DESTDIR_PREFIX}/share/doc/ diff --git a/docs/reference/libtracker-sparql/limits.md b/docs/reference/libtracker-sparql/limits.md index 9d514b834..0aac7a6f8 100644 --- a/docs/reference/libtracker-sparql/limits.md +++ b/docs/reference/libtracker-sparql/limits.md @@ -1,12 +1,8 @@ ---- -title: Limits -short-description: Implementation limits -... +Title: Implementation limits +Slug: implementation-limits -# Limits - -Tracker is implemented on top of SQLite, and all of its benefits and -[limits](https://www.sqlite.org/limits.html) apply. This +Tracker is implemented on top of [SQLite](https://sqlite.org), and all of its +benefits and [limits](https://sqlite.org/limits.html) apply. This document will break down how those limits apply to Tracker. Depending on your distributor, the limits might be changed via SQLite build-time options. @@ -65,7 +61,7 @@ SQLite has a limit on the number of databases that can be attached, defined by `SQLITE_MAX_LIMIT_ATTACHED` (defaults to 10, maximum 128). Tracker uses attached databases to implement its support for multiple -graphs, so the maximum amount of graphs for a given [](TrackerSparqlConnection) +graphs, so the maximum amount of graphs for a given [class@Tracker.SparqlConnection] is equally restricted. ## Limits on glob search @@ -78,7 +74,7 @@ SPARQL syntax. SQLite defines a maximum of 999 parameters to be passed as arguments to a statement, controlled by `SQLITE_MAX_VARIABLE_NUMBER`. -[](TrackerSparqlStatement) has the same limit. +[class@Tracker.SparqlStatement] has the same limit. ## Maximum number of pages in a database @@ -90,4 +86,4 @@ applies per graph. Integers are 64 bit wide. Floating point numbers have IEEE764 double precision. Dates/times have microsecond precision, and may -range between 0001-01-01 00:00:00 and 9999-12-31 23:59:59. +range between `0001-01-01 00:00:00` and `9999-12-31 23:59:59`. diff --git a/docs/reference/libtracker-sparql/logo.svg b/docs/reference/libtracker-sparql/logo.svg new file mode 100644 index 000000000..21ad79cd6 --- /dev/null +++ b/docs/reference/libtracker-sparql/logo.svg @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg width="256" height="256" version="1.1" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink"> + <defs> + <linearGradient id="Gradient" x1="0" x2="0" y1="0" y2="1"> + <stop offset="0%" style="stop-color:#E01B24;stop-opacity:1" /> + <stop offset="100%" style="stop-color:#C061CB;stop-opacity:1" /> + </linearGradient> + <filter id="alpha-to-white"> + <feColorMatrix in="SourceGraphic" type="matrix" + values="0 0 0 1 0 + 0 0 0 1 0 + 0 0 0 1 0 + 0 0 0 1 0"/> + </filter> + <g id="child-svg"> +<svg height="16px" viewBox="0 0 16 16" width="16px" xmlns="http://www.w3.org/2000/svg"> + <g fill="#241f31"> + <path d="m 11.5 10.644531 c -0.863281 0.15625 -1.175781 1.234375 -0.53125 1.828125 l 3.195312 3.195313 c 1.019532 0.996093 2.515626 -0.53125 1.496094 -1.53125 l -3.195312 -3.195313 c -0.25 -0.253906 -0.613282 -0.367187 -0.964844 -0.296875 z m 0 0"/> + <path d="m 6.917969 0 c -3.808594 0 -6.917969 3.109375 -6.917969 6.917969 c 0 3.808593 3.109375 6.917969 6.917969 6.917969 c 3.808593 0 6.921875 -3.109376 6.921875 -6.917969 c 0 -3.808594 -3.113282 -6.917969 -6.921875 -6.917969 z m 0 2.128906 c 2.660156 0 4.792969 2.132813 4.792969 4.789063 c 0 2.660156 -2.132813 4.789062 -4.792969 4.789062 c -2.65625 0 -4.789063 -2.128906 -4.789063 -4.789062 c 0 -2.65625 2.132813 -4.789063 4.789063 -4.789063 z m 0 0"/> + </g> +</svg> +</g> + </defs> + <rect + width="256" + height="256" + fill="url(#Gradient)" + ry="128" + x="0" + y="0" /> + <use xlink:href="#child-svg" filter="url(#alpha-to-white)" + transform="matrix(8,0,0,8,64,64)" /> +</svg> diff --git a/docs/reference/libtracker-sparql/merge-json.py b/docs/reference/libtracker-sparql/merge-json.py new file mode 100644 index 000000000..7793f9155 --- /dev/null +++ b/docs/reference/libtracker-sparql/merge-json.py @@ -0,0 +1,13 @@ +#!/bin/env python3 +import json, sys + +index = json.load(open(sys.argv[1])) +for x in range (2, len(sys.argv)): + extra = json.load(open(sys.argv[x])) + index['symbols'] += extra['symbols'] + +rewritten = json.dumps(index) + +with open(sys.argv[1], 'w') as f: + f.write(rewritten) + f.close() diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build index b6dad9c9a..e49b31d8a 100644 --- a/docs/reference/libtracker-sparql/meson.build +++ b/docs/reference/libtracker-sparql/meson.build @@ -1,16 +1,25 @@ fs = import('fs') -if fs.exists('devhelp') +if fs.exists('doc') # Special case for tarballs, install the pre-generated docs - install_subdir('devhelp/books', - install_dir: join_paths(datadir, 'devhelp')) + install_subdir('doc', + install_dir: datadir) subdir_done() endif -hotdoc = import('hotdoc') +gidocgen_dep = dependency('gi-docgen', fallback: ['gi-docgen', 'dummy_dep']) +gidocgen = find_program('gi-docgen') +graphviz_dot = find_program('dot') + +ontology_introductions = [ + 'nie-introduction.md', + 'nmm-introduction.md', + 'nco-introduction.md', + 'mfo-introduction.md', +] base_ontology_docs = custom_target('ontology-docgen', - output: ['dc-ontology.md'], + output: ['dc-ontology.md.in'], command: [tracker_docgen, '--md', '--ontology-dir', meson.current_build_dir(), # Directory without ontology files @@ -18,67 +27,129 @@ base_ontology_docs = custom_target('ontology-docgen', '--introduction-dir', meson.current_source_dir(), '--ontology-description-dir', join_paths(source_root, 'src/ontologies/')], depends: tracker_docgen, - depend_files: [base_ontology], - build_by_default: true, + depend_files: [base_ontology, ontology_introductions], ) nepomuk_ontology_docs = custom_target('nepomuk-docgen', - output: ['nie-ontology.md'], + output: ['nie-ontology.md.in'], command: [tracker_docgen, '--md', '--ontology-dir', join_paths(source_root, 'src/ontologies/nepomuk'), '--output-dir', meson.current_build_dir(), '--introduction-dir', meson.current_source_dir()], depends: tracker_docgen, - depend_files: [base_ontology], - build_by_default: true, + depend_files: [nepomuk, ontology_introductions], ) +generate_images = custom_target( + 'doc-images', + output: 'rdfs:Resource-hierarchy.svg', + command: [ + 'generate-svgs.sh', + graphviz_dot, + meson.current_build_dir(), + ], + depends: [base_ontology_docs, nepomuk_ontology_docs]) + +generated_ontology_files = [ + 'xsd-ontology.md.in', + 'rdf-ontology.md.in', + 'rdfs-ontology.md.in', + 'nrl-ontology.md.in', + 'dc-ontology.md.in', + + 'nie-ontology.md.in', + 'nao-ontology.md.in', + 'nco-ontology.md.in', + 'nfo-ontology.md.in', + 'nmm-ontology.md.in', + 'mfo-ontology.md.in', + 'tracker-ontology.md.in', + 'slo-ontology.md.in', + 'osinfo-ontology.md.in', +] + +generated_targets = [] +generated_ontology_content = [] + +foreach doc : generated_ontology_files + output_file = doc.replace('.in', '') + generated_ontology_content += output_file + generated_targets += custom_target( + output_file, + output: output_file, + command: [ + 'embed-files.py', + meson.current_build_dir() / doc, + meson.current_build_dir() / output_file, + ], + depends: [base_ontology_docs, nepomuk_ontology_docs, generate_images]) +endforeach + +generated_content_files = [ + 'examples.md.in', + 'tutorial.md.in', +] + +generated_content = [] + +foreach doc : generated_content_files + output_file = doc.replace('.in', '') + generated_content += output_file + generated_targets += custom_target( + output_file, + input: doc, + output: output_file, + command: [ + 'embed-files.py', + '@INPUT@', + '@OUTPUT@', + ]) +endforeach + +overview = ['overview.md'] content = [ - 'overview.md', - 'examples.md', 'ontologies.md', + 'sparql-functions.md', + 'sparql-and-tracker.md', 'limits.md', 'performance.md', - 'sparql-and-tracker.md', - 'sparql-functions.md', - 'migrating-2to3.md', - 'tutorial.md', 'security.md', + 'migrating-2to3.md', ] -required_hotdoc_extensions = [ - 'gi-extension', - 'devhelp-extension', - 'syntax-highlighting-extension', -] - -foreach ext: required_hotdoc_extensions - if not hotdoc.has_extensions(ext) - error('Documentation enabled but HotDoc extension "@0@" is missing'.format(ext)) - endif +# The TOML gi-docgen configuration wants a list of quoted file names. +content_quoted = [] +foreach c : overview + generated_content + content + generated_ontology_content + content_quoted += '"@0@"'.format(c) endforeach -docs_name = 'Tracker' -hotdoc.generate_doc(docs_name, - project_version: tracker_version, - languages: [ 'c', 'python', 'javascript' ], - gi_c_sources: [libtracker_sparql_sources, libtracker_sparql_public_headers], - gi_sources: [tracker_sparql_gir[0].full_path()], - sitemap: 'sitemap.txt', - index: 'index.md', - gi_index: 'gi-index.md', - gi_smart_index: true, - gi_c_source_roots: [sparqlinc], - dependencies: [tracker_sparql_dep, base_ontology_docs, nepomuk_ontology_docs], - extra_assets: [join_paths(meson.current_source_dir(), 'images')], - html_theme: 'https://github.com/hotdoc/hotdoc_lumen_theme/releases/download/0.13.2/hotdoc_lumen_theme-0.13.2.tar.xz?sha256=5721189b7e985f27381ee20137f4a9003049a70a75ab1221a69fd04d27e752bc', - html_extra_theme: join_paths(meson.current_source_dir(), 'theme-extra'), - syntax_highlighting_activate: true, - devhelp_activate: true, - devhelp_online: 'https://gnome.pages.gitlab.gnome.org/tracker/docs/developer/', - install: true, -) +gidocgen_conf = configuration_data() +gidocgen_conf.set('version', meson.project_version()) +gidocgen_conf.set('content', ','.join(content_quoted)) + +gidocgen_toml = configure_file( + input: 'tracker-sparql.toml.in', + output: 'tracker-sparql.toml', + configuration: gidocgen_conf) + +reference = custom_target( + 'docgen', + input: [ gidocgen_toml, tracker_sparql_gir[0] ], + output: 'doc', + command: [ + gidocgen, + 'generate', + '--quiet', + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + '--content-dir=@0@'.format(meson.current_build_dir()), + '@INPUT1@', + ], + depends: [tracker_sparql_gir[0], generated_targets], + depend_files: [overview, content]) -meson.add_install_script('install-devhelp.sh', docs_name) -meson.add_dist_script('dist-docs.sh', docs_name) +docs_name = 'Tracker-3.0' +meson.add_install_script('install-devhelp.sh', docs_name, reference) +meson.add_dist_script('dist-docs.sh', docs_name, reference.full_path()) diff --git a/docs/reference/libtracker-sparql/mfo-introduction.md b/docs/reference/libtracker-sparql/mfo-introduction.md index 73b0b09b2..65ee78b83 100644 --- a/docs/reference/libtracker-sparql/mfo-introduction.md +++ b/docs/reference/libtracker-sparql/mfo-introduction.md @@ -6,12 +6,12 @@ This ontology is an abstract representation of entries coming from feeds. These The basic assumption in the ontology is that all these feeds are unidirectional conversations with (from) the author of the content and every post on those channels is a message. -The source of the posts, the feed itself, is an instance of [mfo:FeedChannel](mfo-ontology.md#mfo:FeedChannel). Each post in that feed will be an instance of [mfo:FeedMessage](mfo-ontology.md#mfo:FeedMessage). The relation between the messages and the channel comes from their superclasses, [nmo:communicationChannel](nmo-ontology.md#nmo:communicationChannel) (taking into account that [mfo:FeedChannel](mfo-ontology.md#mfo:FeedChannel) is a subclass of [nmo:CommunicationChannel](nmo-ontology.md#nmo:CommunicationChannel) and [mfo:FeedMessage](mfo-ontology.md#mfo:FeedMessage) a subclass of [nmo:Message](nmo-ontology.md#nmo:Message). +The source of the posts, the feed itself, is an instance of [mfo:FeedChannel](mfo-ontology.html#mfo:FeedChannel). Each post in that feed will be an instance of [mfo:FeedMessage](mfo-ontology.html#mfo:FeedMessage). The relation between the messages and the channel comes from their superclasses, [nmo:communicationChannel](nmo-ontology.html#nmo:communicationChannel) (taking into account that [mfo:FeedChannel](mfo-ontology.html#mfo:FeedChannel) is a subclass of [nmo:CommunicationChannel](nmo-ontology.html#nmo:CommunicationChannel) and [mfo:FeedMessage](mfo-ontology.html#mfo:FeedMessage) a subclass of [nmo:Message](nmo-ontology.html#nmo:Message). -A post can be plain text but can contain also more things like links, videos or Mp3. We represent those internal pieces in instances of [mfo:Enclosure](mfo-ontology.md#mfo:Enclosure). This class has properties to link with the remote and local representation of the resource (in case the content has been downloaded). +A post can be plain text but can contain also more things like links, videos or Mp3. We represent those internal pieces in instances of [mfo:Enclosure](mfo-ontology.html#mfo:Enclosure). This class has properties to link with the remote and local representation of the resource (in case the content has been downloaded). -Finally, the three important classes (mfo:FeedChannel, mfo:FeedMessage, mfo:Enclosure) are subclasses of [mfo:FeedElement](mfo-ontology.md#mfo:FeedElement), just an abstract class to share the link with mfo:FeedSettings. [mfo:FeedSettings](mfo-ontology.md#mfo:FeedSettings) contains some common configuration options. Not all of them applies to all, but it is a quite cleaner solution. For instance the [mfo:maxSize](mfo-ontology.md#mfo:maxSize) property only makes sense per-enclosure, while the [mfo:updateInterval](mfo-ontology.md#mfo:updateInterval) is useful for the channel. +Finally, the three important classes (mfo:FeedChannel, mfo:FeedMessage, mfo:Enclosure) are subclasses of [mfo:FeedElement](mfo-ontology.html#mfo:FeedElement), just an abstract class to share the link with mfo:FeedSettings. [mfo:FeedSettings](mfo-ontology.html#mfo:FeedSettings) contains some common configuration options. Not all of them applies to all, but it is a quite cleaner solution. For instance the [mfo:maxSize](mfo-ontology.html#mfo:maxSize) property only makes sense per-enclosure, while the [mfo:updateInterval](mfo-ontology.html#mfo:updateInterval) is useful for the channel. ## Special remarks -In some feeds there can be multiple enclosures together in a group, representing the same resource in different formats, qualities, resolutions, etc. Until further notify, the group will be represented using [nie:identifier](nie-ontology.md#nie:identifier) property. To mark the default enclosure of the group, there is a [mfo:groupDefault](mfo-ontology.md#mfo:groupDefault) property. +In some feeds there can be multiple enclosures together in a group, representing the same resource in different formats, qualities, resolutions, etc. Until further notify, the group will be represented using [nie:identifier](nie-ontology.html#nie:identifier) property. To mark the default enclosure of the group, there is a [mfo:groupDefault](mfo-ontology.html#mfo:groupDefault) property. diff --git a/docs/reference/libtracker-sparql/migrating-2to3.md b/docs/reference/libtracker-sparql/migrating-2to3.md index 2330e88e6..172b65b70 100644 --- a/docs/reference/libtracker-sparql/migrating-2to3.md +++ b/docs/reference/libtracker-sparql/migrating-2to3.md @@ -1,9 +1,5 @@ ---- -title: Migrating from 2.x to 3.0 -short-description: Migrating from libtracker-sparql 2.x to 3.0 -... - -# Migrating from libtracker-sparql 2.x to 3.0 +Title: Migrating from 2.x to 3.0 +Slug: migrating-2-to-3 Tracker 3.0 is a new major version, containing some large syntax and conceptual changes. @@ -21,8 +17,8 @@ in one graph at a time. In other words, this yields the wrong result: ```SPARQL -INSERT { GRAPH <A> { <foo> nie:title 'Hello' } } -INSERT { GRAPH <B> { <foo> nie:title 'Hola' } } +INSERT { GRAPH <http://example.com/A> { <foo> nie:title 'Hello' } } +INSERT { GRAPH <http://example.com/B> { <foo> nie:title 'Hola' } } # We expect 2 rows, 2.x returns 1. SELECT ?g ?t { GRAPH ?g { <foo> nie:title ?t } } @@ -37,10 +33,10 @@ skipped if a GRAPH is requested or defined, e.g.: ```SPARQL # Inserts element into the unnamed graph -INSERT { <foo> a nfo:FileDataObject } +INSERT { <http://example.com/foo> a nfo:FileDataObject } # Inserts element into named graph A -INSERT { GRAPH <A> { <bar> a nfo:FileDataObject } } +INSERT { GRAPH <A> { <http://example.com/bar> a nfo:FileDataObject } } # Queries from all named graphs, A in this case SELECT ?g ?s { GRAPH ?g { ?s a nfo:FileDataObject } } @@ -110,18 +106,18 @@ those elements in place. Other ontologies might have similar concepts. Notifiers are now created through tracker_sparql_connection_create_notifier(). -## Different signature of [](TrackerNotifier::events) signal +## Different signature of [signal@Tracker.Notifier::events] signal A TrackerNotifier may hint changes across multiple endpoints (local or remote), in consequence the signal additionally contains 2 string arguments, notifying about the SPARQL endpoint the changes came from, and the SPARQL graph the changes apply to. -## Return value change in `tracker_sparql_connection_update_array()` +## Return value change in [method@Tracker.SparqlConnection.update_array_async] This function changed to handle all changes within a single transaction. Returning an array of errors for each individual update is no longer necessary, so it now -simply returns a boolean return value. +simply returns a boolean return value and a single error for the whole transaction. ## No `tracker_sparql_connection_get()/get_async()` @@ -129,13 +125,13 @@ There is no longer a singleton SPARQL connection. If you are only interested in tracker-miner-fs data, you can create a dedicated DBus connection to it through: ```c -conn = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", ...); +conn = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", …); ``` If you are interested in storing your own data, you can do it through: ```c -conn = tracker_sparql_connection_new (...); +conn = tracker_sparql_connection_new (…); ``` Note that you still may access other endpoints in SELECT queries, eg. for diff --git a/docs/reference/libtracker-sparql/nepomuk.md b/docs/reference/libtracker-sparql/nepomuk.md deleted file mode 100644 index 4745414b6..000000000 --- a/docs/reference/libtracker-sparql/nepomuk.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Nepomuk -short-description: The Nepomuk ontology -... - -# Nepomuk - -Nepomuk is the swiss army knife of the semantic desktop. It defines -data structures for almost any kind of data you might want to store -in a workstation machine. diff --git a/docs/reference/libtracker-sparql/nie-introduction.md b/docs/reference/libtracker-sparql/nie-introduction.md index cc386c45b..f79535281 100644 --- a/docs/reference/libtracker-sparql/nie-introduction.md +++ b/docs/reference/libtracker-sparql/nie-introduction.md @@ -3,26 +3,26 @@ ## Introduction The core of the NEPOMUK Information Element Ontology and the entire -Ontology Framework revolves around the concepts of [nie:DataObject](nie-ontology.md#nie:DataObject) and -[nie:InformationElement](nie-ontology.md#nie:InformationElement). They express the representation +Ontology Framework revolves around the concepts of [nie:DataObject](nie-ontology.html#nie:DataObject) and +[nie:InformationElement](nie-ontology.html#nie:InformationElement). They express the representation and content of a piece of data. Their specialized subclasses (defined in the other ontologies) can be used to classify a wide array of desktop resources and express them in RDF. -[nie:DataObject](nie-ontology.md#nie:DataObject) class represents a bunch of +[nie:DataObject](nie-ontology.html#nie:DataObject) class represents a bunch of bytes somewhere (local or remote), the physical entity that contain data. The *meaning* (interpretation) of that entity, the information for the user contained in those bytes (e.g. a music file, a picture) is represented on the -[nie:InformationElement](nie-ontology.md#nie:InformationElement) side of the +[nie:InformationElement](nie-ontology.html#nie:InformationElement) side of the ontology. Both sides are linked using the -property [nie:interpretedAs](nie-ontology.md#nie:interpretedAs) (and its reverse -[nie:isStoredAs](nie-ontology.md#nie:isStoredAs)), indicating the correspondence +property [nie:interpretedAs](nie-ontology.html#nie:interpretedAs) (and its reverse +[nie:isStoredAs](nie-ontology.html#nie:isStoredAs)), indicating the correspondence between the physical element and its interpretation. There is also a property to -link [nie:InformationElement](nie-ontology.md#nie:InformationElement)s, +link [nie:InformationElement](nie-ontology.html#nie:InformationElement)s, representing the logical containment between them (like a picture and its album). @@ -33,22 +33,22 @@ everything in the Nepomuk set of ontologies, the properties defined here will be inherited for a lot of classes. It is worth to comment few of them with special relevance: - - [nie:title](nie-ontology.md#nie:title): Title or name or short text describing the item - - [nie:description](nie-ontology.md#nie:description): More verbose comment about the element - - [nie:language](nie-ontology.md#nie:language): To specify the language of the item. - - [nie:plainTextContent](nie-ontology.md#nie:plainTextContent): Just the raw content of the file, if it makes sense as text. - - [nie:generator](nie-ontology.md#nie:generator): Software/Agent that set/produced the information. - - [nie:usageCounter](nie-ontology.md#nie:usageCounter): Count number of accesses to the information. It can be an indicator of relevance for advanced searches + - [nie:title](nie-ontology.html#nie:title): Title or name or short text describing the item + - [nie:description](nie-ontology.html#nie:description): More verbose comment about the element + - [nie:language](nie-ontology.html#nie:language): To specify the language of the item. + - [nie:plainTextContent](nie-ontology.html#nie:plainTextContent): Just the raw content of the file, if it makes sense as text. + - [nie:generator](nie-ontology.html#nie:generator): Software/Agent that set/produced the information. + - [nie:usageCounter](nie-ontology.html#nie:usageCounter): Count number of accesses to the information. It can be an indicator of relevance for advanced searches ## Date and timestamp representations There are few important dates for the life-cycle of a resource. These dates are properties of the nie:InformationElement class, and inherited for its subclasses: - - [nie:informationElementDate](nie-ontology.md#nie:informationElementDate): This is an ''abstract'' property that act as superproperty of the other dates. Don't use it directly. - - [nie:contentLastModified](nie-ontology.md#nie:contentLastModified): Modification time of a resource. Usually the mtime of a local file, or information from the server for online resources. - - [nie:contentCreated](nie-ontology.md#nie:contentCreated): Creation time of the content. If the contents is created by an application, the same application should set the value of this property. Note that this property can be undefined for resources in the filesystem because the creation time is not available in the most common filesystem formats. - - [nie:contentAccessed](nie-ontology.md#nie:contentAccessed): For resources coming from the filesystem, this is the usual access time to the file. For other kind of resources (online or virtual), the application accessing it should update its value. - - [nie:lastRefreshed](nie-ontology.md#nie:lastRefreshed): The time that the content was last refreshed. Usually for remote resources. + - [nie:informationElementDate](nie-ontology.html#nie:informationElementDate): This is an ''abstract'' property that act as superproperty of the other dates. Don't use it directly. + - [nie:contentLastModified](nie-ontology.html#nie:contentLastModified): Modification time of a resource. Usually the mtime of a local file, or information from the server for online resources. + - [nie:contentCreated](nie-ontology.html#nie:contentCreated): Creation time of the content. If the contents is created by an application, the same application should set the value of this property. Note that this property can be undefined for resources in the filesystem because the creation time is not available in the most common filesystem formats. + - [nie:contentAccessed](nie-ontology.html#nie:contentAccessed): For resources coming from the filesystem, this is the usual access time to the file. For other kind of resources (online or virtual), the application accessing it should update its value. + - [nie:lastRefreshed](nie-ontology.html#nie:lastRefreshed): The time that the content was last refreshed. Usually for remote resources. ## URIs and full representation of a file @@ -58,7 +58,7 @@ One of the most common resources in a desktop is a file. Given the split between 2. Even when Data Objects and Information Elements are different entities. 3. The URI of the DataObject is the real location of the item (e.g. ''file://path/to/file.mp3'') 3. The URI of the InformationElement(s) will be autogenerated IDs. - 4. Every DataObject must have the property [nie:url](nie-ontology.md#nie:url), that points to the location of the resource, and should be used by any program that wants to access it. + 4. Every DataObject must have the property [nie:url](nie-ontology.html#nie:url), that points to the location of the resource, and should be used by any program that wants to access it. 5. The InformationElement and DataObject are related via the nie:isStoredAs / nie:interpretedAs properties. Here comes an example, for the image file /home/user/a.jpeg: diff --git a/docs/reference/libtracker-sparql/nmm-introduction.md b/docs/reference/libtracker-sparql/nmm-introduction.md index 8b89fc709..82df241fd 100644 --- a/docs/reference/libtracker-sparql/nmm-introduction.md +++ b/docs/reference/libtracker-sparql/nmm-introduction.md @@ -10,14 +10,14 @@ Our approach in NMM is to keep the minimum properties that make sense for the us ## Images domain -The core of images in NMM ontology is the class [nmm:Photo](nmm-ontology.md#nmm:Photo). It is (through a long hierarchy) a [nie:InformationElement](nie-ontology.md#nie:InformationElement), an interpretation of some bytes. It has properties to store the basic information (camera, metering mode, white balance, flash), and inherits from [nfo:Image](nfo-ontology.md#nfo:Image) orientation ([nfo:orientation](nfo-ontology.md#nfo:orientation)) and resolution ([nfo:verticalResolution](nfo-ontology.md#nfo:verticalResolution) and [nfo:horizontalResolution](nfo-ontology.md#nfo:horizontalResolution)). +The core of images in NMM ontology is the class [nmm:Photo](nmm-ontology.html#nmm:Photo). It is (through a long hierarchy) a [nie:InformationElement](nie-ontology.html#nie:InformationElement), an interpretation of some bytes. It has properties to store the basic information (camera, metering mode, white balance, flash), and inherits from [nfo:Image](nfo-ontology.html#nfo:Image) orientation ([nfo:orientation](nfo-ontology.html#nfo:orientation)) and resolution ([nfo:verticalResolution](nfo-ontology.html#nfo:verticalResolution) and [nfo:horizontalResolution](nfo-ontology.html#nfo:horizontalResolution)). -Note that for tags, nie:keywords (from nie:InformationElement) can be used, or the [NAO](nao-ontology.md) ontology. +Note that for tags, nie:keywords (from nie:InformationElement) can be used, or the [NAO](nao-ontology.html) ontology. ## Radio domain -NMM includes classes and properties to represent analog and digital radio stations. There is a class [nmm:RadioStation](nmm-ontology.md#nmm:RadioStation) on the [nie:InformationElement](nie-ontology.md#nie:InformationElement) side of the ontology, representing what the user sees about that station (genre via PTY codes, icon, plus title inherited from nie:InformationElement) +NMM includes classes and properties to represent analog and digital radio stations. There is a class [nmm:RadioStation](nmm-ontology.html#nmm:RadioStation) on the [nie:InformationElement](nie-ontology.html#nie:InformationElement) side of the ontology, representing what the user sees about that station (genre via PTY codes, icon, plus title inherited from nie:InformationElement) -A [nmm:RadioStation](nmm-ontology.md#nmm:RadioStation) can have one or more [nmm:carrier](nmm-ontology.md#nmm:carrier) properties representing the different frequencies (or links when it is digitial) it can be tuned. This property links the station with [nfo:MediaStream](nfo-ontology.md#nfo:MediaStream), but usually it will point to one of the subclasses: [nmm:DigitalRadio](nmm-ontology.md#nmm:DigitalRadio) (if digital) or [nmm:AnalogRadio](nmm-ontology.md#nmm:AnalogRadio) (if analog). An analog station has properties as modulation and frequency, while the digial station has streaming bitrate, encoding or protocol. +A [nmm:RadioStation](nmm-ontology.html#nmm:RadioStation) can have one or more [nmm:carrier](nmm-ontology.html#nmm:carrier) properties representing the different frequencies (or links when it is digitial) it can be tuned. This property links the station with [nfo:MediaStream](nfo-ontology.html#nfo:MediaStream), but usually it will point to one of the subclasses: [nmm:DigitalRadio](nmm-ontology.html#nmm:DigitalRadio) (if digital) or [nmm:AnalogRadio](nmm-ontology.html#nmm:AnalogRadio) (if analog). An analog station has properties as modulation and frequency, while the digial station has streaming bitrate, encoding or protocol. -Note that nfo:MediaStream refers to a flux of bytes/data, and it is on the [nie:DataObject](nie-ontology.md#nie:DataObject)<link linkend="nie-DataObject">nie:DataObject</link> side of the ontology. +Note that nfo:MediaStream refers to a flux of bytes/data, and it is on the [nie:DataObject](nie-ontology.html#nie:DataObject) side of the ontology. diff --git a/docs/reference/libtracker-sparql/ontologies.md b/docs/reference/libtracker-sparql/ontologies.md index 884e7c481..bb931cc36 100644 --- a/docs/reference/libtracker-sparql/ontologies.md +++ b/docs/reference/libtracker-sparql/ontologies.md @@ -1,15 +1,417 @@ ---- -title: Ontologies -short-description: Structure of the stored data -... +Title: Ontologies -# Ontologies - -Ontologies define the structure of the data that the triplestore +Ontologies define the structure of the data that the RDF triple store can hold. It defines the possible resource classes, the properties these classes may have, and the relation between the different classes as expressed by these properties. -Tracker defines stock ontologies that are ready for use, but -also allows developers to define ontologies that are tailored +# Base ontology + +The base ontology is the seed for defining application-specific +ontologies. It defines the building blocks to build ontologies +upon, like the definition of classes, properties, and literal +types themselves. The base ontology is based on +[RDFS Schema](https://www.w3.org/TR/rdf-schema/). + +It is made up of several components: + +- [XML schema (XSD)](xsd-ontology.html) defines the basic literal types. +- [Resource description framework](rdf-ontology.html) defines properties, + lists and language-tagged strings. +- [RDF Schema](rdfs-ontology.html) defines classes and inheritance. +- [Nepomuk Resource Language (NRL)](nrl-ontology.html) defines resource + cardinality and database-level indexes. +- [Dublin core metadata (DC)](dc-ontology.html) defines a common set of + document-oriented superproperties for RDF resources. + +# Nepomuk + +Nepomuk is the swiss army knife of the semantic desktop, similar +in scope to [Schema.org](https://schema.org). It defines +data structures for almost any kind of data you might want to store +in a personal computer. + +It is split into several domains: + +- [Nepomuk Information Element (NIE)](nie-ontology.html) is the + core of Nepomuk. It settles the basic principles like the split + between "container" and "content", and defines the base + [nie:DataObject](nie-ontology.html#nie:DataObject) and + [nie:InformationElement](nie-ontology.html#nie:InformationElement) objects + that represent this split. +- [Nepomuk File Ontology (NFO)](nfo-ontology.html) describes the basic + filesystem-oriented objects. +- [Nepomuk Multimedia (NMM)](nmm-ontology.html) describes multi-media data. +- [Nepomuk Contacts Ontology (NCO)](nco-ontology.html) describes contacts and + addresses. +- [Libosinfo ontology](osinfo-ontology.html) describes OS images. +- [Maemo Feeds Ontology (MFO)](mfo-ontology.html) describes feeds. +- [Simplified Location Ontology (SLO)](slo-ontology.html) extends metadata + with geolocation tagging. +- [Nepomuk Annotation Ontology (NAO)](nao-ontology.html) extends metadata + with annotations. +- Other [Tracker extensions](tracker-ontology.html) to further annotate + data and link to external services. + +# Creating custom ontologies + +Tracker does also allow developers to define ontologies that are tailored for their use. + +Ontologies are made themselves of RDF data in the [Turtle](https://www.w3.org/TR/turtle/) +format with the `.ontology` extension. Custom-made ontologies will build upon the +[base ontology](#base-ontology) provided for this purpose. + +Ontologies may be split in multiple documents in a same directory. The individual +ontology files do not need be self-consistent (e.g. they may use definitions from +other files), but all the ontology files as a whole must be self-consistent. +Tracker will not open or create a RDF triple store if the ontology is not +consistent, and will roll back any change if necessary. + +Tracker loads the ontology files in alphanumeric order, it is advisable +that those have a numbered prefix in order to load those at a consistent +order despite future additions. + +## Defining a namespace + +A namespace is the topmost layer of an individual ontology, it will +contain all classes and properties defined by it. In order to define +a namespace you can do: + +```turtle +# These prefixes will be used in the definition of the ontology, +# thus must be explicitly defined +@prefix nrl: <http://tracker.api.gnome.org/ontology/v3/nrl#> . +@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + +# This is our example namespace +@prefix ex: <http://example.org/#> + +ex: a nrl:Namespace, nrl:Ontology + nrl:prefix "ex" + rdfs:comment "example ontology" + nrl:lastModified "2017-01-01T15:00:00Z" +``` + +## Defining classes + +Classes are the base of an ontology, all stored resources must define +themselves as "being" at least one of these classes. They all derive +from the base rdfs:Resource type. To eg. define classes representing +animals and plants, you can do: + +```turtle +ex:Eukaryote a rdfs:Class; + rdfs:subClassOf rdfs:Resource; + rdfs:comment "An eukaryote". +``` + +By convention all classes use CamelCase names, although class names +are not restricted. The allowed charset is UTF-8. + +Declaring subclasses is possible: + +```turtle +ex:Animal a rdfs:Class; + rdfs:subClassOf ex:Eukaryote; + rdfs:comment "An animal". + +ex:Plant a rdfs:Class; + rdfs:subClassOf ex:Eukaryote; + rdfs:comment "A plant". + +ex:Mammal a rdfs:Class; + rdfs:subClassOf ex:Animal; + rdfs:comment "A mammal". +``` + +With such classes defined, resources may be inserted to the endpoint, +eg. with the SPARQL: + +```SPARQL +INSERT DATA { <merry> a ex:Mammal } +INSERT DATA { <treebeard> a ex:Animal, ex:Plant } +``` + +Note that multiple inheritance is possible, resources will just inherit +all properties from all classes and superclasses. + +## Defining properties + +Properties relate to a class, so all resources pertaining to that class +can define values for these. + +```turtle +ex:cromosomes a rdf:Property; + rdfs:domain ex:Eukaryote; + rdfs:range xsd:integer. + +ex:unicellular a rdf:Property; + rdfs:domain ex:Eukaryote; + rdfs:range xsd:bool; + +ex:dateOfBirth a rdf:Property; + rdfs:domain ex:Mammal; + rdfs:range xsd:dateTime; +``` + +The class the property belongs to is defined by `rdfs:domain`, while the +data type contained is defined by `rdfs:range`. By convention all +properties use dromedaryCase names, although property names are not +restricted. The allowed charset is UTF-8. + +The following basic types are supported: + +- `xsd:boolean` +- `xsd:string` and `rdf:langString` +- `xsd:integer`, ranging from -2^63 to 2^63-1. +- `xsd:double`, able to store a 8 byte IEEE floating point number. +- `xsd:date` and `xsd:dateTime`, able to store dates and times since + January 1st 1 AD, with microsecond resolution. + +Of course, properties can also point to resources of the same or +other classes, so stored resources can conform a graph: + +```turtle +ex:parent a rdf:Property; + rdfs:domain ex:Mammal; + rdfs:range ex:Mammal; + +ex:pet a rdf:Property; + rdfs:domain ex:Mammal; + rdfs:range ex:Eukaryote; +``` + +There is also inheritance of properties, an example would be a property +in a subclass concretizing a more generic property from a superclass. + +```turtle +ex:geneticInformation a rdf:Property; + rdfs:domain ex:Eukaryote; + rdfs:range xsd:string; + +ex:dna a rdf:Property; + rdfs:domain ex:Mammal; + rdfs:range xsd:string; + rdfs:subPropertyOf ex:geneticInformation. +``` + +SPARQL queries are expected to provide the same result when queried +for a property or one of its superproperties. + +```SPARQL +# These two queries should provide the exact same result(s) +SELECT { ?animal a ex:Animal; + ex:geneticInformation "AGCT" } +SELECT { ?animal a ex:Animal; + ex:dna "AGCT" } +``` + +## Defining cardinality of properties + +By default, properties are multivalued, there are no restrictions in +the number of values a property can store. + +```SPARQL +INSERT DATA { + <cat> a ex:Mammal . + <dog> a ex:Mammal . + + <peter> a ex:Mammal ; + ex:pets <cat>, <dog> +} +``` + +Wherever this is not desirable, cardinality can be limited on properties +through nrl:maxCardinality. + +```turtle +ex:cromosomes a rdf:Property; + rdfs:domain ex:Eukaryote; + rdfs:range xsd:integer; + nrl:maxCardinality 1. +``` + +This will raise an error if the SPARQL updates in the endpoint end up +in the property inserted multiple times. + +```SPARQL +# This will fail +INSERT DATA { <cat> a ex:Mammal; + ex:cromosomes 38; + ex:cromosomes 42 } + +# This will succeed +INSERT DATA { <donald> a ex:Mammal; + ex:cromosomes 47 } +``` + +Tracker does not implement support for other maximum cardinalities +than 1. + +<!--- + XXX: explain how cardinality affects subproperties, superproperties +---> + +## Defining uniqueness + +It is desirable for certain properties to keep their values unique +across all resources, this can be expressed by defining the properties +as being a nrl:InverseFunctionalProperty. + +```turtle +ex:geneticInformation a rdf:Property, nrl:InverseFunctionalProperty; + rdfs:domain ex:Eukaryote; + rdfs:range xsd:string; +``` + +With that in place, no two resources can have the same value on the +property. + +```SPARQL +# First insertion, this will succeed +INSERT DATA { <drosophila> a ex:Eukariote; + ex:geneticInformation "AGCT" } + +# This will fail +INSERT DATA { <melanogaster> a ex:Eukariote; + ex:geneticInformation "AGCT" } +``` + +<!--- + XXX: explain how inverse functional proeprties affect sub/superproperties +---> + +## Defining indexes + +It may be the case that SPARQL queries performed on the endpoint are +known to match, sort, or filter on certain properties more often than others. +In this case, the ontology may use nrl:domainIndex in the class definition: + +```turtle +# Make queries on ex:dateOfBirth faster +ex:Mammal a rdfs:Class; + rdfs:subClassOf ex:Animal; + rdfs:comment "A mammal"; + nrl:domainIndex ex:dateOfBirth. +``` + +Classes may define multiple domain indexes. + +**Note**: Be frugal with indexes, do not add these proactively. An index in the wrong +place might not affect query performance positively, but all indexes come at +a cost in disk size. + +## Defining full-text search properties + +Tracker provides nonstandard full-text search capabilities, in order to use +these, the string properties can use nrl:fulltextIndexed: + +```turtle +ex:name a rdf:Property; + rdfs:domain ex:Mammal; + rdfs:range xsd:string; + nrl:fulltextIndexed true; + nrl:weight 10. +``` + +Weighting can also be applied, so certain properties rank higher than others +in full-text search queries. With nrl:fulltextIndexed in place, sparql +queries may use full-text search capabilities: + +```SPARQL +SELECT { ?mammal a ex:Mammal; + fts:match "timmy" } +``` + +## Predefined elements + +It may be desirable for the ontology to offer predefined elements of a +certain class, which can then be used by the endpoint. + +```turtle +ex:self a ex:Mammal. +``` + +Usage does not differ in use from the elements of that same class that +could be inserted in the endpoint. + +```SPARQL +INSERT DATA { ex:self ex:pets <cat> . + <cat> ex:pets ex:self } +``` + +## Updating an ontology + +As software evolves, sometimes changes in the ontology are unavoidable. +Tracker can transparently handle certain ontology changes on existing +databases. + +1. Adding a class. +2. Removing a class. + All resources will be removed from this class, and all related + properties will disappear. +3. Adding a property. +4. Removing a property. + The property will disappear from all elements pertaining to the + class in domain of the property. +5. Changing rdfs:range of a property. + The following conversions are allowed: + + - `xsd:integer` to `xsd:bool`, `xsd:double` and `xsd:string`</listitem></varlistentry> + - `xsd:double` to `xsd:bool`, `xsd:integer` and `xsd:string`</listitem></varlistentry> + - `xsd:string` to `xsd:bool`, `xsd:integer` and `xsd:double`</listitem></varlistentry> + +6. Adding and removing `nrl:domainIndex` from a class. +7. Adding and removing `nrl:fulltextIndexed` from a property. +8. Changing the `nrl:weight` on a property. +9. Removing `nrl:maxCardinality` from a property. + +<!--- + XXX: these need documenting too + add intermediate superproperties + add intermediate superclasses + remove intermediate superproperties + remove intermediate superclasses +---> + +However, there are certain ontology changes that Tracker will find +incompatible. Either because they are incoherent or resulting into +situations where it can not deterministically satisfy the change +in the stored data. Tracker will error out and refuse to do any data +changes in these situations: + +- Properties with rdfs:range being `xsd:bool`, `xsd:date`, `xsd:dateTime`, + or any other custom class are not convertible. Only conversions + covered in the list above are accepted. +- You can not add `rdfs:subClassOf` in classes that are not being + newly added. You can not remove `rdfs:subClassOf` from classes. + The only allowed change to `rdfs:subClassOf` is to correct + subclasses when deleting a class, so they point a common + superclass. +- You can not add `rdfs:subPropertyOf` to properties that are not + being newly added. You can not change an existing + `rdfs:subPropertyOf` unless it is made to point to a common + superproperty. You can however remove `rdfs:subPropertyOf` from + non-new properties. +- Properties can not move across classes, thus any change in + `rdfs:domain` is forbidden. +- You can not add `nrl:maxCardinality` restrictions on properties that + are not being newly added. +- You can not add nor remove `nrl:InverseFunctionalProperty` from a + property that is not being newly added. + +The recommendation to bypass these situations is the same for all, +use different property and class names and use SPARQL to manually +migrate the old data to the new format if necessary. + +High level code is in a better position to solve the +possible incoherences (e.g. picking a single value if a property +changes from multiple values to single value). After the manual +data migration has been completed, the old classes and properties +can be dropped. + +Once changes are made, the `nrl:lastModified` value should be updated +so Tracker knows to reprocess the ontology. diff --git a/docs/reference/libtracker-sparql/overview.md b/docs/reference/libtracker-sparql/overview.md index c14769342..949d81c3f 100644 --- a/docs/reference/libtracker-sparql/overview.md +++ b/docs/reference/libtracker-sparql/overview.md @@ -1,9 +1,4 @@ ---- -title: Overview -short-description: Library Overview -... - -# Overview +Title: Overview Tracker SPARQL allows creating and connecting to one or more triplestore databases. It is used by the @@ -12,13 +7,13 @@ and can also store and publish any kind of app data. Querying data is done using the SPARQL graph query language. See the [examples](examples.html) to find out how this works. -Storing data can also be done using SPARQL, or using the [](TrackerResource) +Storing data can also be done using SPARQL, or using the [class@Tracker.Resource] API. -You can share a database over D-Bus using the [](TrackerEndpoint) API, +You can share a database over D-Bus using the [class@Tracker.Endpoint] API, allowing other libtracker-sparql users to query from it, either by referencing it in a `SELECT { SERVICE ... }` query, or by connecting -directly with [](tracker_sparql_connection_bus_new). +directly with [ctor@Tracker.SparqlConnection.bus_new]. Tracker SPARQL partitions the database into multiple graphs. You can implementing access control restrictions based on @@ -28,14 +23,14 @@ The number of graphs is [limited](limits.html). ## Connection methods You can create and access a private store using -[](tracker_sparql_connection_new). This is useful to store +[ctor@Tracker.SparqlConnection.new]. This is useful to store app-specific data. To connect to another database on the same local machine, such as the -one exposed by Tracker Miner FS, use [](tracker_sparql_connection_bus_new). +one exposed by Tracker Miner FS, use [ctor@Tracker.SparqlConnection.bus_new]. To connect to another a database on a remote machine, use -[](tracker_sparql_connection_remote_new). This can be used to query online +[ctor@Tracker.SparqlConnection.remote_new]. This can be used to query online databases that provide a SPARQL endpoint, such as [DBpedia](https://wiki.dbpedia.org/about). . ## Connecting from Flatpak @@ -48,7 +43,7 @@ The app's Flatpak manifest needs to specify which graph(s) the app will access. See the [example app](https://gitlab.gnome.org/GNOME/tracker/-/blob/master/examples/flatpak/org.example.TrackerSandbox.json) and the [portal documentation](https://gnome.pages.gitlab.gnome.org/tracker/docs/commandline/#tracker-xdg-portal-3) to see how. -No code changes are needed in the app, as [](tracker_sparql_connection_bus_new) +No code changes are needed in the app, as [ctor@Tracker.SparqlConnection.bus_new] will automatically try connect via the portal if it can't talk to the given D-Bus name directly. diff --git a/docs/reference/libtracker-sparql/performance.md b/docs/reference/libtracker-sparql/performance.md index 3994d850f..942b2de57 100644 --- a/docs/reference/libtracker-sparql/performance.md +++ b/docs/reference/libtracker-sparql/performance.md @@ -1,13 +1,9 @@ ---- -title: Performance dos and donts -short-description: Performance dos and donts -... - -# Performance advise +Title: Performance dos and donts +slug: performance-advise SPARQL is a very powerful query language. As it should be suspected, this means there are areas where performance is -sacrificed for versatility. +inherently sacrificed for versatility. These are some tips to get the best of SPARQL as implemented by Tracker. @@ -20,7 +16,7 @@ Queries with unrestricted predicates are those like: SELECT ?p { <a> ?p 42 } ``` -They involve lookups across all possible triples of +These involve lookups across all possible triples of an object, which roughly translates to a traversal through all tables and columns. @@ -30,7 +26,8 @@ The most pathological case is: SELECT ?s ?p ?o { ?s ?p ?o } ``` -Which does retrieve every triple existing in the store. +Which does retrieve every triple existing in the RDF +triple store. Queries with unrestricted predicates are most useful to introspect resources, or the triple store in its entirety. @@ -76,11 +73,11 @@ The graph(s) may be specified through SPARQL syntax for graphs. For example: ```SPARQL -WITH <G> SELECT ?u { ?u a rdfs:Resource } -WITH <G> SELECT ?g ?u { GRAPH ?g { ?u a rdfs:Resource }} +WITH <http://example.com/Graph> SELECT ?u { ?u a rdfs:Resource } +SELECT ?g ?u FROM NAMED <http://example.com/Graph> { GRAPH ?g { ?u a rdfs:Resource }} ``` -## Avoid substring matching +## Avoid globs and substring matching Matching for regexp/glob/substrings defeats any index text fields could have. For example: @@ -88,7 +85,7 @@ could have. For example: ```SPARQL SELECT ?u { ?u nie:title ?title . - FILTER (CONTAINS (?title, "sideshow")) + FILTER (CONTAINS (?title, "banana")) } ``` @@ -97,11 +94,11 @@ encouraged to use fulltext search for finding matches within strings where possible, for example: ```SPARQL -SELECT ?u { ?u fts:match "sideshow" } +SELECT ?u { ?u fts:match "banana" } ``` ## Use TrackerSparqlStatement -Using [](TrackerSparqlStatement) allows to parse and compile +Using [class@Tracker.SparqlStatement] allows to parse and compile a query once, and reuse it many times. Its usage is recommended wherever possible. diff --git a/docs/reference/libtracker-sparql/security.md b/docs/reference/libtracker-sparql/security.md index 6ea2fa3a2..034bda365 100644 --- a/docs/reference/libtracker-sparql/security.md +++ b/docs/reference/libtracker-sparql/security.md @@ -1,19 +1,17 @@ ---- -title: Security -short-description: Security considerations -... - -# Security considerations +Title: Security considerations +Slug: security-considerations The SPARQL 1.1 specifications have a number of informative `Security -considerations` sections. This section describes how those possibly -apply to the implementation of Tracker. +considerations` sections. This is an informative document describing how +those may or may not apply to the implementation of Tracker. Note that most of these considerations derive from situations where -a SPARQL store is exposed through a public endpoint, while Tracker +a RDF triple store is exposed through a public endpoint, while Tracker does not do that by default. Users should be careful about creating endpoints. For D-Bus endpoints, access through the portal is encouraged. +# SPARQL specifications + ## Queries (From [https://www.w3.org/TR/2013/REC-sparql11-query-20130321/#security](https://www.w3.org/TR/2013/REC-sparql11-query-20130321/#security)) @@ -81,7 +79,7 @@ sandboxed process have all SERVICE access restricted. Tracker developers encourage that all access to endpoints created on D-Bus happen through the portal, and that all HTTP endpoints validate the provenance -of the requests through the [](TrackerEndpointHttp::block-remote-address) +of the requests through the [signal@Tracker.EndpointHttp::block_remote_address] signal to limit access to resources. (From [https://www.w3.org/TR/sparql11-protocol/#policy-security](https://www.w3.org/TR/sparql11-protocol/#policy-security)) @@ -103,7 +101,7 @@ processing services. Tracker does not perform any time or frequency rate limits to queries. HTTP endpoints may perform the latter through the -[](TrackerEndpointHttp::block-remote-address) signal. +[signal@Tracker.EndpointHttp::block_remote_address] signal. ## Updates @@ -155,6 +153,27 @@ all the way to the public API. As an additional layer of security, readonly queries happen on readonly database connections. It is essentially not possible to perform any data change from the query APIs. +## IRIs + +IRIs are a cornerstone of RDF data, since individual RDF resources are typically +named through them. Quoting [https://www.w3.org/TR/sparql11-protocol/#policy-security](https://www.w3.org/TR/sparql11-protocol/#policy-security): + +``` +Different IRIs may have the same appearance. Characters in different scripts +may look similar (a Cyrillic "о" may appear similar to a Latin "o"). A +character followed by combining characters may have the same visual +representation as another character (LATIN SMALL LETTER E followed by +COMBINING ACUTE ACCENT has the same visual representation as LATIN SMALL +LETTER E WITH ACUTE). Users of SPARQL must take care to construct queries +with IRIs that match the IRIs in the data. Further information about matching +of similar characters can be found in Unicode Security Considerations +[UNISEC] and Internationalized Resource Identifiers (IRIs) [RFC3987] +Section 8. +``` + +The situations where this might be a source of confusion or mischief, or even +be possible depends on how those IRIs are created, used, displayed or +inserted. # API user considerations @@ -165,27 +184,11 @@ considerations and take some precautions: * For local D-Bus endpoints, consider using a graph partitioning scheme that makes it easy to policy the access to the data when accessed through the portal. - * Avoid the possibility of injection attacks. Use [](TrackerSparqlStatement) + * Avoid the possibility of injection attacks. Use [class@Tracker.SparqlStatement] and avoid string-based approaches to build SPARQL queries from user input. - * Consider that IRIs are susceptible to homograph attacks. Quoting - https://www.w3.org/TR/sparql11-protocol/#policy-security: - - ``` - Different IRIs may have the same appearance. Characters in different scripts - may look similar (a Cyrillic "о" may appear similar to a Latin "o"). A - character followed by combining characters may have the same visual - representation as another character (LATIN SMALL LETTER E followed by - COMBINING ACUTE ACCENT has the same visual representation as LATIN SMALL - LETTER E WITH ACUTE). Users of SPARQL must take care to construct queries - with IRIs that match the IRIs in the data. Further information about matching - of similar characters can be found in Unicode Security Considerations - [UNISEC] and Internationalized Resource Identifiers (IRIs) [RFC3987] - Section 8. - ``` - - The situations where this might be a source of confusion or mischief, or even - be possible depends on how those IRIs are created, used, displayed or - inserted. + * Consider that IRIs describing RDF resources are susceptible to homograph + attacks as described above. Developers are not exempt of validating + external input that might end up stored as-is. # Feature grid diff --git a/docs/reference/libtracker-sparql/sitemap.txt b/docs/reference/libtracker-sparql/sitemap.txt deleted file mode 100644 index a28c62b35..000000000 --- a/docs/reference/libtracker-sparql/sitemap.txt +++ /dev/null @@ -1,30 +0,0 @@ -index.md - overview.md - examples.md - tutorial.md - ontologies.md - nepomuk.md - nie-ontology.md - nao-ontology.md - nfo-ontology.md - nco-ontology.md - nmm-ontology.md - mfo-ontology.md - slo-ontology.md - tracker-ontology.md - osinfo-ontology.md - base-ontology.md - xsd-ontology.md - dc-ontology.md - rdf-ontology.md - rdfs-ontology.md - nrl-ontology.md - defining-ontologies.md - gi-index - sparql-functions.md - implementation.md - limits.md - performance.md - sparql-and-tracker.md - security.md - migrating-2to3.md diff --git a/docs/reference/libtracker-sparql/sparql-and-tracker.md b/docs/reference/libtracker-sparql/sparql-and-tracker.md index 436a1c74d..b1de7eb27 100644 --- a/docs/reference/libtracker-sparql/sparql-and-tracker.md +++ b/docs/reference/libtracker-sparql/sparql-and-tracker.md @@ -1,12 +1,9 @@ ---- -title: SPARQL as understood by Tracker -short-description: SPARQL as understood by Tracker -... +Title: SPARQL as understood by Tracker +slug: sparql-and-tracker -# SPARQL as understood by Tracker - -This section describes the choices made by Tracker in its interpretation -of the SPARQL documents, as well as its extensions and divergences. +This document describes the choices made by Tracker in its interpretation +of the SPARQL documents, as well as the ways it diverges or extends on the +specifications. ## The default graph @@ -37,13 +34,13 @@ the RDF abstract syntax, a blank node is just a unique node that can be used in one or more RDF statements, but has no intrinsic name. ``` -By default Tracker treats blank nodes as an URI generator instead. The +By default, Tracker does instead treat blank nodes as an URI generator. The string referencing a blank node (e.g. as returned by cursors) permanently identifies that blank node and can be used as an URI reference in future queries. The blank node behavior defined in the RDF/SPARQL specifications can -be enabled with the [](TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES) +be enabled with the #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag. ## Property functions @@ -277,7 +274,7 @@ are treated as parameters at query time, so it is possible to prepare a query statement once and reuse it many times assigning different values to those parameters at query time. -See [](TrackerSparqlStatement) documentation for more information. +See [class@Tracker.SparqlStatement] documentation for more information. ## Full-text search @@ -305,5 +302,5 @@ The DESCRIBE form returns a single result RDF graph containing RDF data about re ``` In order to allow serialization to RDF formats that allow expressing graph information -(e.g. Trig), DESCRIBE resultsets have 4 columns for subject / predicate / object / graph -information. +(e.g. [Trig](https://www.w3.org/TR/trig/)), DESCRIBE resultsets have 4 columns for +subject / predicate / object / graph information. diff --git a/docs/reference/libtracker-sparql/sparql-functions.md b/docs/reference/libtracker-sparql/sparql-functions.md index 939cac37b..be8a48a8c 100644 --- a/docs/reference/libtracker-sparql/sparql-functions.md +++ b/docs/reference/libtracker-sparql/sparql-functions.md @@ -1,17 +1,14 @@ ---- -title: Builtin SPARQL functions -short-description: Builtin SPARQL functions -... - -# Builtin SPARQL functions +Title: Builtin SPARQL functions +slug: sparql-functions Besides the functions built in the SPARQL 1.1 syntax, type casts and functional properties, Tracker supports a number of SPARQL -functions. Some of these functions have correspondences in XPath. +functions. Some of these functions have correspondences in +[XPath](https://www.w3.org/TR/xpath-31/). -## String functions +# String functions -### `fn:lower-case` +## `fn:lower-case` ```SPARQL fn:lower-case (?string) @@ -19,7 +16,7 @@ fn:lower-case (?string) Converts a string to lowercase, equivalent to `LCASE`. -### `fn:upper-case` +## `fn:upper-case` ```SPARQL fn:upper-case (?string) @@ -27,7 +24,7 @@ fn:upper-case (?string) Converts a string to uppercase, equivalent to `UCASE`. -### `fn:contains` +## `fn:contains` ```SPARQL fn:contains (?haystack, ?needle) @@ -36,7 +33,7 @@ fn:contains (?haystack, ?needle) Returns a boolean indicating whether `?needle` is found in `?haystack`. Equivalent to `CONTAINS`. -### `fn:starts-with` +## `fn:starts-with` ```SPARQL fn:starts-with (?string, ?prefix) @@ -45,7 +42,7 @@ fn:starts-with (?string, ?prefix) Returns a boolean indicating whether `?string` starts with `?prefix`. Equivalent to `STRSTARTS`. -### `fn:ends-with` +## `fn:ends-with` ```SPARQL fn:ends-with (?string, ?suffix) @@ -54,7 +51,7 @@ fn:ends-with (?string, ?suffix) Returns a boolean indicating whether `?string` ends with `?suffix`. Equivalent to `STRENDS`. -### `fn:substring` +## `fn:substring` ```SPARQL fn:substring (?string, ?startLoc) @@ -65,7 +62,7 @@ Returns a substring delimited by the integer `?startLoc` and `?endLoc` arguments. If `?endLoc` is omitted, the end of the string is used. -### `fn:concat` +## `fn:concat` ```SPARQL fn:concat (?string1, ?string2, ..., ?stringN) @@ -74,7 +71,7 @@ fn:concat (?string1, ?string2, ..., ?stringN) Takes a variable number of arguments and returns a string concatenation of all its returned values. Equivalent to `CONCAT`. -### `fn:string-join` +## `fn:string-join` ```SPARQL fn:string-join ((?string1, ?string2, ...), ?separator) @@ -83,7 +80,7 @@ fn:string-join ((?string1, ?string2, ...), ?separator) Takes a variable number of arguments and returns a string concatenation using `?separator` to join all elements. -### `fn:replace` +## `fn:replace` ```SPARQL fn:replace (?string, ?regex, ?replacement) @@ -111,7 +108,7 @@ If `?flags` contains the character `“i”`, search is caseless. If `?flags` contains the character `“x”`, `?regex` is interpreted to be an extended regular expression. -### `tracker:case-fold` +## `tracker:case-fold` ```SPARQL tracker:case-fold (?string) @@ -119,7 +116,7 @@ tracker:case-fold (?string) Converts a string into a form that is independent of case. -### `tracker:title-order` +## `tracker:title-order` ```SPARQL tracker:title-order (?string) @@ -128,7 +125,7 @@ tracker:title-order (?string) Manipulates a string to remove leading articles for sorting purposes, e.g. “Wall, The”. Best used in `ORDER BY` clauses. -### `tracker:ascii-lower-case` +## `tracker:ascii-lower-case` ```SPARQL tracker:ascii-lower-case (?string) @@ -136,7 +133,7 @@ tracker:ascii-lower-case (?string) Converts an ASCII string to lowercase, equivalent to `LCASE`. -### `tracker:normalize` +## `tracker:normalize` ```SPARQL tracker:normalize (?string, ?option) @@ -145,7 +142,7 @@ tracker:normalize (?string, ?option) Normalizes `?string`. The `?option` string must be one of `nfc`, `nfd`, `nfkc` or `nfkd`. -### `tracker:unaccent` +## `tracker:unaccent` ```SPARQL tracker:unaccent (?string) @@ -153,7 +150,7 @@ tracker:unaccent (?string) Removes accents from a string. -### `tracker:coalesce` +## `tracker:coalesce` ```SPARQL tracker:coalesce (?value1, ?value2, ..., ?valueN) @@ -161,7 +158,7 @@ tracker:coalesce (?value1, ?value2, ..., ?valueN) Picks the first non-null value. Equivalent to `COALESCE`. -### `tracker:strip-punctuation` +## `tracker:strip-punctuation` ``` SPARQL tracker:strip-punctuation (?string) @@ -170,9 +167,9 @@ tracker:strip-punctuation (?string) Removes any Unicode character which has the General Category value of P (Punctuation) from the string. -## DateTime functions +# DateTime functions -### `fn:year-from-dateTime` +## `fn:year-from-dateTime` ```SPARQL fn:year-from-dateTime (?date) @@ -182,7 +179,7 @@ Returns the year from a `xsd:date` type, a `xsd:dateTime` type, or a ISO8601 date string. This function is equivalent to `YEAR`. -### `fn:month-from-dateTime` +## `fn:month-from-dateTime` ```SPARQL fn:month-from-dateTime (?date) @@ -191,7 +188,7 @@ fn:month-from-dateTime (?date) Returns the month from a `xsd:date` type, a `xsd:dateTime` type, or a ISO8601 date string. This function is equivalent to `MONTH`. -### `fn:day-from-dateTime` +## `fn:day-from-dateTime` ```SPARQL fn:day-from-dateTime (?date) @@ -200,7 +197,7 @@ fn:day-from-dateTime (?date) Returns the day from a `xsd:date` type, a `xsd:dateTime` type, or a ISO8601 date string. This function is equivalent to `DAY`. -### `fn:hours-from-dateTime` +## `fn:hours-from-dateTime` ```SPARQL fn:hours-from-dateTime (?date) @@ -209,7 +206,7 @@ fn:hours-from-dateTime (?date) Returns the hours from a `xsd:dateTime` type or a ISO8601 datetime string. This function is equivalent to `HOURS`. -### `fn:minutes-from-dateTime` +## `fn:minutes-from-dateTime` ```SPARQL fn:minutes-from-dateTime (?date) @@ -219,7 +216,7 @@ Returns the minutes from a `xsd:dateTime` type or a ISO8601 datetime string. This function is equivalent to `MINUTES`. -### `fn:seconds-from-dateTime` +## `fn:seconds-from-dateTime` ```SPARQL fn:seconds-from-dateTime (?date) @@ -229,7 +226,7 @@ Returns the seconds from a `xsd:dateTime` type or a ISO8601 datetime string. This function is equivalent to `SECONDS`. -### `fn:timezone-from-dateTime` +## `fn:timezone-from-dateTime` ```SPARQL fn:timezone-from-dateTime (?date) @@ -240,7 +237,7 @@ not equivalent to `TIMEZONE` or `TZ`. ## Full-text search functions -### `fts:rank` +## `fts:rank` ```SPARQL fts:rank (?match) @@ -249,7 +246,7 @@ fts:rank (?match) Returns the rank of a full-text search match. Must be used in conjunction with `fts:match`. -### `fts:offsets` +## `fts:offsets` ```SPARQL fts:offsets (?match) @@ -263,7 +260,7 @@ string has the format: prefix:property:offset prefix:property:offset prefix:property:offset ``` -### `fts:snippet` +## `fts:snippet` ```SPARQL fts:snippet (?match) @@ -284,9 +281,9 @@ the string used to separate distant matches in the snippet string. The `?numTokens` parameter specifies the number of tokens the returned string should containt at most. -## URI functions +# URI functions -### `tracker:uri-is-parent` +## `tracker:uri-is-parent` ```SPARQL tracker:uri-is-parent (?parent, ?uri) @@ -295,7 +292,7 @@ tracker:uri-is-parent (?parent, ?uri) Returns a boolean value expressing whether `?parent` is a parent of `?uri`. -### `tracker:uri-is-descendant` +## `tracker:uri-is-descendant` ```SPARQL tracker:uri-is-descendant (?uri1, ?uri2, ..., ?uriN, ?child) @@ -305,7 +302,7 @@ Returns a boolean value expressing whether one of the given URIs are a parent (direct or indirect) of `?child`. -### `tracker:string-from-filename` +## `tracker:string-from-filename` ```SPARQL tracker:string-from-filename (?filename) @@ -313,9 +310,9 @@ tracker:string-from-filename (?filename) Returns a UTF-8 string from a filename. -## Geolocation functions +# Geolocation functions -### `tracker:cartesian-distance` +## `tracker:cartesian-distance` ```SPARQL tracker:cartesian-distance (?lat1, ?lat2, ?lon1, ?lon2) @@ -324,7 +321,7 @@ tracker:cartesian-distance (?lat1, ?lat2, ?lon1, ?lon2) Calculates the cartesian distance between 2 points expressed by `?lat1 / ?lon1` and `?lat2 / ?lon2`. -### `tracker:haversine-distance` +## `tracker:haversine-distance` ```SPARQL tracker:haversine-distance (?lat1, ?lat2, ?lon1, ?lon2) @@ -333,9 +330,9 @@ tracker:haversine-distance (?lat1, ?lat2, ?lon1, ?lon2) Calculates the haversine distance between 2 points expressed by `?lat1 / ?lon1` and `?lat2 / ?lon2`. -## Identification functions +# Identification functions -### `tracker:id` +## `tracker:id` ```SPARQL tracker:id (?urn) @@ -344,7 +341,7 @@ tracker:id (?urn) Returns the internal ID corresponding to a URN. Its inverse operation is `tracker:uri`. -### `tracker:uri` +## `tracker:uri` ```SPARQL tracker:uri (?id) diff --git a/docs/reference/libtracker-sparql/theme-extra/css/tracker-custom.css b/docs/reference/libtracker-sparql/theme-extra/css/tracker-custom.css deleted file mode 100644 index dc1ed37bf..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/css/tracker-custom.css +++ /dev/null @@ -1,3 +0,0 @@ -#page-description img { - display: inherit; -} diff --git a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.js b/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.js deleted file mode 100644 index 691d48707..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.js +++ /dev/null @@ -1,65 +0,0 @@ -/* Original at https://github.com/PrismJS/prism.git, under MIT license. - * Plus adaptions to make it work on ancient prism as used by hotdoc, - * and our own keywords. - */ -Prism.languages.sparql = { - 'comment': { - pattern: /#.*/, - greedy: true - }, - 'multiline-string': { - pattern: /"""(?:(?:""?)?(?:[^"\\]|\\.))*"""|'''(?:(?:''?)?(?:[^'\\]|\\.))*'''/, - greedy: true, - alias: 'string', - inside: { - 'comment': /#.*/ - } - }, - 'string': { - pattern: /"(?:[^\\"\r\n]|\\.)*"|'(?:[^\\'\r\n]|\\.)*'/, - greedy: true - }, - 'url': { - pattern: /<(?:[^\x00-\x20<>"{}|^`\\]|\\(?:u[\da-fA-F]{4}|U[\da-fA-F]{8}))*>/, - greedy: true, - inside: { - 'punctuation': /[<>]/ - } - }, - 'function': { - pattern: /(?:(?![-.\d\xB7])[-.\w\xB7\xC0-\uFFFD]+)?:(?:(?![-.])(?:[-.:\w\xC0-\uFFFD]|%[\da-f]{2}|\\.)+)?/i, - inside: { - 'local-name': { - pattern: /([^:]*:)[\s\S]+/, - lookbehind: true - }, - 'prefix': { - pattern: /[\s\S]+/, - inside: { - 'punctuation': /:/ - } - } - } - }, - 'number': /[+-]?\b\d+(?:\.\d*)?(?:e[+-]?\d+)?/i, - 'punctuation': /[{}.,;()[\]]|\^\^/, - 'boolean': /\b(?:true|false)\b/i, - 'keyword': [ - /\b(?:A|ADD|ALL|AS|ASC|ASK|BNODE|BY|CLEAR|CONSTRAINT|CONSTRUCT|COPY|CREATE|DATA|DEFAULT|DELETE|DESC|DESCRIBE|DISTINCT|DROP|EXISTS|FILTER|FROM|GROUP|HAVING|INSERT|INTO|LIMIT|LOAD|MINUS|MOVE|NAMED|NOT|NOW|OFFSET|OPTIONAL|OR|ORDER|RAND|REDUCED|REPLACE|SELECT|SEPARATOR|SERVICE|SILENT|STRUUID|UNION|USING|UUID|VALUES|WHERE)\b/i, - /\b(?:ABS|AVG|BIND|BOUND|CEIL|COALESCE|CONCAT|CONTAINS|COUNT|DATATYPE|DAY|ENCODE_FOR_URI|FLOOR|GROUP_CONCAT|HOURS|IF|IRI|isBLANK|isIRI|isLITERAL|isNUMERIC|isURI|LANG|LANGMATCHES|LCASE|MAX|MD5|MIN|MINUTES|MONTH|ROUND|REGEX|REPLACE|sameTerm|SAMPLE|SECONDS|SHA1|SHA256|SHA384|SHA512|STR|STRAFTER|STRBEFORE|STRDT|STRENDS|STRLANG|STRLEN|STRSTARTS|SUBSTR|SUM|TIMEZONE|TZ|UCASE|URI|YEAR)\b(?=\s*\()/i, - /\b(?:GRAPH|BASE|PREFIX)\b/i, - /(?:\ba|@prefix|@base)\b|=/, - /\b(?:graph|base|prefix)\b/i - ], - 'variable': { - pattern: /[?$]\w+/, - greedy: true - }, - 'tag': { - pattern: /@[a-z]+(?:-[a-z\d]+)*/i, - inside: { - 'punctuation': /@/ - } - } -}; -Prism.languages.rq = Prism.languages.sparql; diff --git a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.min.js b/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.min.js deleted file mode 100644 index 0df615e1e..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-sparql.min.js +++ /dev/null @@ -1 +0,0 @@ -Prism.languages.sparql={'comment':{pattern:/#.*/,greedy:true},'multiline-string':{pattern:/"""(?:(?:""?)?(?:[^"\\]|\\.))*"""|'''(?:(?:''?)?(?:[^'\\]|\\.))*'''/,greedy:true,alias:'string',inside:{'comment':/#.*/}},'string':{pattern:/"(?:[^\\"\r\n]|\\.)*"|'(?:[^\\'\r\n]|\\.)*'/,greedy:true},'url':{pattern:/<(?:[^\x00-\x20<>"{}|^`\\]|\\(?:u[\da-fA-F]{4}|U[\da-fA-F]{8}))*>/,greedy:true,inside:{'punctuation':/[<>]/}},'function':{pattern:/(?:(?![-.\d\xB7])[-.\w\xB7\xC0-\uFFFD]+)?:(?:(?![-.])(?:[-.:\w\xC0-\uFFFD]|%[\da-f]{2}|\\.)+)?/i,inside:{'local-name':{pattern:/([^:]*:)[\s\S]+/,lookbehind:true},'prefix':{pattern:/[\s\S]+/,inside:{'punctuation':/:/}}}},'number':/[+-]?\b\d+(?:\.\d*)?(?:e[+-]?\d+)?/i,'punctuation':/[{}.,;()[\]]|\^\^/,'boolean':/\b(?:true|false)\b/i,'keyword':[/\b(?:A|ADD|ALL|AS|ASC|ASK|BNODE|BY|CLEAR|CONSTRAINT|CONSTRUCT|COPY|CREATE|DATA|DEFAULT|DELETE|DESC|DESCRIBE|DISTINCT|DROP|EXISTS|FILTER|FROM|GROUP|HAVING|INSERT|INTO|LIMIT|LOAD|MINUS|MOVE|NAMED|NOT|NOW|OFFSET|OPTIONAL|OR|ORDER|RAND|REDUCED|REPLACE|SELECT|SEPARATOR|SERVICE|SILENT|STRUUID|UNION|USING|UUID|VALUES|WHERE)\b/i,/\b(?:ABS|AVG|BIND|BOUND|CEIL|COALESCE|CONCAT|CONTAINS|COUNT|DATATYPE|DAY|ENCODE_FOR_URI|FLOOR|GROUP_CONCAT|HOURS|IF|IRI|isBLANK|isIRI|isLITERAL|isNUMERIC|isURI|LANG|LANGMATCHES|LCASE|MAX|MD5|MIN|MINUTES|MONTH|ROUND|REGEX|REPLACE|sameTerm|SAMPLE|SECONDS|SHA1|SHA256|SHA384|SHA512|STR|STRAFTER|STRBEFORE|STRDT|STRENDS|STRLANG|STRLEN|STRSTARTS|SUBSTR|SUM|TIMEZONE|TZ|UCASE|URI|YEAR)\b(?=\s*\()/i,/\b(?:GRAPH|BASE|PREFIX)\b/i,/(?:\ba|@prefix|@base)\b|=/,/\b(?:graph|base|prefix)\b/i],'variable':{pattern:/[?$]\w+/,greedy:true},'tag':{pattern:/@[a-z]+(?:-[a-z\d]+)*/i,inside:{'punctuation':/@/}}};Prism.languages.rq=Prism.languages.sparql; diff --git a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.js b/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.js deleted file mode 100644 index 4d588f716..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.js +++ /dev/null @@ -1,55 +0,0 @@ -/* Original at https://github.com/PrismJS/prism.git, under MIT license */ -Prism.languages.turtle = { - 'comment': { - pattern: /#.*/, - greedy: true - }, - 'multiline-string': { - pattern: /"""(?:(?:""?)?(?:[^"\\]|\\.))*"""|'''(?:(?:''?)?(?:[^'\\]|\\.))*'''/, - greedy: true, - alias: 'string', - inside: { - 'comment': /#.*/ - } - }, - 'string': { - pattern: /"(?:[^\\"\r\n]|\\.)*"|'(?:[^\\'\r\n]|\\.)*'/, - greedy: true - }, - 'url': { - pattern: /<(?:[^\x00-\x20<>"{}|^`\\]|\\(?:u[\da-fA-F]{4}|U[\da-fA-F]{8}))*>/, - greedy: true, - inside: { - 'punctuation': /[<>]/ - } - }, - 'function': { - pattern: /(?:(?![-.\d\xB7])[-.\w\xB7\xC0-\uFFFD]+)?:(?:(?![-.])(?:[-.:\w\xC0-\uFFFD]|%[\da-f]{2}|\\.)+)?/i, - inside: { - 'local-name': { - pattern: /([^:]*:)[\s\S]+/, - lookbehind: true - }, - 'prefix': { - pattern: /[\s\S]+/, - inside: { - 'punctuation': /:/ - } - } - } - }, - 'number': /[+-]?\b\d+(?:\.\d*)?(?:e[+-]?\d+)?/i, - 'punctuation': /[{}.,;()[\]]|\^\^/, - 'boolean': /\b(?:true|false)\b/, - 'keyword': [ - /(?:\ba|@prefix|@base)\b|=/, - /\b(?:graph|base|prefix)\b/i - ], - 'tag': { - pattern: /@[a-z]+(?:-[a-z\d]+)*/i, - inside: { - 'punctuation': /@/ - } - } -}; -Prism.languages.trig = Prism.languages['turtle']; diff --git a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.min.js b/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.min.js deleted file mode 100644 index eaa96996e..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/prism_components/prism-turtle.min.js +++ /dev/null @@ -1 +0,0 @@ -Prism.languages.turtle={comment:{pattern:/#.*/,greedy:!0},"multiline-string":{pattern:/"""(?:(?:""?)?(?:[^"\\]|\\.))*"""|'''(?:(?:''?)?(?:[^'\\]|\\.))*'''/,greedy:!0,alias:"string",inside:{comment:/#.*/}},string:{pattern:/"(?:[^\\"\r\n]|\\.)*"|'(?:[^\\'\r\n]|\\.)*'/,greedy:!0},url:{pattern:/<(?:[^\x00-\x20<>"{}|^`\\]|\\(?:u[\da-fA-F]{4}|U[\da-fA-F]{8}))*>/,greedy:!0,inside:{punctuation:/[<>]/}},function:{pattern:/(?:(?![-.\d\xB7])[-.\w\xB7\xC0-\uFFFD]+)?:(?:(?![-.])(?:[-.:\w\xC0-\uFFFD]|%[\da-f]{2}|\\.)+)?/i,inside:{"local-name":{pattern:/([^:]*:)[\s\S]+/,lookbehind:!0},prefix:{pattern:/[\s\S]+/,inside:{punctuation:/:/}}}},number:/[+-]?\b\d+(?:\.\d*)?(?:e[+-]?\d+)?/i,punctuation:/[{}.,;()[\]]|\^\^/,boolean:/\b(?:true|false)\b/,keyword:[/(?:\ba|@prefix|@base)\b|=/,/\b(?:graph|base|prefix)\b/i],tag:{pattern:/@[a-z]+(?:-[a-z\d]+)*/i,inside:{punctuation:/@/}}},Prism.languages.trig=Prism.languages.turtle;
\ No newline at end of file diff --git a/docs/reference/libtracker-sparql/theme-extra/templates/navbar_links.html b/docs/reference/libtracker-sparql/theme-extra/templates/navbar_links.html deleted file mode 100644 index ad72a1401..000000000 --- a/docs/reference/libtracker-sparql/theme-extra/templates/navbar_links.html +++ /dev/null @@ -1,6 +0,0 @@ -@require(page) - -<li> - <a href="https://gnome.pages.gitlab.gnome.org/tracker/">Website</a> -</li> - diff --git a/docs/reference/libtracker-sparql/tracker-sparql.toml.in b/docs/reference/libtracker-sparql/tracker-sparql.toml.in new file mode 100644 index 000000000..fef19fe55 --- /dev/null +++ b/docs/reference/libtracker-sparql/tracker-sparql.toml.in @@ -0,0 +1,57 @@ +[library] +version = "@version@" +browse_url = "https://gitlab.gnome.org/GNOME/tracker/" +repository_url = "https://gitlab.gnome.org/GNOME/tracker.git" +website_url = "https://tracker.gnome.org/" +authors = "Tracker Development Team" +logo_url = "logo.svg" +license = "GPL-2.1-or-later" +description = "Low-footprint RDF triple store with SPARQL 1.1 interface" + +dependencies = [ "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "GObject Interfaces and Objects, Networking, IPC, and I/O" + docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = false + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/tracker/-/blob/master/" + +[extra] +content_files = [ + @content@, +] +content_images = [ + "logo.svg", + "images/icon-deprecated.svg", + "images/icon-fulltextindexed.svg", + "images/icon-multivalue.svg", + "images/icon-notify.svg", + "images/icon-superproperty.svg", +] + +urlmap_file = "urlmap.js" + +# Overrides +[[object]] +# Deprecation macros don't matter to anyone but us +pattern = "DEPRECATED_IN.*" +hidden = true + +[[object]] +# Object type name capitalization messes with gi-docgen matching of type macros +pattern = "ENDPOINT_DBUS.*" +hidden = true diff --git a/docs/reference/libtracker-sparql/tutorial.md b/docs/reference/libtracker-sparql/tutorial.md.in index 0f0691d56..6a19663bf 100644 --- a/docs/reference/libtracker-sparql/tutorial.md +++ b/docs/reference/libtracker-sparql/tutorial.md.in @@ -1,32 +1,33 @@ ---- -title: SPARQL Tutorial -short-description: SPARQL Tutorial +Title: SPARQL Tutorial +Slug: sparql-tutorial ... -# SPARQL Tutorial +This document aims to introduce you to RDF and SPARQL from the ground +up, up to a point where SPARQL queries will become familiar and approachable +to reason about. -This tutorial aims to introduce you to RDF and SPARQL from the ground -up. All examples come from the Nepomuk ontology, and even though +Different RDF triple stores may have different data layouts. All examples +in this tutorial come from the Nepomuk ontology, and even though the tutorial aims to be generic enough, it mentions things -specific to Tracker, those are clearly spelled out. +specific to Tracker. Those are clearly spelled out. If you are reading this tutorial, you might also have Tracker installed in your system, if that is the case you can for example start a fresh empty SPARQL service for local testing: ```bash -$ tracker3 endpoint --dbus-service a.b.c --ontology nepomuk +$ tracker3 endpoint --dbus-service org.example.Endpoint --ontology nepomuk ``` The queries can be run in this specific service with: ```bash -$ tracker3 sparql --dbus-service a.b.c --query $SPARQL_QUERY +$ tracker3 sparql --dbus-service org.example.Endpoint --query $SPARQL_QUERY ``` ## RDF Triples -RDF data define a graph, composed by vertices and edges. This graph is +RDF data defines a graph, composed by vertices and edges. This graph is directed, because edges point from one vertex to another, and it is labeled, as those edges have a name. The unit of data in RDF is a triple of the form: @@ -35,7 +36,9 @@ triple of the form: Or expressed visually: - +<div class="docblock"> +{{ images/triple-graph-1.svg }} +</div> Subject and object are 2 graph vertices and the predicate is the edge, the accumulation of those triples form the full graph. For example, @@ -65,7 +68,9 @@ the following triples: Would visually generate the following graph: - +<div class="docblock"> +{{ images/triple-graph-2.svg }} +</div> The dot after each triple is not (just) there for legibility, but is part of the syntax. The RDF triples in full length are quite @@ -282,7 +287,10 @@ SELECT ?song ?songTitle ?albumTitle { ``` Stop a bit to think on the graph pattern expressed in the last query: - + +<div class="docblock"> +{{ images/triple-graph-3.svg }} +</div> This pattern on one hand consists of specified data (eg. `?song` must be a `nmm:MusicPiece`, it must have a `nmm:musicAlbum` and a `nie:title`, @@ -316,7 +324,7 @@ ASK { Sadly, not everything in the world can be trivially mapped to a URI, as an aide Tracker offers helpers to generate URIs based -on UUIDv4 identifiers like [](tracker_sparql_get_uuid_urn), +on UUIDv4 identifiers like [func@Tracker.sparql_get_uuid_urn], these generated strings are typically called URNs. The `BASE` keyword allows setting a common prefix for all URIs @@ -547,7 +555,9 @@ sets of `subject predicate object`. A single predicate like that is the simplest property path there is, it relates subject and object directly via a labeled arrow. - +<div class="docblock"> +{{ images/triple-graph-1.svg }} +</div> Property paths make it possible to define more complex connections between subject and object (literally, paths of properties). The `/` @@ -701,8 +711,8 @@ SELECT ?song ?value { ``` To learn more about how ontologies are done, read the documentation about -[defining ontologies](ontologies.md). Tracker also provides a stock -[Nepomuk](nepomuk.md) ontology, ready for use. +[defining ontologies](ontologies.html#creating-custom-ontologies). Tracker also provides a stock +[Nepomuk](ontologies.html#nepomuk) ontology, ready for use. ## Inserting data @@ -856,8 +866,8 @@ Where any second insert would be redundantly attempting to add the same triple to the store. By default, Tracker deviates from the SPARQL standard in the handling -of blank nodes, these are considered a generator of URIs. The -[](TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES) flag may be used to +of blank nodes, these are considered a generator of URIs. +The #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag may be used to make Tracker honor the SPARQL 1.1 standard with those. The standard defines blank nodes as truly anonymous, you can only use them to determine that there is something that matches the graph pattern you defined. The @@ -871,7 +881,7 @@ SELECT ?u { ``` Tracker by default will provide you with URNs that can be fed into other -SPARQL queries as URIs. With [](TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES) +SPARQL queries as URIs. With #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES enabled, the returned elements will be temporary names that can only be used to determine the existence of a distinct match. There, blank nodes can match named nodes, but named nodes do not match with blank nodes. @@ -1072,8 +1082,7 @@ to query information in RDF data graphs) very thoroughly, it also has some unusual features that make it able to scale from small private databases to large distributed ones. -This is not all that there is, and perhaps the "everything is a graph" mindset -takes a while to think intuitively about to anyone with a background in -relational databases. The purpose that this tutorial hopefully achieved is -that SPARQL queries will now look familiar, and became approachable to reason -about. +Perhaps the "everything is a graph" mindset takes a while to think intuitively +about to anyone with a background in relational databases. As with any complex +language, mastery requires dedication. This is probably just the beginning of a +journey. diff --git a/docs/reference/libtracker-sparql/urlmap.js b/docs/reference/libtracker-sparql/urlmap.js new file mode 100644 index 000000000..67e8a251f --- /dev/null +++ b/docs/reference/libtracker-sparql/urlmap.js @@ -0,0 +1,6 @@ +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'GLib', 'https://docs.gtk.org/glib/' ], + [ 'GObject', 'https://docs.gtk.org/gobject/' ], + [ 'Gio', 'https://docs.gtk.org/gio/' ], +] diff --git a/docs/reference/meson.build b/docs/reference/meson.build index 8ef80ee9f..58d222006 100644 --- a/docs/reference/meson.build +++ b/docs/reference/meson.build @@ -1,3 +1,3 @@ -docpath = join_paths(datadir, 'gtk-doc') +docpath = join_paths(datadir) subdir('libtracker-sparql') diff --git a/docs/tools/meson.build b/docs/tools/meson.build index 5bb96c1da..3281db4d4 100644 --- a/docs/tools/meson.build +++ b/docs/tools/meson.build @@ -4,7 +4,6 @@ doctool_gresources = gnome.compile_resources('tracker_doctool_gresources', 'dsc- doctool_files = [ 'tracker-docgen-md.c', - 'tracker-docgen-xml.c', 'tracker-main.c', 'tracker-ontology-model.c', 'tracker-utils.c', diff --git a/docs/tools/tracker-docgen-md.c b/docs/tools/tracker-docgen-md.c index 4d4d929fb..0aa099135 100644 --- a/docs/tools/tracker-docgen-md.c +++ b/docs/tools/tracker-docgen-md.c @@ -57,6 +57,12 @@ print_predefined_instances (FILE *f, if (!klass->instances) return; + if (g_str_equal (klass->shortname, "rdfs:Resource") || + g_str_equal (klass->shortname, "rdfs:DataType") || + g_str_equal (klass->shortname, "rdfs:Class") || + g_str_equal (klass->shortname, "rdf:Property") || + g_str_equal (klass->shortname, "nie:InformationElement")) + return; id = klass->shortname; @@ -75,32 +81,66 @@ print_class_hierarchy (FILE *f, TrackerOntologyClass *klass, TrackerOntologyModel *model) { - GPtrArray *strings; const gchar *id; - guint i; - - strings = class_get_parent_hierarchy_strings (klass, model); - if (!strings) + if (!klass->superclasses && !klass->subclasses) + return; + if (g_str_equal (klass->shortname, "nie:InformationElement")) return; id = klass->shortname; - g_fprintf (f, "#### <a name=\"%s.hierarchy\"></a>Class hierarchy\n\n", id); - g_fprintf (f, "```\n"); - //g_fprintf (f, " <code>\n"); + g_fprintf (f, "<div class=\"docblock\">\n"); + g_fprintf (f, "{{ %s-hierarchy.svg }}\n", id); + g_fprintf (f, "</div>\n"); +} - for (i = 0; i < strings->len; i++) { - HierarchyString *str = g_ptr_array_index (strings, i); +static gboolean +check_range_non_literals (GList *properties, + TrackerOntologyModel *model) +{ + GList *l; - g_fprintf (f, "%s%s%s\n", - str->before->str, - str->class->shortname, - str->after->str); + for (l = properties; l; l = l->next) { + TrackerOntologyProperty *prop; + TrackerOntologyClass *domain; + + prop = tracker_ontology_model_get_property (model, l->data); + domain = tracker_ontology_model_get_class (model, prop->range->data); + + if (g_str_has_prefix (domain->shortname, "xsd:") || + g_str_equal (domain->shortname, "rdfs:Literal") || + g_str_equal (domain->shortname, "rdf:langString")) + continue; + + return TRUE; } - g_fprintf (f, "```\n\n"); - g_ptr_array_unref (strings); + return FALSE; +} + +static void +print_rdf_diagram (FILE *f, + TrackerOntologyClass *klass, + TrackerOntologyModel *model) +{ + const gchar *id; + + if (!klass->in_range_of && + !check_range_non_literals (klass->in_domain_of, model)) + return; + + id = klass->shortname; + g_fprintf (f, "#### <a name=\"%s.hierarchy\"></a>RDF Diagram\n\n", id); + g_fprintf (f, "<div class=\"docblock\">\n"); + g_fprintf (f, + "<style>" + "svg .edge:hover a { text-decoration: none !important; fill: var(--primary); } " + "svg .edge:hover path { stroke: var(--primary); } " + "svg .edge:hover polygon { fill: var(--primary); stroke: var(--primary); }" + "</style>\n"); + g_fprintf (f, "{{ %s-diagram.svg }}\n", id); + g_fprintf (f, "</div>\n"); } static void @@ -109,7 +149,7 @@ print_flag (FILE *f, const gchar *icon_name, const gchar *flag_description) { - g_fprintf (f, "[![%s](images/%s \"%s\")](%s)", + g_fprintf (f, "[![%s](%s \"%s\")](%s)", flag_description, icon_name, flag_description, flag_property_link); } @@ -127,8 +167,6 @@ print_property_table (FILE *f, properties_sorted = g_list_sort (g_list_copy (properties), (GCompareFunc) strcmp); - g_fprintf (f, "#### <a name=\"%s.properties\"></a>Properties\n\n", id); - g_fprintf (f, "|Name|Type|Notes|Description|\n"); g_fprintf (f, "| --- | --- | --- | --- |\n"); @@ -220,11 +258,9 @@ print_ontology_class (TrackerOntologyModel *model, id = klass->shortname; /* Anchor for external links. */ - g_fprintf (f, "### <a name=\"%s\"></a>%s\n\n", id, name); + g_fprintf (f, "## <a name=\"%s\"></a>%s\n\n", id, name); if (klass->description || klass->deprecated || klass->notify) { - g_fprintf (f, "##### Description\n\n"); - if (klass->description) { g_fprintf (f, "%s\n\n", klass->description); } @@ -239,20 +275,26 @@ print_ontology_class (TrackerOntologyModel *model, g_fprintf (f, "**Note:** "); print_flag (f, "nrl-ontology.html#nrl:notify", "icon-notify.svg", "Notify icon"); g_fprintf (f, "This class emits notifications about changes, and can " - "be monitored using `TrackerNotifier`."); + "be monitored using [class@Tracker.Notifier]."); g_fprintf (f, "\n\n"); } } - if (klass->specification) { - g_fprintf (f, "### Specification\n"); - g_fprintf (f, "<%s>\n", klass->specification); + print_class_hierarchy (f, klass, model); + print_rdf_diagram (f, klass, model); + + if (klass->in_domain_of) { + g_fprintf (f, "#### <a name=\"%s.properties\"></a>Properties\n\n", id); + print_property_table (f, model, id, klass->in_domain_of); } - print_class_hierarchy (f, klass, model); print_predefined_instances (f, klass, model); - print_property_table (f, model, id, klass->in_domain_of); + if (klass->specification) { + g_fprintf (f, "#### Specification\n"); + g_fprintf (f, "<%s>\n", klass->specification); + } + } static void @@ -272,10 +314,9 @@ print_ontology_extra_properties (TrackerOntologyModel *model, short_classname = class_id = klass->shortname; section_id = g_strconcat (ontology_prefix, ".", class_id, NULL); - g_fprintf (f, "### <a name=\"%s\"></a>Additional properties for %s\n", section_id, short_classname); + g_fprintf (f, "# <a name=\"%s\"></a>Additional properties for %s\n", section_id, short_classname); - g_fprintf (f, "#### Description\n"); - g_fprintf (f, "Properties this ontology defines which can describe %s resources.\n", + g_fprintf (f, "Properties this ontology defines which can describe %s resources.\n\n", short_classname); print_property_table (f, model, section_id, properties_for_class); @@ -324,17 +365,23 @@ print_link (FILE *f, static void print_md_header (FILE *f, TrackerOntologyDescription *desc) { - g_fprintf (f, "---\n"); - g_fprintf (f, "title: %s\n", desc->title); - g_fprintf (f, "short-description: %s\n", desc->description); - g_fprintf (f, "...\n\n"); - g_fprintf (f, "# %s\n\n", desc->title); + g_fprintf (f, "Title: %s\n", desc->title); + g_fprintf (f, "Slug: %s-ontology\n\n", desc->localPrefix); + g_fprintf (f, "%s\n\n", desc->description); + g_fprintf (f, + "<style>" + "img { display: inline-block } " + "table { border-collapse: collapse; } " + "tr { border: none !important; } " + "tr:hover { background: var(--box-bg); } " + "td:not(:last-child), th:not(:last-child) { border: none; border-right: solid 1px #888; }" + "</style>\n"); } static void print_md_footer (FILE *f, TrackerOntologyDescription *desc) { - g_fprintf (f, "## Credits and Copyright\n\n"); + g_fprintf (f, "# Credits and Copyright\n\n"); print_people_list (f, "Authors:", desc->authors); print_people_list (f, "Editors:", desc->editors); print_people_list (f, "Contributors:", desc->contributors); @@ -432,7 +479,7 @@ print_toc_classes (FILE *f, if (!classes) return; - g_fprintf (f, "## <a name=\"%s.classes\"></a>Classes\n\n", id); + g_fprintf (f, "The following classes are defined:\n\n"); for (l = classes; l; l = l->next) { TrackerOntologyClass *klass; @@ -451,62 +498,65 @@ print_toc_classes (FILE *f, g_fprintf (f, "\n\n"); } -static void -print_toc_extra_properties (FILE *f, - TrackerOntologyModel *model, - const char *id, - GHashTable *extra_properties) +void +generate_devhelp_keywords (TrackerOntologyModel *model, + TrackerOntologyDescription *description, + GFile *output_location, + GList *classes, + GList *properties) { - GList *props_for_class, *c, *l; - g_autoptr(GList) classes = NULL; - gboolean print_comma = FALSE; - - if (g_hash_table_size (extra_properties) == 0) - return; + gchar *path, *filename; + GFile *file; + GList *l; + FILE *f; - g_fprintf (f, "## <a name=\"%s.extra_properties\"></a>Additional Properties\n", id); + filename = g_strdup_printf ("%s-ontology.keywords", description->localPrefix); + file = g_file_get_child (output_location, filename); + g_free (filename); - classes = g_hash_table_get_keys (extra_properties); - classes = g_list_sort (classes, (GCompareFunc)strcmp); - for (c = classes; c; c = c->next) { - gchar *classname; + path = g_file_get_path (file); + f = fopen (path, "w"); + g_assert (f != NULL); + g_free (path); - classname = c->data; - props_for_class = g_hash_table_lookup (extra_properties, classname); - for (l = props_for_class; l; l = l->next) { - TrackerOntologyProperty *prop; - const char *basename = NULL, *prop_id = NULL; + for (l = classes; l != NULL; l = l->next) { + TrackerOntologyClass *klass; - prop = tracker_ontology_model_get_property (model, l->data); - basename = prop->basename; - prop_id = prop->shortname; + klass = tracker_ontology_model_get_class (model, l->data); + g_fprintf (f, " <keyword type=\"rdf-class\" name=\"%s\" link=\"%s-ontology.html#%s\"/>\n", + klass->shortname, + description->localPrefix, + klass->shortname); + } - if (print_comma) { - g_fprintf (f, ", "); - } else { - print_comma = TRUE; - } + for (l = properties; l != NULL; l = l->next) { + TrackerOntologyProperty *prop; - g_fprintf (f, "[%s](#%s)", basename, prop_id); - } + prop = tracker_ontology_model_get_property (model, l->data); + g_fprintf (f, " <keyword type=\"rdf-property\" name=\"%s\" link=\"%s-ontology.html#%s\"/>\n", + prop->shortname, + description->localPrefix, + prop->shortname); } - g_fprintf (f, "\n\n"); + g_object_unref (file); + fclose (f); } void -generate_keywords (TrackerOntologyModel *model, - TrackerOntologyDescription *description, - GFile *output_location, - GList *classes, - GList *properties) +generate_search_terms (TrackerOntologyModel *model, + TrackerOntologyDescription *description, + GFile *output_location, + GList *classes, + GList *properties) { gchar *path, *filename; GFile *file; GList *l; FILE *f; + gboolean first = TRUE; - filename = g_strdup_printf ("%s-ontology.keywords", description->localPrefix); + filename = g_strdup_printf ("%s-ontology.index.json", description->localPrefix); file = g_file_get_child (output_location, filename); g_free (filename); @@ -515,26 +565,48 @@ generate_keywords (TrackerOntologyModel *model, g_assert (f != NULL); g_free (path); + g_fprintf (f, "{\"symbols\":["); + for (l = classes; l != NULL; l = l->next) { TrackerOntologyClass *klass; + g_autofree gchar *desc = NULL; + + if (!first) + g_fprintf (f, ","); klass = tracker_ontology_model_get_class (model, l->data); - g_fprintf (f, " <keyword type=\"rdf-class\" name=\"%s\" link=\"%s-ontology.html#%s\"/>\n", + if (klass->description) + desc = g_strescape (klass->description, NULL); + + g_fprintf (f, "{\"type\": \"content\", \"name\":\"%s\",\"href\":\"%s-ontology.html#%s\",\"summary\":\"%s\"}", klass->shortname, description->localPrefix, - klass->shortname); + klass->shortname, + desc ? desc : ""); + first = FALSE; } for (l = properties; l != NULL; l = l->next) { TrackerOntologyProperty *prop; + g_autofree gchar *desc = NULL; + + if (!first) + g_fprintf (f, ","); prop = tracker_ontology_model_get_property (model, l->data); - g_fprintf (f, " <keyword type=\"rdf-property\" name=\"%s\" link=\"%s-ontology.html#%s\"/>\n", + if (prop->description) + desc = g_strescape (prop->description, NULL); + + g_fprintf (f, "{\"type\": \"content\", \"name\":\"%s\",\"href\":\"%s-ontology.html#%s\",\"summary\":\"%s\"}", prop->shortname, description->localPrefix, - prop->shortname); + prop->shortname, + desc ? desc : ""); + first = FALSE; } + g_fprintf (f, "]}"); + g_object_unref (file); fclose (f); } @@ -554,7 +626,7 @@ ttl_md_print (TrackerOntologyDescription *description, GList *l; FILE *f; - filename = g_strdup_printf ("%s-ontology.md", description->localPrefix); + filename = g_strdup_printf ("%s-ontology.md.in", description->localPrefix); file = g_file_get_child (output_location, filename); g_free (filename); @@ -572,7 +644,6 @@ ttl_md_print (TrackerOntologyDescription *description, print_synopsis (f, description); print_toc_classes (f, model, description->localPrefix, classes); - print_toc_extra_properties (f, model, description->localPrefix, extra_properties); basename = g_strdup_printf ("%s-introduction.md", description->localPrefix); introduction = g_build_filename (description_dir, basename, NULL); @@ -589,7 +660,7 @@ ttl_md_print (TrackerOntologyDescription *description, } if (classes != NULL) { - g_fprintf (f, "## <a name=\"%s-classes\"></a>Class Details\n\n", description->localPrefix); + g_fprintf (f, "# <a name=\"%s-classes\"></a>Classes\n\n", description->localPrefix); for (l = classes; l; l = l->next) { TrackerOntologyClass *klass; @@ -600,8 +671,6 @@ ttl_md_print (TrackerOntologyDescription *description, } if (g_hash_table_size (extra_properties) > 0) { - g_fprintf (f, "## <a name=\"%s-extra-properties\"></a>Property Details\n\n", description->localPrefix); - extra_classes = g_hash_table_get_keys (extra_properties); extra_classes = g_list_sort (extra_classes, (GCompareFunc)strcmp); for (l = extra_classes; l; l = l->next) { @@ -619,7 +688,8 @@ ttl_md_print (TrackerOntologyDescription *description, print_md_footer (f, description); - generate_keywords (model, description, output_location, classes, properties); + generate_devhelp_keywords (model, description, output_location, classes, properties); + generate_search_terms (model, description, output_location, classes, properties); g_free (upper_name); g_free (introduction); diff --git a/docs/tools/tracker-docgen-xml.c b/docs/tools/tracker-docgen-xml.c deleted file mode 100644 index d39f8a86d..000000000 --- a/docs/tools/tracker-docgen-xml.c +++ /dev/null @@ -1,662 +0,0 @@ -/* - * Copyright (C) 2009, Nokia <ivan.frade@nokia.com> - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - * 02110-1301, USA. - */ - -#include <glib/gprintf.h> -#include <gio/gio.h> - -#include "tracker-docgen-xml.h" -#include "tracker-utils.h" - -typedef struct { - TrackerOntologyModel *model; - TrackerOntologyDescription *description; - FILE *output; -} CallbackInfo; - -static void -print_predefined_instances (FILE *f, - TrackerOntologyClass *klass, - TrackerOntologyModel *model) -{ - const gchar *id; - GList *l; - - if (!klass->instances) - return; - - id = klass->shortname; - - g_fprintf (f, "<refsect3 id='%s.predefined-instances'>", id); - g_fprintf (f, "<title>Predefined instances</title><para>"); - g_fprintf (f, "%s has the following predefined instances: ", klass->shortname); - g_fprintf (f, "<itemizedlist>\n"); - - for (l = klass->instances; l; l = l->next) { - g_fprintf (f, "<listitem><para>"); - g_fprintf (f, "<literal>%s</literal>", (gchar*) l->data); - g_fprintf (f, "</para></listitem>\n"); - } - - g_fprintf (f, "</itemizedlist></para></refsect3>\n"); -} - -static void -print_class_hierarchy (FILE *f, - TrackerOntologyClass *klass, - TrackerOntologyModel *model) -{ - GPtrArray *strings; - const gchar *id; - guint i; - - strings = class_get_parent_hierarchy_strings (klass, model); - - if (!strings) - return; - - id = klass->shortname; - - g_fprintf (f, "<refsect3 id='%s.hierarchy'>", id); - g_fprintf (f, "<title>Class hierarchy</title>"); - g_fprintf (f, "<screen>"); - - for (i = 0; i < strings->len; i++) { - HierarchyString *str = g_ptr_array_index (strings, i); - - if (str->class == klass) { - g_fprintf (f, " %s<emphasis><link linkend=\"%s\">%s</link></emphasis>%s\n", - str->before->str, - str->class->shortname, - str->link_label->str, - str->after->str); - } else { - g_fprintf (f, " %s<link linkend=\"%s\">%s</link>%s\n", - str->before->str, - str->class->shortname, - str->link_label->str, - str->after->str); - } - } - - g_fprintf (f, "</screen></refsect3>\n"); - g_ptr_array_unref (strings); -} - -static void -print_flag (FILE *f, - const gchar *flag_property_link, - const gchar *icon_name, - const gchar *flag_description) -{ - /* This must not contain any linebreaks, or gtkdoc-fixxrefs will not - * resolve the link. See https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/122 - */ - g_fprintf (f, "<link linkend=\"%s\">", flag_property_link); - g_fprintf (f, "<inlinemediaobject>"); - g_fprintf (f, "<imageobject><imagedata fileref=\"%s\" /></imageobject>", icon_name); - g_fprintf (f, "<alt>%s</alt>", flag_description); - g_fprintf (f, "</inlinemediaobject>"); - g_fprintf (f, "</link>"); -} - -static void -print_property_table (FILE *f, - TrackerOntologyModel *model, - const char *id, - GList *properties) -{ - GList *l, *m; - g_autoptr(GList) properties_sorted = NULL; - - if (!properties) - return; - - properties_sorted = g_list_sort (g_list_copy (properties), (GCompareFunc) strcmp); - - /* We (ab)use the "struct_members" role to ensure devhelp2 <keyword> entries are - * generated by gtkdoc-mkhtml2. This is needed for xrefs to work between the - * libtracker-sparql and nepomuk ontology docs. - */ - g_fprintf (f, "<refsect3 role=\"struct_members\" id=\"%s.properties\">", id); - g_fprintf (f, "<title>Properties</title>"); - - g_fprintf (f, "<informaltable frame=\"none\"><tgroup cols=\"4\">"); - g_fprintf (f, "<thead><row><entry>Name</entry><entry>Type</entry><entry>Notes</entry><entry>Description</entry></row></thead>"); - - g_fprintf (f, "<tbody>"); - for (l = properties_sorted; l; l = l->next) { - TrackerOntologyProperty *prop; - TrackerOntologyClass *range; - const gchar *shortname = NULL, *basename = NULL, *type_name = NULL, *type_class_id = NULL, *prop_id = NULL; - - prop = tracker_ontology_model_get_property (model, l->data); - range = tracker_ontology_model_get_class (model, prop->range->data); - - prop_id = shortname = prop->shortname; - basename = prop->basename; - type_name = range->basename; - type_class_id = range->shortname; - - g_fprintf (f, "<row role=\"member\">"); - - /* Property name column */ - g_fprintf (f, "<entry role=\"struct_member_name\">"); - /* This id is globally unique and can be used for internal links. - * We abuse <structfield> so that gtkdoc-mkhtml2 creates a usable link. */ - g_fprintf (f, "<para><structfield id=\"%s\">%s</structfield></para>", prop_id, basename); - /* This anchor is unique within the refentry and can be used for external links */ - g_fprintf (f, "<anchor id='%s' />", basename); - g_fprintf (f, "<indexterm zone='%s'><primary sortas='%s'>%s</primary></indexterm>", - prop_id, shortname, shortname); - g_fprintf (f, "</entry>"); - - /* Type column */ - g_fprintf (f, "<entry>"); - g_fprintf (f, "<link linkend=\"%s\">%s</link>", type_class_id, type_name); - g_fprintf (f, "</entry>"); - - /* Flags column */ - g_fprintf (f, "<entry>"); - - if (prop->deprecated) { - print_flag (f, "nrl-deprecated", "icon-deprecated.svg", - "This property is deprecated."); - } - - if (prop->superproperties) { - for (m = prop->superproperties; m; m = m->next) { - const gchar *shortname = NULL, *superprop_id = NULL; - g_autofree gchar *message = NULL; - TrackerOntologyProperty *superprop; - - superprop = tracker_ontology_model_get_property (model, m->data); - shortname = superprop_id = superprop->shortname; - - message = g_strdup_printf ("This property extends %s", shortname); - - print_flag (f, superprop_id, "icon-superproperty.svg", message); - } - } - - if (prop->max_cardinality != NULL && atoi (prop->max_cardinality) == 1) { - /* Single valued properties are most common, so we don't display this. */ - } else { - g_autofree gchar *message = NULL; - - if (prop->max_cardinality != NULL && atoi (prop->max_cardinality) > 0) { - message = g_strdup_printf ("This property can have a maximum of %i values", *prop->max_cardinality); - } else { - message = g_strdup_printf ("This property can have multiple values."); - } - print_flag (f, "nrl-maxCardinality", "icon-multivalue.svg", message); - } - - if (prop->fulltextIndexed) { - print_flag (f, "nrl-fulltextIndexed", "icon-fulltextindexed.svg", - "This property is full-text-indexed, and can be looked up through <literal>fts:match</literal>"); - } - - g_fprintf (f, "</entry>"); - - /* Description column */ - g_fprintf (f, "<entry>"); - if (prop->description) { - g_fprintf (f, "<para>%s</para>", prop->description); - } - g_fprintf (f, "</entry>"); - g_fprintf (f, "</row>"); - } - - g_fprintf (f, "</tbody></tgroup>"); - g_fprintf (f, "</informaltable>"); - - g_fprintf (f, "</refsect3>"); -} - -static void -print_ontology_class (TrackerOntologyModel *model, - TrackerOntologyClass *klass, - FILE *f) -{ - const gchar *name = NULL, *id = NULL; - - g_return_if_fail (f != NULL); - - name = klass->basename; - id = klass->shortname; - - /* Anchor for external links. */ - g_fprintf (f, "<anchor id='%s' />\n", name); - - g_fprintf (f, "<refsect2 role='rdf-class' id='%s'>\n", id); - g_fprintf (f, "<title>%s</title>\n", name); - - if (klass->description || klass->deprecated || klass->notify) { - g_fprintf (f, "<refsect3 id='%s.description'>\n", id); - g_fprintf (f, " <title>Description</title>\n"); - - if (klass->description) { - g_fprintf (f, " %s", klass->description); - } - - if (klass->deprecated) { - g_fprintf (f, "<para>"); - print_flag (f, "nrl-deprecated", "icon-deprecated.svg", "Deprecated icon"); - g_fprintf (f, "This class is deprecated."); - g_fprintf (f, "</para>"); - } - - if (klass->notify) { - g_fprintf (f, "<para>"); - print_flag (f, "nrl-notify", "icon-notify.svg", "Notify icon"); - g_fprintf (f, "This class emits notifications about changes, and can " - "be monitored using <link linkend=\"TrackerNotifier\">TrackerNotifier</link>."); - g_fprintf (f, "</para>"); - } - g_fprintf (f, "</refsect3>\n"); - } - - if (klass->specification) { - g_fprintf (f, "<refsect3 id='%s.specification'>\n", id); - g_fprintf (f, " <title>Specification</title>\n"); - g_fprintf (f, " <ulink url=\"%s\" />", klass->specification); - g_fprintf (f, "</refsect3>\n"); - } - - print_class_hierarchy (f, klass, model); - print_predefined_instances (f, klass, model); - - print_property_table (f, model, id, klass->in_domain_of); - - g_fprintf (f, "</refsect2>\n"); -} - -static void -print_ontology_extra_properties (TrackerOntologyModel *model, - const char *ontology_prefix, - const char *classname, - GList *properties_for_class, - FILE *f) -{ - TrackerOntologyClass *klass; - const gchar *short_classname = NULL, *class_id = NULL; - gchar *section_id = NULL; - - g_return_if_fail (f != NULL); - - klass = tracker_ontology_model_get_class (model, classname); - short_classname = class_id = klass->shortname; - section_id = g_strconcat (ontology_prefix, ".", class_id, NULL); - - g_fprintf (f, "<refsect2 role='rdf-property-list' id='%s'>\n", section_id); - g_fprintf (f, "<title>Additional properties for %s</title>\n", short_classname); - - g_fprintf (f, "<refsect3>\n"); - g_fprintf (f, " <title>Description</title>\n"); - g_fprintf (f, " <para>Properties this ontology defines which can describe %s resources.</para>", - short_classname); - g_fprintf (f, "</refsect3>\n"); - - print_property_table (f, model, section_id, properties_for_class); - g_fprintf (f, "</refsect2>\n"); - - g_free (section_id); -} - -static void -print_itemized_list (FILE *f, GList *list) -{ - GList *it; - - g_fprintf (f, "<itemizedlist>\n"); - for (it = list; it != NULL; it = it->next) { - g_fprintf (f, "<listitem>%s</listitem>\n", (gchar *)it->data); - } - g_fprintf (f, "</itemizedlist>\n"); -} - -static void -print_people_list (FILE *f, - const gchar *role, - GList *list) -{ - if (!list) { - return; - } - - g_fprintf (f, "<varlistentry>\n"); - g_fprintf (f, " <term>%s</term>\n", role); - g_fprintf (f, " <listitem>\n"); - print_itemized_list (f, list); - g_fprintf (f, " </listitem>\n"); - g_fprintf (f, "</varlistentry>\n"); -} - -static void -print_link_as_varlistentry (FILE *f, - const gchar *term, - const gchar *link_text, - const gchar *link) -{ - g_fprintf (f, " <varlistentry>\n"); - g_fprintf (f," <term>%s</term>\n", term); - if (link) { - g_fprintf (f, - " <listitem><para><ulink url=\"%s\">%s</ulink></para></listitem>\n", - link, link_text); - } else { - g_fprintf (f, " <listitem><para>Not available</para></listitem>\n"); - } - g_fprintf (f, " </varlistentry>\n"); -} - -#if 0 -static void -print_deprecated_message (FILE *f) -{ - g_fprintf (f, "<note>\n"); - g_fprintf (f, "<title>Note:</title>\n"); - g_fprintf (f, "<para>This item is deprecated</para>\n"); - g_fprintf (f, "</note>\n"); -} -#endif - -static void -print_xml_header (FILE *f, TrackerOntologyDescription *desc) -{ - g_fprintf (f, "<?xml version='1.0' encoding='UTF-8'?>\n"); - g_fprintf (f, "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.5//EN\"\n" - " \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" [\n"); - g_fprintf (f, "<!ENTITY %% local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n"); - g_fprintf (f, "]>"); - - g_fprintf (f, "<refentry id='%s' xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n", desc->localPrefix); - g_fprintf (f, "<refmeta>\n"); - g_fprintf (f, " <refentrytitle>%s</refentrytitle>\n", desc->title); - g_fprintf (f, "</refmeta>\n"); - g_fprintf (f, "<refnamediv>\n"); - g_fprintf (f, "<refname>%s</refname>", desc->title); - g_fprintf (f, "<refpurpose>%s</refpurpose>", desc->description); - g_fprintf (f, "</refnamediv>\n"); -} - -static void -print_xml_footer (FILE *f, TrackerOntologyDescription *desc) -{ - g_fprintf (f, "<refsect1>\n"); - g_fprintf (f, "<title>Credits and Copyright</title>\n"); - print_people_list (f, "Authors:", desc->authors); - print_people_list (f, "Editors:", desc->editors); - print_people_list (f, "Contributors:", desc->contributors); - - print_link_as_varlistentry (f, "Upstream:", "Upstream version", desc->upstream); - print_link_as_varlistentry (f, "ChangeLog:", "Tracker changes", desc->gitlog); - - if (desc->copyright) { - g_fprintf (f, "<varlistentry>\n"); - g_fprintf (f, " <term>Copyright:</term>\n"); - g_fprintf (f, " <listitem>\n"); - g_fprintf (f, "<para>%s</para>\n", desc->copyright); - g_fprintf (f, " </listitem>\n"); - g_fprintf (f, "</varlistentry>\n"); - } - - g_fprintf (f, "</refsect1>\n"); - g_fprintf (f, "</refentry>\n"); -} - -/* By default we list properties under their respective class. - * - * Ontologies can contain properties whose class is in a different - * ontology, and we treat these specially as 'extra properties'. - * - * This functions returns a hash table mapping class name to the - * extra properties provided for that class. - */ -static GHashTable * -get_extra_properties (TrackerOntologyModel *model, - GList *classes, - GList *properties) -{ - GList *l, *c; - GHashTable *extra_properties; - GHashTableIter iter; - gchar *classname; - GList *properties_for_class; - - extra_properties = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL); - - for (l = properties; l; l = l->next) { - TrackerOntologyProperty *prop; - gboolean has_domain_in_this_ontology = FALSE; - - prop = tracker_ontology_model_get_property (model, l->data); - - for (c = prop->domain; c; c = c->next) { - TrackerOntologyDescription *desc = NULL; - TrackerOntologyClass *klass; - gchar *prefix; - const gchar *sep; - - klass = tracker_ontology_model_get_class (model, c->data); - sep = strstr (klass->shortname, ":"); - - if (sep) { - prefix = g_strndup (klass->shortname, sep - klass->shortname); - desc = tracker_ontology_model_get_description (model, prefix); - g_free (prefix); - } - - has_domain_in_this_ontology = desc != NULL; - } - - if (!has_domain_in_this_ontology) { - for (c = prop->domain; c; c = c->next) { - const gchar *classname; - GList *list; - - classname = c->data; - list = g_hash_table_lookup (extra_properties, classname); - list = g_list_append (list, prop->propertyname); - g_hash_table_insert (extra_properties, g_strdup (classname), list); - } - } - } - - g_hash_table_iter_init (&iter, extra_properties); - while (g_hash_table_iter_next (&iter, (gpointer *)&classname, (gpointer *)&properties_for_class)) { - properties_for_class = g_list_sort (properties_for_class, (GCompareFunc) strcmp); - g_hash_table_iter_replace (&iter, properties_for_class); - } - - return extra_properties; -} - -static void -print_synopsis (FILE *f, - TrackerOntologyDescription *desc) -{ - g_fprintf (f, "<refsynopsisdiv>\n"); - g_fprintf (f, "<synopsis>\n"); - g_fprintf (f, "@prefix %s: <%s>\n", desc->localPrefix, desc->baseUrl); - g_fprintf (f, "</synopsis>\n"); - g_fprintf (f, "</refsynopsisdiv>\n"); -} - -static void -print_toc_classes (FILE *f, - TrackerOntologyModel *model, - const char *id, - GList *classes) -{ - GList *l; - - if (!classes) - return; - - g_fprintf (f, "<refsect1 id=\"%s.classes\">", id); - g_fprintf (f, "<title>Classes</title>"); - - for (l = classes; l; l = l->next) { - TrackerOntologyClass *klass; - const char *basename = NULL, *id = NULL; - - klass = tracker_ontology_model_get_class (model, l->data); - basename = klass->basename; - id = klass->shortname; - - if (l != classes) { - g_fprintf (f, ", "); - } - g_fprintf (f, "<link linkend=\"%s\">%s</link>", id, basename); - } - - g_fprintf (f, "</refsect1>"); -} - -static void -print_toc_extra_properties (FILE *f, - TrackerOntologyModel *model, - const char *id, - GHashTable *extra_properties) -{ - GList *props_for_class, *c, *l; - g_autoptr(GList) classes = NULL; - gboolean print_comma = FALSE; - - if (g_hash_table_size (extra_properties) == 0) - return; - - g_fprintf (f, "<refsect1 id=\"%s.extra_properties\">", id); - g_fprintf (f, "<title>Additional Properties</title>"); - - classes = g_hash_table_get_keys (extra_properties); - classes = g_list_sort (classes, (GCompareFunc)strcmp); - for (c = classes; c; c = c->next) { - gchar *classname; - - classname = c->data; - props_for_class = g_hash_table_lookup (extra_properties, classname); - for (l = props_for_class; l; l = l->next) { - TrackerOntologyProperty *prop; - const char *basename = NULL, *prop_id = NULL; - - prop = tracker_ontology_model_get_property (model, l->data); - basename = prop->basename; - prop_id = prop->shortname; - - if (print_comma) { - g_fprintf (f, ", "); - } else { - print_comma = TRUE; - } - - g_fprintf (f, "<link linkend=\"%s\">%s</link>", prop_id, basename); - } - } - - g_fprintf (f, "</refsect1>"); -} - -/* Generate docbook XML document for one ontology. */ -void -ttl_xml_print (TrackerOntologyDescription *description, - TrackerOntologyModel *model, - const gchar *prefix, - GFile *output_location, - const gchar *description_dir) -{ - gchar *upper_name, *path, *introduction, *basename, *filename; - g_autoptr(GList) classes = NULL, properties = NULL, extra_classes = NULL; - g_autoptr(GHashTable) extra_properties = NULL; - GFile *file; - GList *l; - FILE *f; - - filename = g_strdup_printf ("%s-ontology.xml", description->localPrefix); - file = g_file_get_child (output_location, filename); - g_free (filename); - - path = g_file_get_path (file); - f = fopen (path, "w"); - g_assert (f != NULL); - g_free (path); - - upper_name = g_ascii_strup (description->localPrefix, -1); - classes = tracker_ontology_model_list_classes (model, prefix); - properties = tracker_ontology_model_list_properties (model, prefix); - extra_properties = get_extra_properties (model, classes, properties); - - print_xml_header (f, description); - - print_synopsis (f, description); - print_toc_classes (f, model, description->localPrefix, classes); - print_toc_extra_properties (f, model, description->localPrefix, extra_properties); - - basename = g_strdup_printf ("%s-introduction.xml", description->localPrefix); - introduction = g_build_filename (description_dir, basename, NULL); - g_free (basename); - - if (g_file_test (introduction, G_FILE_TEST_EXISTS)) { - g_fprintf (f, "<xi:include href='%s'><xi:fallback/></xi:include>", - introduction); - } - - if (classes != NULL) { - g_fprintf (f, "<refsect1 id='%s-classes'>\n", description->localPrefix); - g_fprintf (f, "<title>Class Details</title>\n"); - - for (l = classes; l; l = l->next) { - TrackerOntologyClass *klass; - - klass = tracker_ontology_model_get_class (model, l->data); - print_ontology_class (model, klass, f); - } - - g_fprintf (f, "</refsect1>\n"); - } - - if (g_hash_table_size (extra_properties) > 0) { - g_fprintf (f, "<refsect1 id='%s-extra-properties'>\n", description->localPrefix); - g_fprintf (f, "<title>Property Details</title>\n"); - - extra_classes = g_hash_table_get_keys (extra_properties); - extra_classes = g_list_sort (extra_classes, (GCompareFunc)strcmp); - for (l = extra_classes; l; l = l->next) { - gchar *classname; - GList *properties_for_class; - - classname = l->data; - - properties_for_class = g_hash_table_lookup (extra_properties, classname); - if (properties_for_class) { - print_ontology_extra_properties (model, description->localPrefix, classname, properties_for_class, f); - } - } - - g_fprintf (f, "</refsect1>\n"); - } - - print_xml_footer (f, description); - - g_free (upper_name); - g_free (introduction); - g_object_unref (file); - fclose (f); -} diff --git a/docs/tools/tracker-docgen-xml.h b/docs/tools/tracker-docgen-xml.h deleted file mode 100644 index 840182bb8..000000000 --- a/docs/tools/tracker-docgen-xml.h +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright (C) 2009, Nokia <ivan.frade@nokia.com> - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - * 02110-1301, USA. - */ - -#ifndef __TTL_XML_H__ -#define __TTL_XML_H__ - -#include <gio/gio.h> -#include "tracker-ontology-model.h" - -G_BEGIN_DECLS - -void ttl_xml_print (TrackerOntologyDescription *description, - TrackerOntologyModel *model, - const gchar *prefix, - GFile *output_location, - const gchar *description_dir); - -G_END_DECLS - -#endif diff --git a/docs/tools/tracker-main.c b/docs/tools/tracker-main.c index 863b2ab2d..f695610a1 100644 --- a/docs/tools/tracker-main.c +++ b/docs/tools/tracker-main.c @@ -23,15 +23,14 @@ #include <stdio.h> #include "tracker-docgen-md.h" -#include "tracker-docgen-xml.h" #include "tracker-ontology-model.h" +#include "tracker-utils.h" static gchar *ontology_dir = NULL; static gchar *ontology_desc_dir = NULL; static gchar *output_dir = NULL; static gchar *introduction_dir = NULL; -static gboolean xml = FALSE; -static gboolean markdown = FALSE; +static gboolean markdown = TRUE; static GOptionEntry entries[] = { { "ontology-dir", 'd', 0, G_OPTION_ARG_FILENAME, &ontology_dir, @@ -50,10 +49,6 @@ static GOptionEntry entries[] = { "Directory to find ontology introduction", NULL }, - { "xml", 'x', 0, G_OPTION_ARG_NONE, &xml, - "Whether to produce docbook XML for gtk-doc", - NULL - }, { "md", 'm', 0, G_OPTION_ARG_NONE, &markdown, "Whether to produce markdown", NULL @@ -86,12 +81,6 @@ main (gint argc, gchar **argv) return -1; } - if (!!xml == !!markdown) { - g_printerr ("%s\n", - "One of --xml or --md must be provided"); - return -1; - } - if (!ontology_dir || !output_dir) { gchar *help; @@ -131,10 +120,10 @@ main (gint argc, gchar **argv) if (!description) continue; - if (xml) - ttl_xml_print (description, model, prefixes[i], output_file, introduction_dir); - else if (markdown) + if (markdown) ttl_md_print (description, model, prefixes[i], output_file, introduction_dir); + + ttl_generate_dot_files (description, model, prefixes[i], output_file); } g_strfreev (prefixes); diff --git a/docs/tools/tracker-utils.c b/docs/tools/tracker-utils.c index 498ff4a4a..7a70f3331 100644 --- a/docs/tools/tracker-utils.c +++ b/docs/tools/tracker-utils.c @@ -26,373 +26,215 @@ #include "tracker-utils.h" -enum { - INSERT_BEFORE, - INSERT_AFTER -}; - -static void -class_get_parent_hierarchy (TrackerOntologyModel *model, - const gchar *class_name, - GList **list) -{ - TrackerOntologyClass *klass; - GList *l, *elem; - - /* Ensure we only got the same class there once */ - elem = g_list_find_custom (*list, class_name, - (GCompareFunc) g_strcmp0); - if (elem) - *list = g_list_delete_link (*list, elem); - *list = g_list_prepend (*list, (gpointer) class_name); - - klass = tracker_ontology_model_get_class (model, class_name); - if (!klass) - return; - - - for (l = klass->superclasses; l; l = l->next) { - class_get_parent_hierarchy (model, l->data, list); - } -} - -static GList * -class_get_hierarchy (TrackerOntologyModel *model, - TrackerOntologyClass *klass) +static gchar * +link_from_shortname (const gchar *shortname) { - GList *hierarchy = NULL, *l; + const gchar *sep; + gchar *link, *prefix; - /* Order is: parents, this class, and children. Guaranteed - * to be in an order where all parents are before a child. - * We first prepend all children, and then find out the - * upwards hierarchy recursively. - */ - for (l = klass->subclasses; l; l = l->next) { - hierarchy = g_list_prepend (hierarchy, l->data); - } + sep = strstr (shortname, ":"); + g_assert (sep != NULL); - class_get_parent_hierarchy (model, klass->classname, &hierarchy); + prefix = g_strndup (shortname, sep - shortname); + link = g_strdup_printf ("%s-ontology.html#%s", prefix, shortname); + g_free (prefix); - return hierarchy; + return link; } -typedef struct { - TrackerOntologyClass *class; - GList *hierarchy; - GHashTable *resolved_children; - GHashTable *resolved_parents; - GHashTable *placed; - GPtrArray *strings; -} HierarchyContext; - -static HierarchyString * -hierarchy_string_new (void) +static void +describe_class (FILE *f, + TrackerOntologyModel *model, + TrackerOntologyClass *klass, + gboolean link) { - HierarchyString *str; + g_fprintf (f, "node [shape=\"box\", style=\"rounded\", border=\"0\", fontname=\"sans-serif\""); - str = g_new0 (HierarchyString, 1); - str->before = g_string_new (""); - str->after = g_string_new (""); - str->link_label = g_string_new (""); + if (link) { + g_autofree gchar *link = NULL; - return str; -} + link = link_from_shortname (klass->shortname); + g_fprintf (f, ", class=\"link\", href=\"%s\"", link); + } -static void -hierarchy_string_free (HierarchyString *str) -{ - g_string_free (str->before, TRUE); - g_string_free (str->after, TRUE); - g_string_free (str->link_label, TRUE); - g_free (str); + g_fprintf (f, "]; \"%s\"\n", klass->shortname); } static void -hierarchy_string_append (HierarchyString *str, - int pos, - const gchar *substr) +print_superclasses (FILE *f, + TrackerOntologyModel *model, + TrackerOntologyClass *klass, + GHashTable *visited, + gboolean link) { - if (pos == INSERT_BEFORE) - g_string_append (str->before, substr); - else - g_string_append (str->after, substr); - - str->visible_len += g_utf8_strlen (substr, -1); -} + GList *l; -static void -hierarchy_string_append_link (HierarchyString *str, - TrackerOntologyClass *klass) -{ - g_string_append (str->link_label, klass->shortname); - str->class = klass; - str->visible_len += g_utf8_strlen (klass->shortname, -1); -} + if (g_hash_table_contains (visited, klass)) + return; -static GList * -list_filter (GList *original, - GList *valid) -{ - GList *l, *filtered = NULL; + describe_class (f, model, klass, link); - for (l = original; l; l = l->next) { - if (!g_list_find_custom (valid, l->data, - (GCompareFunc) g_strcmp0)) - continue; + for (l = klass->superclasses; l; l = l->next) { + TrackerOntologyClass *superclass; - filtered = g_list_prepend (filtered, l->data); + superclass = tracker_ontology_model_get_class (model, l->data); + print_superclasses (f, model, superclass, visited, TRUE); + g_fprintf (f, "\"%s\" -- \"%s\"\n", superclass->shortname, klass->shortname); } - return filtered; + g_hash_table_add (visited, klass); } -static HierarchyContext * -hierarchy_context_new (TrackerOntologyClass *klass, - TrackerOntologyModel *model) +static void +ttl_generate_class_hierarchy_dot (TrackerOntologyDescription *description, + TrackerOntologyModel *model, + TrackerOntologyClass *klass, + GFile *output_location) { - HierarchyContext *context; + gchar *path, *filename; + GFile *file; + g_autoptr(GHashTable) visited = NULL; + FILE *f; GList *l; - context = g_new0 (HierarchyContext, 1); - context->class = klass; - context->hierarchy = class_get_hierarchy (model, klass); - context->placed = g_hash_table_new (g_str_hash, g_str_equal); - context->resolved_parents = g_hash_table_new_full (g_str_hash, - g_str_equal, - NULL, - (GDestroyNotify) g_list_free); - context->resolved_children = g_hash_table_new_full (g_str_hash, - g_str_equal, - NULL, - (GDestroyNotify) g_list_free); - context->strings = g_ptr_array_new_with_free_func ((GDestroyNotify) hierarchy_string_free); - - for (l = context->hierarchy; l; l = l->next) { - TrackerOntologyClass *cl = tracker_ontology_model_get_class (model, l->data); - - g_hash_table_insert (context->resolved_parents, - cl->classname, - list_filter (cl->superclasses, - context->hierarchy)); - g_hash_table_insert (context->resolved_children, - cl->classname, - list_filter (cl->subclasses, - context->hierarchy)); - - g_ptr_array_add (context->strings, hierarchy_string_new ()); - } + if (!klass->subclasses && !klass->superclasses) + return; - return context; -} + filename = g_strdup_printf ("%s-hierarchy.dot", klass->shortname); + file = g_file_get_child (output_location, filename); + g_free (filename); -static void -hierarchy_context_free (HierarchyContext *context) -{ - g_list_free (context->hierarchy); - g_ptr_array_unref (context->strings); - g_hash_table_unref (context->placed); - g_hash_table_unref (context->resolved_parents); - g_hash_table_unref (context->resolved_children); - g_free (context); -} + path = g_file_get_path (file); + f = fopen (path, "w"); + g_assert (f != NULL); + g_free (path); -static GList * -hierarchy_context_get_single_parented_children (HierarchyContext *context, - TrackerOntologyClass *klass, - TrackerOntologyModel *model) -{ - GList *filtered = NULL, *children, *l; + g_fprintf (f, "graph G {\n"); + g_fprintf (f, "bgcolor=\"transparent\";\n"); + g_fprintf (f, "rankdir=TB;\n"); - children = g_hash_table_lookup (context->resolved_children, - klass->classname); + visited = g_hash_table_new (NULL, NULL); - for (l = children; l; l = l->next) { - GList *parents; + print_superclasses (f, model, klass, visited, FALSE); - parents = g_hash_table_lookup (context->resolved_parents, l->data); + for (l = klass->subclasses; l; l = l->next) { + TrackerOntologyClass *subclass; - if (g_list_length (parents) == 1) - filtered = g_list_prepend (filtered, l->data); + subclass = tracker_ontology_model_get_class (model, l->data); + describe_class (f, model, subclass, TRUE); + g_fprintf (f, "\"%s\" -- \"%s\"\n", klass->shortname, subclass->shortname); } - return filtered; + g_fprintf (f, "}"); + + g_object_unref (file); + fclose (f); } static void -fill_padding (HierarchyString *str, - gint pos, - gint max_len, - gchar *substr) +ttl_generate_rdf_diagram_dot (TrackerOntologyDescription *description, + TrackerOntologyModel *model, + TrackerOntologyClass *klass, + GFile *output_location) { - gint padding = max_len - str->visible_len; + gchar *path, *filename; + GFile *file; + g_autoptr(GHashTable) visited = NULL; + g_autofree gchar *link = NULL; + FILE *f; + GList *l; - if (padding <= 0) + if (!klass->subclasses && !klass->superclasses) return; - while (padding > 0) { - hierarchy_string_append (str, pos, substr); - padding--; - } -} - -static gboolean -check_parents_placed (GList *parents, - GHashTable *ht) -{ - GList *l; + filename = g_strdup_printf ("%s-diagram.dot", klass->shortname); + file = g_file_get_child (output_location, filename); + g_free (filename); - for (l = parents; l; l = l->next) { - if (!g_hash_table_lookup (ht, l->data)) - return FALSE; - } + path = g_file_get_path (file); + f = fopen (path, "w"); + g_assert (f != NULL); + g_free (path); - return TRUE; -} + g_fprintf (f, "digraph G {\n"); + g_fprintf (f, "bgcolor=\"transparent\";\n"); + g_fprintf (f, "rankdir=LR;\n"); -static void -hierarchy_context_resolve_class (HierarchyContext *context, - TrackerOntologyClass *klass, - TrackerOntologyModel *model) -{ - GList *l = g_list_find_custom (context->hierarchy, klass->classname, - (GCompareFunc) g_strcmp0); - gint pos = g_list_position (context->hierarchy, l); - GList *children, *parents; - HierarchyString *str; - gboolean is_child; - - if (pos < 0) - return; + visited = g_hash_table_new (NULL, NULL); + describe_class (f, model, klass, FALSE); - parents = g_hash_table_lookup (context->resolved_parents, - klass->classname); + for (l = klass->in_domain_of; l; l = l->next) { + TrackerOntologyProperty *prop; + TrackerOntologyClass *range; - if (g_list_length (parents) > 1) { - gboolean first_pending = TRUE; - gint i, max_len = 0; + prop = tracker_ontology_model_get_property (model, l->data); + range = tracker_ontology_model_get_class (model, prop->range->data); - /* This class has more than one parent in the current graph, - * those paint the lines on the right side. - */ + if (g_hash_table_contains (visited, prop)) + continue; - /* Step 1: Find the longest string */ - first_pending = TRUE; - for (i = 0, l = context->hierarchy; i < pos && l; i++, l = l->next) { - is_child = g_list_find_custom (klass->superclasses, l->data, - (GCompareFunc) g_strcmp0) != NULL; - if (!is_child && first_pending) - continue; + if (g_str_has_prefix (range->shortname, "xsd:") || + g_str_equal (range->shortname, "rdfs:Literal") || + g_str_equal (range->shortname, "rdf:langString")) + continue; - str = g_ptr_array_index (context->strings, i); - max_len = MAX (max_len, str->visible_len); + if (!g_hash_table_contains (visited, range)) { + describe_class (f, model, range, TRUE); + g_hash_table_add (visited, range); } - /* Step 2: append the line art, we must fill in some padding if - * necessary. - */ - first_pending = TRUE; - for (i = 0, l = context->hierarchy; i < pos && l; i++, l = l->next) { - is_child = g_list_find_custom (klass->superclasses, l->data, - (GCompareFunc) g_strcmp0) != NULL; - - if (!is_child && first_pending) - continue; - - str = g_ptr_array_index (context->strings, i); - - fill_padding (str, INSERT_AFTER, max_len, is_child ? "─" : " "); - - if (first_pending) { - hierarchy_string_append (str, INSERT_AFTER, "──┐"); - first_pending = FALSE; - } else if (is_child) { - hierarchy_string_append (str, INSERT_AFTER, "──┤"); - } else { - hierarchy_string_append (str, INSERT_AFTER, " │"); - } - } + link = link_from_shortname (prop->shortname); + g_fprintf (f, "\"%s\" -> \"%s\" [label=\"%s\", fontname=\"sans-serif\", fontsize=10, href=\"%s\"]\n", + klass->shortname, range->shortname, prop->shortname, + link); + g_hash_table_add (visited, prop); + } + + for (l = klass->in_range_of; l; l = l->next) { + TrackerOntologyProperty *prop; + TrackerOntologyClass *domain; - /* Step 3: Finally, print the current class */ - str = g_ptr_array_index (context->strings, pos); - fill_padding (str, INSERT_BEFORE, max_len - 1, " "); - - hierarchy_string_append (str, INSERT_BEFORE, " └── "); - hierarchy_string_append_link (str, klass); - hierarchy_string_append (str, INSERT_AFTER, " "); - } else { - /* The current class has only 1 parent, lineart for those is - * displayed on the left side. - */ - - /* Step 1: Print the current class */ - str = g_ptr_array_index (context->strings, pos); - hierarchy_string_append_link (str, klass); - hierarchy_string_append (str, INSERT_AFTER, " "); - - /* Step 2: Modify all strings downwards, adding the lineart - * necessary for all children of this class. - */ - children = hierarchy_context_get_single_parented_children (context, klass, model); - l = l->next; - pos++; - - for (; l; l = l->next, pos++) { - guint len = g_list_length (children); - GList *cur; - - str = g_ptr_array_index (context->strings, pos); - cur = g_list_find_custom (children, l->data, - (GCompareFunc) g_strcmp0); - is_child = (cur != NULL); - - if (is_child) { - if (len > 1) - hierarchy_string_append (str, INSERT_BEFORE, "├── "); - else if (len == 1) - hierarchy_string_append (str, INSERT_BEFORE, "╰── "); - - children = g_list_delete_link (children, cur); - g_hash_table_insert (context->placed, - l->data, GINT_TO_POINTER (TRUE)); - } else { - if (len > 0) - hierarchy_string_append (str, INSERT_BEFORE, "│ "); - else if (len == 0 && - !g_hash_table_lookup (context->placed, l->data)) { - GList *cl_parents; - - cl_parents = g_hash_table_lookup (context->resolved_parents, l->data); - - if (g_list_length (cl_parents) == 1 || - !check_parents_placed (cl_parents, context->placed)) { - hierarchy_string_append (str, INSERT_BEFORE, " "); - } - } - } + prop = tracker_ontology_model_get_property (model, l->data); + domain = tracker_ontology_model_get_class (model, prop->domain->data); + + if (g_hash_table_contains (visited, prop)) + continue; + + if (!g_hash_table_contains (visited, domain)) { + describe_class (f, model, domain, TRUE); + g_hash_table_add (visited, domain); } + + link = link_from_shortname (prop->shortname); + g_fprintf (f, "\"%s\" -> \"%s\" [label=\"%s\", fontname=\"sans-serif\", fontsize=10, href=\"%s\"]\n", + domain->shortname, klass->shortname, prop->shortname, + link); + g_hash_table_add (visited, prop); } + + g_fprintf (f, "}"); + + g_object_unref (file); + fclose (f); } -GPtrArray * -class_get_parent_hierarchy_strings (TrackerOntologyClass *klass, - TrackerOntologyModel *model) +void +ttl_generate_dot_files (TrackerOntologyDescription *description, + TrackerOntologyModel *model, + const gchar *prefix, + GFile *output_location) { - HierarchyContext *context; - GList *c; - GPtrArray *strings = NULL; - - context = hierarchy_context_new (klass, model); - - /* Proceed from parent to child classes, populating the - * context->strings array. - */ - for (c = context->hierarchy; c; c = c->next) { - TrackerOntologyClass *cl = tracker_ontology_model_get_class (model, c->data); - hierarchy_context_resolve_class (context, cl, model); - } + g_autoptr(GList) classes = NULL; + GList *l; - strings = g_ptr_array_ref (context->strings); - hierarchy_context_free (context); + classes = tracker_ontology_model_list_classes (model, prefix); - return strings; + for (l = classes; l; l = l->next) { + TrackerOntologyClass *klass; + + klass = tracker_ontology_model_get_class (model, l->data); + + ttl_generate_class_hierarchy_dot (description, model, klass, output_location); + ttl_generate_rdf_diagram_dot (description, model, klass, output_location); + } } diff --git a/docs/tools/tracker-utils.h b/docs/tools/tracker-utils.h index 8a9eb2c17..f2e8e00e9 100644 --- a/docs/tools/tracker-utils.h +++ b/docs/tools/tracker-utils.h @@ -39,6 +39,11 @@ GPtrArray * class_get_parent_hierarchy_strings (TrackerOntologyClass *klass, TrackerOntologyModel *model); +void ttl_generate_dot_files (TrackerOntologyDescription *description, + TrackerOntologyModel *model, + const gchar *prefix, + GFile *output_location); + G_END_DECLS #endif /* TRACKER_UTILS_H */ diff --git a/docs/website/build.py b/docs/website/build.py index e903dcd38..b175f7bdb 100755 --- a/docs/website/build.py +++ b/docs/website/build.py @@ -58,42 +58,6 @@ def argument_parser(): return parser -def apidocs_header(tracker_commit): - return f"""<!-- Inserted by {__file__} --> - <div class="warning"> - <p>This is a documentation preview for the next version of Tracker, - generated from <a href="https://gitlab.gnome.org/GNOME/tracker/commit/{tracker_commit}/">tracker.git commit {tracker_commit[:7]}</a>.</p> - <p>See the <a href="https://gnome.pages.gitlab.gnome.org/tracker/docs/developer/">Tracker website</a> for more documentation.</p> - </div>""" - - -def add_apidocs_header(text, filename): - """Add a header to the documentation preview files.""" - - # We insert the header before any of these - markers = [ - '<div class="book">', - '<div class="chapter">', - '<div class="index">', - '<div class="glossary">', - '<div class="part">', - '<div class="refentry">', - '<div class="section">', - ] - - wrote_marker = False - - with open(filename, encoding='utf8') as f_in: - with tempfile.NamedTemporaryFile(delete=False, mode='w', encoding='utf8') as f_out: - for line in f_in: - for marker in markers: - if not wrote_marker and line.find(marker) != -1: - f_out.write(text) - wrote_marker = True - f_out.write(line) - shutil.move(f_out.name, filename) - - class Manpages(): def run(self, command): command = [str(c) for c in command] @@ -202,11 +166,6 @@ def main(): log.info(" - Copying %s to %s (%i files)", src, dest, len(list(src.iterdir()))) shutil.copytree(src, dest) - log.info("Adding preview header to API reference documentation") - text = apidocs_header(args.tracker_commit) - for filename in apidocs_dest.rglob('*.html'): - add_apidocs_header(text, filename) - log.info("Documentation available in %s/ directory.", args.output) diff --git a/examples/python/meson.build b/examples/python/meson.build index 47bac5af0..65e329d2c 100644 --- a/examples/python/meson.build +++ b/examples/python/meson.build @@ -17,7 +17,7 @@ examples = [ foreach example_name: examples file = meson.current_source_dir() / '@0@.py'.format(example_name) test(example_name, python, - args: sandbox_python_args + [python.path(), file], + args: sandbox_python_args + [python.full_path(), file], env: env, suite: 'examples') endforeach diff --git a/meson.build b/meson.build index 48fd039ad..8374cbbf6 100644 --- a/meson.build +++ b/meson.build @@ -1,6 +1,6 @@ project('tracker', 'c', version: '3.5.0.beta', - meson_version: '>=0.53', + meson_version: '>=0.55', default_options: [ 'c_std=c99', 'warning_level=2']) @@ -291,9 +291,7 @@ conf = configuration_data() # Config that goes in config.h -conf.set('HAVE_LIBICU', unicode_library_name == 'icu') conf.set('HAVE_LIBSTEMMER', have_libstemmer) -conf.set('HAVE_LIBUNISTRING', unicode_library_name == 'unistring') conf.set('HAVE_STATVFS64', cc.has_header_symbol('sys/statvfs.h', 'statvfs64', args: '-D_LARGEFILE64_SOURCE')) @@ -1,14 +1,14 @@ # Bulgarian translation of tracker po-file. # Copyright (C) 2015 Free Software Foundation, Inc. -# Copyright (C) 2022 Alexander Shopov <ash@kambanaria.org>. +# Copyright (C) 2022, 2023 Alexander Shopov <ash@kambanaria.org>. # This file is distributed under the same license as the tracer package. -# Alexander Shopov <ash@kambanaria.org>, 2015, 2022. +# Alexander Shopov <ash@kambanaria.org>, 2015, 2022, 2023. msgid "" msgstr "" "Project-Id-Version: tracker master\n" "Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/tracker/issues\n" -"POT-Creation-Date: 2022-10-01 08:05+0000\n" -"PO-Revision-Date: 2022-10-02 16:07+0200\n" +"POT-Creation-Date: 2023-02-13 21:09+0000\n" +"PO-Revision-Date: 2023-03-05 09:31+0200\n" "Last-Translator: Alexander Shopov <ash@kambanaria.org>\n" "Language-Team: Bulgarian <dict@fsa-bg.org>\n" "Language: bg\n" @@ -32,12 +32,12 @@ msgid "Version" msgstr "Версия" #: src/portal/tracker-main.c:110 src/tracker/tracker-endpoint.c:387 -#: src/tracker/tracker-export.c:509 src/tracker/tracker-import.c:196 +#: src/tracker/tracker-export.c:543 src/tracker/tracker-import.c:196 #: src/tracker/tracker-sparql.c:1566 src/tracker/tracker-sql.c:239 msgid "Unrecognized options" msgstr "Непознати опции" -#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:48 +#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:49 #: src/tracker/tracker-import.c:46 src/tracker/tracker-sparql.c:110 #: src/tracker/tracker-sql.c:44 msgid "Location of the database" @@ -142,61 +142,74 @@ msgstr "" "Създадена е нова база от данни. Ползвайте опцията „--dbus-service“, за да я " "споделите по шина за съобщения." -#: src/tracker/tracker-export.c:49 src/tracker/tracker-import.c:47 +#: src/tracker/tracker-export.c:50 src/tracker/tracker-import.c:47 #: src/tracker/tracker-import.c:62 src/tracker/tracker-import.c:63 #: src/tracker/tracker-sparql.c:111 src/tracker/tracker-sparql.c:123 #: src/tracker/tracker-sql.c:45 src/tracker/tracker-sql.c:49 msgid "FILE" msgstr "ФАЙЛ" -#: src/tracker/tracker-export.c:52 src/tracker/tracker-import.c:50 +#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:50 #: src/tracker/tracker-sparql.c:114 msgid "Connects to a DBus service" msgstr "Свързване към услуга за DBus" -#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:51 +#: src/tracker/tracker-export.c:54 src/tracker/tracker-import.c:51 #: src/tracker/tracker-sparql.c:115 msgid "DBus service name" msgstr "Име на услуга за DBus" -#: src/tracker/tracker-export.c:56 src/tracker/tracker-import.c:54 +#: src/tracker/tracker-export.c:57 +msgid "Output results format: “turtle”, “trig” or “json-ld”" +msgstr "Формат на изхода с резултати: „turtle“, „trig“ или „json-ld“" + +#: src/tracker/tracker-export.c:58 +msgid "RDF_FORMAT" +msgstr "ФОРМАТ_ЗА_RDF" + +#: src/tracker/tracker-export.c:61 src/tracker/tracker-import.c:54 #: src/tracker/tracker-sparql.c:118 msgid "Connects to a remote service" msgstr "Свързване към отдалечена услуга" -#: src/tracker/tracker-export.c:57 src/tracker/tracker-import.c:55 +#: src/tracker/tracker-export.c:62 src/tracker/tracker-import.c:55 #: src/tracker/tracker-sparql.c:119 msgid "Remote service URI" msgstr "Адрес на отдалечената услуга" -#: src/tracker/tracker-export.c:60 +#: src/tracker/tracker-export.c:65 msgid "Output TriG format which includes named graph information" msgstr "Извеждане във формат TriG, който съдържа информация от именовани гра̀фи" -#: src/tracker/tracker-export.c:72 src/tracker/tracker-export.c:73 +#: src/tracker/tracker-export.c:77 src/tracker/tracker-export.c:78 msgid "IRI" msgstr "IRI (интернационализиран идентификатор на ресурс)" #. TRANSLATORS: Those are commandline arguments -#: src/tracker/tracker-export.c:98 src/tracker/tracker-import.c:88 +#: src/tracker/tracker-export.c:103 src/tracker/tracker-import.c:88 #: src/tracker/tracker-sparql.c:199 msgid "Specify one “--database”, “--dbus-service” or “--remote-service” option" msgstr "" "Укажете точно една от опциите „--database“, „--dbus-service“ или „--remote-" "service“" -#: src/tracker/tracker-export.c:305 src/tracker/tracker-export.c:325 +#: src/tracker/tracker-export.c:310 src/tracker/tracker-export.c:331 #: src/tracker/tracker-import.c:125 src/tracker/tracker-sparql.c:1124 msgid "No error given" msgstr "Не е дадена грешка" -#: src/tracker/tracker-export.c:324 src/tracker/tracker-import.c:124 +#: src/tracker/tracker-export.c:330 src/tracker/tracker-import.c:124 #: src/tracker/tracker-sparql.c:1123 msgid "Could not establish a connection to Tracker" msgstr "Не може да се установи връзка с основния процес на индексирането" -#: src/tracker/tracker-export.c:391 src/tracker/tracker-export.c:404 -#: src/tracker/tracker-export.c:414 src/tracker/tracker-sparql.c:1502 +#: src/tracker/tracker-export.c:373 +#, c-format +msgid "Unsupported serialization format “%s”\n" +msgstr "Неподдържан формат за сериализация „%s“\n" + +#: src/tracker/tracker-export.c:425 src/tracker/tracker-export.c:438 +#: src/tracker/tracker-export.c:448 src/tracker/tracker-sparql.c:1502 #: src/tracker/tracker-sql.c:137 src/tracker/tracker-sql.c:170 msgid "Could not run query" msgstr "Заявката не може да се изпълни" @@ -2,14 +2,14 @@ # Copyright(C) 2007 THE tracker'S COPYRIGHT HOLDER # This file is distributed under the same license as the tracker package. # Namhyung Kim <namhyung@gmail.com>, 2007. -# Seong-ho Cho <shcho@gnome.org>, 2013-2022. +# Seong-ho Cho <shcho@gnome.org>, 2013-2023. # msgid "" msgstr "" -"Project-Id-Version: tracker\n" +"Project-Id-Version: tracker master\n" "Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/tracker/issues\n" -"POT-Creation-Date: 2022-07-12 10:59+0000\n" -"PO-Revision-Date: 2022-08-28 20:29+0900\n" +"POT-Creation-Date: 2023-02-13 21:09+0000\n" +"PO-Revision-Date: 2023-03-03 02:22+0900\n" "Last-Translator: Seong-ho Cho <shcho@gnome.org>\n" "Language-Team: Gnome Korea <gnome-kr@googlegroups.com>\n" "Language: ko\n" @@ -34,13 +34,13 @@ msgstr "the|a|an" msgid "Version" msgstr "버전" -#: src/portal/tracker-main.c:109 src/tracker/tracker-endpoint.c:387 -#: src/tracker/tracker-export.c:509 src/tracker/tracker-import.c:196 +#: src/portal/tracker-main.c:110 src/tracker/tracker-endpoint.c:387 +#: src/tracker/tracker-export.c:543 src/tracker/tracker-import.c:196 #: src/tracker/tracker-sparql.c:1566 src/tracker/tracker-sql.c:239 msgid "Unrecognized options" msgstr "인식할 수 없는 옵션" -#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:48 +#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:49 #: src/tracker/tracker-import.c:46 src/tracker/tracker-sparql.c:110 #: src/tracker/tracker-sql.c:44 msgid "Location of the database" @@ -145,61 +145,74 @@ msgstr "" "새 데이터베이스를 만들었습니다. 메시지 버스에서 이 데이터베이스를 공유하려면 " "“--dbus-service” 옵션을 사용하십시오." -#: src/tracker/tracker-export.c:49 src/tracker/tracker-import.c:47 +#: src/tracker/tracker-export.c:50 src/tracker/tracker-import.c:47 #: src/tracker/tracker-import.c:62 src/tracker/tracker-import.c:63 #: src/tracker/tracker-sparql.c:111 src/tracker/tracker-sparql.c:123 #: src/tracker/tracker-sql.c:45 src/tracker/tracker-sql.c:49 msgid "FILE" msgstr "<파일>" -#: src/tracker/tracker-export.c:52 src/tracker/tracker-import.c:50 +#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:50 #: src/tracker/tracker-sparql.c:114 msgid "Connects to a DBus service" msgstr "DBus 서비스로 연결합니다" -#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:51 +#: src/tracker/tracker-export.c:54 src/tracker/tracker-import.c:51 #: src/tracker/tracker-sparql.c:115 msgid "DBus service name" msgstr "DBus 서비스 명칭" -#: src/tracker/tracker-export.c:56 src/tracker/tracker-import.c:54 +#: src/tracker/tracker-export.c:57 +msgid "Output results format: “turtle”, “trig” or “json-ld”" +msgstr "출력 결과 형식: “turtle”, “trig”, “json-ld”" + +#: src/tracker/tracker-export.c:58 +msgid "RDF_FORMAT" +msgstr "RDF_FORMAT" + +#: src/tracker/tracker-export.c:61 src/tracker/tracker-import.c:54 #: src/tracker/tracker-sparql.c:118 msgid "Connects to a remote service" msgstr "원격 서비스로 연결합니다" -#: src/tracker/tracker-export.c:57 src/tracker/tracker-import.c:55 +#: src/tracker/tracker-export.c:62 src/tracker/tracker-import.c:55 #: src/tracker/tracker-sparql.c:119 msgid "Remote service URI" msgstr "원격 서비스 URI" -#: src/tracker/tracker-export.c:60 +#: src/tracker/tracker-export.c:65 msgid "Output TriG format which includes named graph information" msgstr "이름을 부여한 그래프 정보가 들어간 TriG 형식으로 출력" -#: src/tracker/tracker-export.c:72 src/tracker/tracker-export.c:73 +#: src/tracker/tracker-export.c:77 src/tracker/tracker-export.c:78 msgid "IRI" msgstr "<IRI>" #. TRANSLATORS: Those are commandline arguments -#: src/tracker/tracker-export.c:98 src/tracker/tracker-import.c:88 +#: src/tracker/tracker-export.c:103 src/tracker/tracker-import.c:88 #: src/tracker/tracker-sparql.c:199 msgid "Specify one “--database”, “--dbus-service” or “--remote-service” option" msgstr "" "“--database”, “--dbus-service”, “--remote-service” 옵션 중 하나를 지정하십시" "오" -#: src/tracker/tracker-export.c:305 src/tracker/tracker-export.c:325 +#: src/tracker/tracker-export.c:310 src/tracker/tracker-export.c:331 #: src/tracker/tracker-import.c:125 src/tracker/tracker-sparql.c:1124 msgid "No error given" msgstr "발생한 오류가 없습니다" -#: src/tracker/tracker-export.c:324 src/tracker/tracker-import.c:124 +#: src/tracker/tracker-export.c:330 src/tracker/tracker-import.c:124 #: src/tracker/tracker-sparql.c:1123 msgid "Could not establish a connection to Tracker" msgstr "트래커로 연결을 수립할 수 없습니다" -#: src/tracker/tracker-export.c:391 src/tracker/tracker-export.c:404 -#: src/tracker/tracker-export.c:414 src/tracker/tracker-sparql.c:1502 +#: src/tracker/tracker-export.c:373 +#, c-format +msgid "Unsupported serialization format “%s”\n" +msgstr "지원하지 않는 “%s” 직렬화 형식\n" + +#: src/tracker/tracker-export.c:425 src/tracker/tracker-export.c:438 +#: src/tracker/tracker-export.c:448 src/tracker/tracker-sparql.c:1502 #: src/tracker/tracker-sql.c:137 src/tracker/tracker-sql.c:170 msgid "Could not run query" msgstr "질의문을 실행할 수 없습니다" @@ -1,16 +1,16 @@ # Polish translation for tracker. -# Copyright © 2007-2022 the tracker authors. +# Copyright © 2007-2023 the tracker authors. # This file is distributed under the same license as the tracker package. # Tomasz Dominikowski <dominikowski@gmail.com>, 2007-2008. -# Piotr Drąg <piotrdrag@gmail.com>, 2009-2022. -# Aviary.pl <community-poland@mozilla.org>, 2007-2022. +# Piotr Drąg <piotrdrag@gmail.com>, 2009-2023. +# Aviary.pl <community-poland@mozilla.org>, 2007-2023. # msgid "" msgstr "" "Project-Id-Version: tracker\n" "Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/tracker/issues\n" -"POT-Creation-Date: 2022-07-12 10:59+0000\n" -"PO-Revision-Date: 2022-08-15 15:08+0200\n" +"POT-Creation-Date: 2023-02-13 21:09+0000\n" +"PO-Revision-Date: 2023-03-05 17:45+0100\n" "Last-Translator: Piotr Drąg <piotrdrag@gmail.com>\n" "Language-Team: Polish <community-poland@mozilla.org>\n" "Language: pl\n" @@ -34,13 +34,13 @@ msgstr "the|a|an" msgid "Version" msgstr "Wersja" -#: src/portal/tracker-main.c:109 src/tracker/tracker-endpoint.c:387 -#: src/tracker/tracker-export.c:509 src/tracker/tracker-import.c:196 +#: src/portal/tracker-main.c:110 src/tracker/tracker-endpoint.c:387 +#: src/tracker/tracker-export.c:543 src/tracker/tracker-import.c:196 #: src/tracker/tracker-sparql.c:1566 src/tracker/tracker-sql.c:239 msgid "Unrecognized options" msgstr "Nierozpoznane opcje" -#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:48 +#: src/tracker/tracker-endpoint.c:50 src/tracker/tracker-export.c:49 #: src/tracker/tracker-import.c:46 src/tracker/tracker-sparql.c:110 #: src/tracker/tracker-sql.c:44 msgid "Location of the database" @@ -145,61 +145,74 @@ msgstr "" "Utworzono nową bazę danych. Użycie opcji „--dbus-service” umożliwia " "udostępnienie tej bazy na magistrali komunikatów." -#: src/tracker/tracker-export.c:49 src/tracker/tracker-import.c:47 +#: src/tracker/tracker-export.c:50 src/tracker/tracker-import.c:47 #: src/tracker/tracker-import.c:62 src/tracker/tracker-import.c:63 #: src/tracker/tracker-sparql.c:111 src/tracker/tracker-sparql.c:123 #: src/tracker/tracker-sql.c:45 src/tracker/tracker-sql.c:49 msgid "FILE" msgstr "PLIK" -#: src/tracker/tracker-export.c:52 src/tracker/tracker-import.c:50 +#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:50 #: src/tracker/tracker-sparql.c:114 msgid "Connects to a DBus service" msgstr "Łączy z usługą D-Bus" -#: src/tracker/tracker-export.c:53 src/tracker/tracker-import.c:51 +#: src/tracker/tracker-export.c:54 src/tracker/tracker-import.c:51 #: src/tracker/tracker-sparql.c:115 msgid "DBus service name" msgstr "Nazwa usługi D-Bus" -#: src/tracker/tracker-export.c:56 src/tracker/tracker-import.c:54 +#: src/tracker/tracker-export.c:57 +msgid "Output results format: “turtle”, “trig” or “json-ld”" +msgstr "Format wyników wyjścia: „turtle”, „trig” lub „json-ld”" + +#: src/tracker/tracker-export.c:58 +msgid "RDF_FORMAT" +msgstr "FORMAT_RDF" + +#: src/tracker/tracker-export.c:61 src/tracker/tracker-import.c:54 #: src/tracker/tracker-sparql.c:118 msgid "Connects to a remote service" msgstr "Łączy ze zdalną usługą" -#: src/tracker/tracker-export.c:57 src/tracker/tracker-import.c:55 +#: src/tracker/tracker-export.c:62 src/tracker/tracker-import.c:55 #: src/tracker/tracker-sparql.c:119 msgid "Remote service URI" msgstr "Adres URI zdalnej usługi" -#: src/tracker/tracker-export.c:60 +#: src/tracker/tracker-export.c:65 msgid "Output TriG format which includes named graph information" msgstr "Wyjściowy format TriG zawierający informacje o nazwanym wykresie" -#: src/tracker/tracker-export.c:72 src/tracker/tracker-export.c:73 +#: src/tracker/tracker-export.c:77 src/tracker/tracker-export.c:78 msgid "IRI" msgstr "IRI" #. TRANSLATORS: Those are commandline arguments -#: src/tracker/tracker-export.c:98 src/tracker/tracker-import.c:88 +#: src/tracker/tracker-export.c:103 src/tracker/tracker-import.c:88 #: src/tracker/tracker-sparql.c:199 msgid "Specify one “--database”, “--dbus-service” or “--remote-service” option" msgstr "" "Należy podać jedną opcję „--database”, „--dbus-service” lub „--remote-" "service”" -#: src/tracker/tracker-export.c:305 src/tracker/tracker-export.c:325 +#: src/tracker/tracker-export.c:310 src/tracker/tracker-export.c:331 #: src/tracker/tracker-import.c:125 src/tracker/tracker-sparql.c:1124 msgid "No error given" msgstr "Nie podano błędu" -#: src/tracker/tracker-export.c:324 src/tracker/tracker-import.c:124 +#: src/tracker/tracker-export.c:330 src/tracker/tracker-import.c:124 #: src/tracker/tracker-sparql.c:1123 msgid "Could not establish a connection to Tracker" msgstr "Nie można nawiązać połączenia z programem Tracker" -#: src/tracker/tracker-export.c:391 src/tracker/tracker-export.c:404 -#: src/tracker/tracker-export.c:414 src/tracker/tracker-sparql.c:1502 +#: src/tracker/tracker-export.c:373 +#, c-format +msgid "Unsupported serialization format “%s”\n" +msgstr "Nieobsługiwany format serializacji „%s”\n" + +#: src/tracker/tracker-export.c:425 src/tracker/tracker-export.c:438 +#: src/tracker/tracker-export.c:448 src/tracker/tracker-sparql.c:1502 #: src/tracker/tracker-sql.c:137 src/tracker/tracker-sql.c:170 msgid "Could not run query" msgstr "Nie można wykonać zapytania" diff --git a/src/libtracker-common/meson.build b/src/libtracker-common/meson.build index 17bdd533a..800c14771 100644 --- a/src/libtracker-common/meson.build +++ b/src/libtracker-common/meson.build @@ -6,18 +6,42 @@ tracker_common_sources = [ 'tracker-file-utils.c', 'tracker-term-utils.c', 'tracker-utils.c', - 'tracker-locale.c', - 'tracker-parser-utils.c', - 'tracker-language.c', + 'tracker-parser.c', ] if unicode_library_name == 'icu' - tracker_common_sources += 'tracker-parser-libicu.c' + libtracker_parser_libicu = shared_module('tracker-parser-libicu', + 'tracker-parser-libicu.c', + 'tracker-parser-utils.c', + 'tracker-language.c', + dependencies: [gobject,libstemmer, icu_uc, icu_i18n], + c_args: tracker_c_args + [ + '-include', join_paths(build_root, 'config.h'), + '-DMODULE', + ], + include_directories: [configinc, srcinc], + install: true, + install_dir: tracker_internal_libs_dir, + name_suffix: 'so', + ) else - tracker_common_sources += 'tracker-parser-libunistring.c' + libtracker_parser_libunistring = shared_module('tracker-parser-libunistring', + 'tracker-parser-libunistring.c', + 'tracker-parser-utils.c', + 'tracker-language.c', + dependencies: [gobject,libstemmer, libunistring], + c_args: tracker_c_args + [ + '-include', join_paths(build_root, 'config.h'), + '-DMODULE', + ], + include_directories: [configinc, srcinc], + install: true, + install_dir: tracker_internal_libs_dir, + name_suffix: 'so', + ) endif -tracker_common_dependencies = [glib, gio, gio_unix, libmath, libstemmer] +tracker_common_dependencies = [glib, gio, gio_unix, libmath] if build_machine.system() == 'openbsd' libkvm = meson.get_compiler('c').find_library('kvm') @@ -26,8 +50,12 @@ endif libtracker_common = static_library('tracker-common', tracker_common_sources, - dependencies: tracker_common_dependencies + [unicode_library], - c_args: tracker_c_args, + dependencies: [tracker_common_dependencies, gmodule], + c_args: [ + '-DPRIVATE_LIBDIR="@0@"'.format(tracker_internal_libs_dir), + '-DBUILD_LIBDIR="@0@"'.format(meson.current_build_dir()), + '-DBUILDROOT="@0@"'.format(meson.build_root()), + ] + tracker_c_args, include_directories: [configinc, srcinc], gnu_symbol_visibility: 'hidden', ) @@ -36,6 +64,6 @@ commoninc = include_directories('.') tracker_common_dep = declare_dependency( link_with: libtracker_common, - dependencies: tracker_common_dependencies + [unicode_library], + dependencies: [tracker_common_dependencies, gmodule], include_directories: [configinc, srcinc, commoninc], ) diff --git a/src/libtracker-common/tracker-common.h b/src/libtracker-common/tracker-common.h index e572b6ebc..d04e2b083 100644 --- a/src/libtracker-common/tracker-common.h +++ b/src/libtracker-common/tracker-common.h @@ -31,11 +31,9 @@ #include "tracker-date-time.h" #include "tracker-debug.h" #include "tracker-file-utils.h" -#include "tracker-language.h" #include "tracker-parser.h" #include "tracker-term-utils.h" #include "tracker-utils.h" -#include "tracker-locale.h" #undef __LIBTRACKER_COMMON_INSIDE__ diff --git a/src/libtracker-common/tracker-locale.c b/src/libtracker-common/tracker-locale.c deleted file mode 100644 index 816bb8d69..000000000 --- a/src/libtracker-common/tracker-locale.c +++ /dev/null @@ -1,105 +0,0 @@ -/* - * Copyright (C) 2010 Nokia <ivan.frade@nokia.com> - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Lesser General Public - * License as published by the Free Software Foundation; either - * version 2.1 of the License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - */ - -#include "config.h" - -#include <locale.h> -#include <string.h> - -#include <glib.h> - -#include "tracker-locale.h" - -static const gchar *locale_names[] = { - [TRACKER_LOCALE_LANGUAGE] = "LANG", - [TRACKER_LOCALE_TIME] = "LC_TIME", - [TRACKER_LOCALE_COLLATE] = "LC_COLLATE", - [TRACKER_LOCALE_NUMERIC] = "LC_NUMERIC", - [TRACKER_LOCALE_MONETARY] = "LC_MONETARY" -}; - -static GRecMutex locales_mutex; - -static const gchar * -tracker_locale_get_unlocked (TrackerLocaleID id) -{ - const gchar *env_locale = NULL; - - switch (id) { - case TRACKER_LOCALE_LANGUAGE: - env_locale = g_getenv ("LANG"); - break; - case TRACKER_LOCALE_TIME: - env_locale = setlocale (LC_TIME, NULL); - break; - case TRACKER_LOCALE_COLLATE: - env_locale = setlocale (LC_COLLATE, NULL); - break; - case TRACKER_LOCALE_NUMERIC: - env_locale = setlocale (LC_NUMERIC, NULL); - break; - case TRACKER_LOCALE_MONETARY: - env_locale = setlocale (LC_MONETARY, NULL); - break; - default: - g_assert_not_reached (); - break; - } - - return env_locale; -} - -void -tracker_locale_sanity_check (void) -{ - guint i; - - g_rec_mutex_lock (&locales_mutex); - - for (i = 0; i < TRACKER_LOCALE_LAST; i++) { - const gchar *env_locale = NULL; - - env_locale = tracker_locale_get_unlocked (i); - - if (!env_locale) { - g_warning ("Locale '%s' is not set, defaulting to C locale", locale_names[i]); - } - } - - g_rec_mutex_unlock (&locales_mutex); -} - -gchar * -tracker_locale_get (TrackerLocaleID id) -{ - const gchar *env_locale = NULL; - gchar *locale; - - g_rec_mutex_lock (&locales_mutex); - - env_locale = tracker_locale_get_unlocked (id); - - /* Always return a duplicated string, as the locale may change at any - * moment */ - locale = g_strdup (env_locale); - - g_rec_mutex_unlock (&locales_mutex); - - return locale; -} diff --git a/src/libtracker-common/tracker-locale.h b/src/libtracker-common/tracker-locale.h deleted file mode 100644 index 32547d13d..000000000 --- a/src/libtracker-common/tracker-locale.h +++ /dev/null @@ -1,50 +0,0 @@ -/* - * Copyright (C) 2010 Nokia <ivan.frade@nokia.com> - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Lesser General Public - * License as published by the Free Software Foundation; either - * version 2.1 of the License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - */ - -#ifndef __LIBTRACKER_COMMON_LOCALE_H__ -#define __LIBTRACKER_COMMON_LOCALE_H__ - -#include <glib.h> - -G_BEGIN_DECLS - -#if !defined (__LIBTRACKER_COMMON_INSIDE__) && !defined (TRACKER_COMPILATION) -#error "only <libtracker-common/tracker-common.h> must be included directly." -#endif - -/* Type of locales supported in tracker */ -typedef enum { - TRACKER_LOCALE_LANGUAGE, - TRACKER_LOCALE_TIME, - TRACKER_LOCALE_COLLATE, - TRACKER_LOCALE_NUMERIC, - TRACKER_LOCALE_MONETARY, - TRACKER_LOCALE_LAST -} TrackerLocaleID; - -void tracker_locale_sanity_check (void); - -/* Get the current locale of the given type. - * Note that it returns a newly-allocated string which should be g_free()-ed - */ -gchar *tracker_locale_get (TrackerLocaleID id); - -G_END_DECLS - -#endif /* __LIBTRACKER_COMMON_LOCALE_H__ */ diff --git a/src/libtracker-common/tracker-parser-libicu.c b/src/libtracker-common/tracker-parser-libicu.c index 8c4803206..8795af7cf 100644 --- a/src/libtracker-common/tracker-parser-libicu.c +++ b/src/libtracker-common/tracker-parser-libicu.c @@ -30,7 +30,10 @@ #include <unicode/ustring.h> #include <unicode/uchar.h> #include <unicode/unorm.h> +#include <unicode/ucol.h> +#include "tracker-language.h" +#include "tracker-debug.h" #include "tracker-parser.h" #include "tracker-parser-utils.h" @@ -41,6 +44,8 @@ typedef enum { TRACKER_PARSER_WORD_TYPE_OTHER_NO_UNAC, } TrackerParserWordType; +typedef UCollator TrackerCollator; + /* Max possible length of a UChar encoded string (just a safety limit) */ #define WORD_BUFFER_LENGTH 512 @@ -144,7 +149,7 @@ get_word_info (const UChar *word, /* The input word in this method MUST be normalized in NFKD form, * and given in UChars, where str_length is the number of UChars * (not the number of bytes) */ -gboolean +static gboolean tracker_parser_unaccent_nfkd_string (gpointer str, gsize *str_length) { @@ -571,15 +576,12 @@ parser_next (TrackerParser *parser, } TrackerParser * -tracker_parser_new (TrackerLanguage *language) +tracker_parser_new (void) { TrackerParser *parser; - g_return_val_if_fail (TRACKER_IS_LANGUAGE (language), NULL); - parser = g_new0 (TrackerParser, 1); - - parser->language = g_object_ref (language); + parser->language = tracker_language_new (NULL); return parser; } @@ -754,3 +756,253 @@ tracker_parser_next (TrackerParser *parser, return str; } +gpointer +tracker_collation_init (void) +{ + UCollator *collator = NULL; + UErrorCode status = U_ZERO_ERROR; + const gchar *locale; + + /* Get locale! */ + locale = setlocale (LC_COLLATE, NULL); + + collator = ucol_open (locale, &status); + if (!collator) { + g_warning ("[ICU collation] Collator for locale '%s' cannot be created: %s", + locale, u_errorName (status)); + /* Try to get UCA collator then... */ + status = U_ZERO_ERROR; + collator = ucol_open ("root", &status); + if (!collator) { + g_critical ("[ICU collation] UCA Collator cannot be created: %s", + u_errorName (status)); + } + } + + return collator; +} + +void +tracker_collation_shutdown (gpointer collator) +{ + if (collator) + ucol_close ((UCollator *)collator); +} + +gint +tracker_collation_utf8 (gpointer collator, + gint len1, + gconstpointer str1, + gint len2, + gconstpointer str2) +{ + UErrorCode status = U_ZERO_ERROR; + UCharIterator iter1; + UCharIterator iter2; + UCollationResult result; + + /* Collator must be created before trying to collate */ + g_return_val_if_fail (collator, -1); + + /* Setup iterators */ + uiter_setUTF8 (&iter1, str1, len1); + uiter_setUTF8 (&iter2, str2, len2); + + result = ucol_strcollIter ((UCollator *)collator, + &iter1, + &iter2, + &status); + if (status != U_ZERO_ERROR) + g_critical ("Error collating: %s", u_errorName (status)); + + if (result == UCOL_GREATER) + return 1; + if (result == UCOL_LESS) + return -1; + return 0; +} + +gunichar2 * +tracker_parser_tolower (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + UChar *zOutput; + int nOutput; + UErrorCode status = U_ZERO_ERROR; + + g_return_val_if_fail (input, NULL); + + nOutput = len * 2 + 2; + zOutput = malloc (nOutput); + + u_strToLower (zOutput, nOutput / 2, + input, len / 2, + NULL, &status); + + if (!U_SUCCESS (status)) { + memcpy (zOutput, input, len); + zOutput[len] = '\0'; + nOutput = len; + } + + *len_out = nOutput; + + return zOutput; +} + +gunichar2 * +tracker_parser_toupper (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + UChar *zOutput; + int nOutput; + UErrorCode status = U_ZERO_ERROR; + + nOutput = len * 2 + 2; + zOutput = malloc (nOutput); + + u_strToUpper (zOutput, nOutput / 2, + input, len / 2, + NULL, &status); + + if (!U_SUCCESS (status)) { + memcpy (zOutput, input, len); + zOutput[len] = '\0'; + nOutput = len; + } + + *len_out = nOutput; + + return zOutput; +} + +gunichar2 * +tracker_parser_casefold (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + UChar *zOutput; + int nOutput; + UErrorCode status = U_ZERO_ERROR; + + nOutput = len * 2 + 2; + zOutput = malloc (nOutput); + + u_strFoldCase (zOutput, nOutput / 2, + input, len / 2, + U_FOLD_CASE_DEFAULT, &status); + + if (!U_SUCCESS (status)){ + memcpy (zOutput, input, len); + zOutput[len] = '\0'; + nOutput = len; + } + + *len_out = nOutput; + + return zOutput; +} + +static gunichar2 * +normalize_string (const gunichar2 *string, + gsize string_len, /* In gunichar2s */ + const UNormalizer2 *normalizer, + gsize *len_out, /* In gunichar2s */ + UErrorCode *status) +{ + int nOutput; + gunichar2 *zOutput; + + nOutput = (string_len * 2) + 1; + zOutput = g_new0 (gunichar2, nOutput); + + nOutput = unorm2_normalize (normalizer, string, string_len, zOutput, nOutput, status); + + if (*status == U_BUFFER_OVERFLOW_ERROR) { + /* Try again after allocating enough space for the normalization */ + *status = U_ZERO_ERROR; + zOutput = g_renew (gunichar2, zOutput, nOutput); + memset (zOutput, 0, nOutput * sizeof (gunichar2)); + nOutput = unorm2_normalize (normalizer, string, string_len, zOutput, nOutput, status); + } + + if (!U_SUCCESS (*status)) { + g_clear_pointer (&zOutput, g_free); + nOutput = 0; + } + + if (len_out) + *len_out = nOutput; + + return zOutput; +} + +gunichar2 * +tracker_parser_normalize (const gunichar2 *input, + GNormalizeMode mode, + gsize len, + gsize *len_out) +{ + uint16_t *zOutput = NULL; + gsize nOutput; + const UNormalizer2 *normalizer; + UErrorCode status = U_ZERO_ERROR; + + if (mode == G_NORMALIZE_NFC) + normalizer = unorm2_getNFCInstance (&status); + else if (mode == G_NORMALIZE_NFD) + normalizer = unorm2_getNFDInstance (&status); + else if (mode == G_NORMALIZE_NFKC) + normalizer = unorm2_getNFKCInstance (&status); + else if (mode == G_NORMALIZE_NFKD) + normalizer = unorm2_getNFKDInstance (&status); + else + g_assert_not_reached (); + + if (U_SUCCESS (status)) { + zOutput = normalize_string (input, len / 2, + normalizer, + &nOutput, &status); + } + + if (!U_SUCCESS (status)) { + zOutput = g_memdup2 (input, len); + nOutput = len; + } + + *len_out = nOutput; + + return zOutput; +} + +gunichar2 * +tracker_parser_unaccent (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + uint16_t *zOutput = NULL; + gsize nOutput; + const UNormalizer2 *normalizer; + UErrorCode status = U_ZERO_ERROR; + + normalizer = unorm2_getNFKDInstance (&status); + + if (U_SUCCESS (status)) { + zOutput = normalize_string (input, len / 2, + normalizer, + &nOutput, &status); + } + + if (!U_SUCCESS (status)) { + zOutput = g_memdup2 (input, len); + } + + /* Unaccenting is done in place */ + tracker_parser_unaccent_nfkd_string (zOutput, &nOutput); + + *len_out = nOutput; + + return zOutput; +} diff --git a/src/libtracker-common/tracker-parser-libunistring.c b/src/libtracker-common/tracker-parser-libunistring.c index d24c5f1cb..b26b4bae5 100644 --- a/src/libtracker-common/tracker-parser-libunistring.c +++ b/src/libtracker-common/tracker-parser-libunistring.c @@ -30,6 +30,7 @@ #include <unictype.h> #include <unicase.h> +#include "tracker-language.h" #include "tracker-parser.h" #include "tracker-parser-utils.h" @@ -40,6 +41,9 @@ typedef enum { TRACKER_PARSER_WORD_TYPE_OTHER_NO_UNAC, } TrackerParserWordType; +/* If string lenth less than this value, allocating from the stack */ +#define MAX_STACK_STR_SIZE 8192 + /* Max possible length of a UTF-8 encoded string (just a safety limit) */ #define WORD_BUFFER_LENGTH 512 @@ -84,7 +88,7 @@ get_word_info (TrackerParser *parser, /* Get first character of the word as UCS4 */ first_unichar_len = u8_strmbtouc (&first_unichar, - &(parser->txt[parser->cursor])); + (const guchar *) &(parser->txt[parser->cursor])); if (first_unichar_len <= 0) { /* This should only happen if NIL was passed to u8_strmbtouc, * so better just force stop here */ @@ -106,7 +110,7 @@ get_word_info (TrackerParser *parser, i = parser->cursor + first_unichar_len; while (1) { /* Text bounds reached? */ - if (i >= parser->txt_size) + if (i >= (gsize) parser->txt_size) break; /* Proper unicode word break detected? */ if (parser->word_break_flags[i]) @@ -159,7 +163,7 @@ get_word_info (TrackerParser *parser, /* The input word in this method MUST be normalized in NFKD form, * and given in UTF-8, where str_length is the byte-length * (note: there is no trailing NUL character!) */ -gboolean +static gboolean tracker_parser_unaccent_nfkd_string (gpointer str, gsize *str_length) { @@ -181,7 +185,7 @@ tracker_parser_unaccent_nfkd_string (gpointer str, gint utf8_len; /* Get next character of the word as UCS4 */ - utf8_len = u8_strmbtouc (&unichar, &word[i]); + utf8_len = u8_strmbtouc (&unichar, (const guchar *) &word[i]); /* Invalid UTF-8 character or end of original string. */ if (utf8_len <= 0) { @@ -249,12 +253,12 @@ process_word_utf8 (TrackerParser *parser, /* Casefold and NFKD normalization in output. * NOTE: if the output buffer is not big enough, u8_casefold will * return a newly-allocated buffer. */ - normalized = u8_casefold ((const uint8_t *)word, - length, - uc_locale_language (), - UNINORM_NFKD, - word_buffer, - &new_word_length); + normalized = (gchar*) u8_casefold ((const uint8_t *)word, + length, + uc_locale_language (), + UNINORM_NFKD, + (guchar *) word_buffer, + &new_word_length); /* Case folding + Normalization failed, ignore this word */ g_return_val_if_fail (normalized != NULL, NULL); @@ -275,7 +279,7 @@ process_word_utf8 (TrackerParser *parser, normalized = length > WORD_BUFFER_LENGTH ? g_malloc (length + 1) : word_buffer; - for (i = 0; i < length; i++) { + for (i = 0; i < (gsize) length; i++) { normalized[i] = g_ascii_tolower (word[i]); } @@ -345,7 +349,7 @@ parser_next (TrackerParser *parser, /* Loop to look for next valid word */ while (!processed_word && - parser->cursor < parser->txt_size) { + parser->cursor < (gsize) parser->txt_size) { TrackerParserWordType type; gsize truncated_length; gboolean is_allowed; @@ -424,15 +428,12 @@ parser_next (TrackerParser *parser, } TrackerParser * -tracker_parser_new (TrackerLanguage *language) +tracker_parser_new (void) { TrackerParser *parser; - g_return_val_if_fail (TRACKER_IS_LANGUAGE (language), NULL); - parser = g_new0 (TrackerParser, 1); - - parser->language = g_object_ref (language); + parser->language = tracker_language_new (NULL); return parser; } @@ -541,3 +542,106 @@ tracker_parser_next (TrackerParser *parser, return str; } +gpointer +tracker_collation_init (void) +{ + /* Nothing to do */ + return NULL; +} + +void +tracker_collation_shutdown (gpointer collator) +{ + /* Nothing to do */ +} + +gint +tracker_collation_utf8 (gpointer collator, + gint len1, + gconstpointer str1, + gint len2, + gconstpointer str2) +{ + gint result; + guchar *aux1; + guchar *aux2; + + /* Note: str1 and str2 are NOT NUL-terminated */ + aux1 = (len1 < MAX_STACK_STR_SIZE) ? g_alloca (len1+1) : g_malloc (len1+1); + aux2 = (len2 < MAX_STACK_STR_SIZE) ? g_alloca (len2+1) : g_malloc (len2+1); + + memcpy (aux1, str1, len1); aux1[len1] = '\0'; + memcpy (aux2, str2, len2); aux2[len2] = '\0'; + + result = u8_strcoll (aux1, aux2); + + if (len1 >= MAX_STACK_STR_SIZE) + g_free (aux1); + if (len2 >= MAX_STACK_STR_SIZE) + g_free (aux2); + return result; +} + +gunichar2 * +tracker_parser_tolower (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + return u16_tolower (input, len / 2, NULL, NULL, NULL, len_out); +} + +gunichar2 * +tracker_parser_toupper (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + return u16_toupper (input, len / 2, NULL, NULL, NULL, len_out); +} + +gunichar2 * +tracker_parser_casefold (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + return u16_casefold (input, len / 2, NULL, NULL, NULL, len_out); +} + +gunichar2 * +tracker_parser_normalize (const gunichar2 *input, + GNormalizeMode mode, + gsize len, + gsize *len_out) +{ + uninorm_t nf; + + if (mode == G_NORMALIZE_NFC) + nf = UNINORM_NFC; + else if (mode == G_NORMALIZE_NFD) + nf = UNINORM_NFD; + else if (mode == G_NORMALIZE_NFKC) + nf = UNINORM_NFKC; + else if (mode == G_NORMALIZE_NFKD) + nf = UNINORM_NFKD; + else + g_assert_not_reached (); + + return u16_normalize (nf, input, len / 2, NULL, len_out); +} + +gunichar2 * +tracker_parser_unaccent (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + gunichar2 *zOutput; + gsize written = 0; + + zOutput = u16_normalize (UNINORM_NFKD, input, len, NULL, &written); + + /* Unaccenting is done in place */ + tracker_parser_unaccent_nfkd_string (zOutput, &written); + + *len_out = written; + + return zOutput; +} diff --git a/src/libtracker-common/tracker-parser-utils.h b/src/libtracker-common/tracker-parser-utils.h index b2440213f..84a48c58d 100644 --- a/src/libtracker-common/tracker-parser-utils.h +++ b/src/libtracker-common/tracker-parser-utils.h @@ -24,10 +24,6 @@ #include <glib.h> -#ifdef HAVE_LIBICU -#include <unicode/utypes.h> -#endif - G_BEGIN_DECLS /* ASCII-7 is in range [0x00,0x7F] */ diff --git a/src/libtracker-common/tracker-parser.c b/src/libtracker-common/tracker-parser.c new file mode 100644 index 000000000..2300e284e --- /dev/null +++ b/src/libtracker-common/tracker-parser.c @@ -0,0 +1,255 @@ +/* + * Copyright (C) 2023, Red Hat Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + * Author: Carlos Garnacho <carlosg@gnome.org> + */ + +#include "config.h" + +#include <gio/gio.h> +#include <gmodule.h> + +#include "tracker-parser.h" + +#include "tracker-debug.h" + +static TrackerParser * (*parser_new) (void); +static void (*parser_free) (TrackerParser *parser); +static void (*parser_reset) (TrackerParser *parser, + const gchar *txt, + gint txt_size, + guint max_word_length, + gboolean enable_stemmer, + gboolean enable_unaccent, + gboolean ignore_stop_words, + gboolean ignore_reserved_words, + gboolean ignore_numbers); +static const gchar * (*parser_next) (TrackerParser *parser, + gint *position, + gint *byte_offset_start, + gint *byte_offset_end, + gboolean *stop_word, + gint *word_length); +static gpointer (*collation_init) (void); +static void (*collation_shutdown) (gpointer collator); +static gint (*collation_utf8) (gpointer collator, + gint len1, + gconstpointer str1, + gint len2, + gconstpointer str2); +static gunichar2 * (*util_tolower) (const gunichar2 *input, + gsize len, + gsize *len_out); +static gunichar2 * (*util_toupper) (const gunichar2 *input, + gsize len, + gsize *len_out); +static gunichar2 * (*util_casefold) (const gunichar2 *input, + gsize len, + gsize *len_out); +static gunichar2 * (*util_normalize) (const gunichar2 *input, + GNormalizeMode mode, + gsize len, + gsize *len_out); +static gunichar2 * (*util_unaccent) (const gunichar2 *input, + gsize len, + gsize *len_out); + +static void +ensure_init_parser (void) +{ + static GModule *module = NULL; + + if (module == NULL) { + const gchar *modules[] = { + + "libtracker-parser-libicu.so", + "libtracker-parser-libunistring.so" + }; + gchar *module_path; + guint i; + + g_assert (g_module_supported ()); + + for (i = 0; i < G_N_ELEMENTS (modules); i++) { + if (g_strcmp0 (g_get_current_dir (), BUILDROOT) == 0) { + /* Detect in-build runtime of this code, this may happen + * building introspection information or running tests. + * We want the in-tree modules to be loaded then. + */ + module_path = g_strdup_printf (BUILD_LIBDIR "/%s", modules[i]); + } else { + module_path = g_strdup_printf (PRIVATE_LIBDIR "/%s", modules[i]); + } + + module = g_module_open (module_path, + G_MODULE_BIND_LAZY | + G_MODULE_BIND_LOCAL); + g_free (module_path); + + if (module) + break; + } + + g_assert (module != NULL); + + if (!g_module_symbol (module, "tracker_parser_new", (gpointer *) &parser_new) || + !g_module_symbol (module, "tracker_parser_free", (gpointer *) &parser_free) || + !g_module_symbol (module, "tracker_parser_reset", (gpointer *) &parser_reset) || + !g_module_symbol (module, "tracker_parser_next", (gpointer *) &parser_next) || + !g_module_symbol (module, "tracker_collation_init", (gpointer *) &collation_init) || + !g_module_symbol (module, "tracker_collation_shutdown", (gpointer *) &collation_shutdown) || + !g_module_symbol (module, "tracker_collation_utf8", (gpointer *) &collation_utf8) || + !g_module_symbol (module, "tracker_parser_tolower", (gpointer *) &util_tolower) || + !g_module_symbol (module, "tracker_parser_toupper", (gpointer *) &util_toupper) || + !g_module_symbol (module, "tracker_parser_casefold", (gpointer *) &util_casefold) || + !g_module_symbol (module, "tracker_parser_normalize", (gpointer *) &util_normalize) || + !g_module_symbol (module, "tracker_parser_unaccent", (gpointer *) &util_unaccent)) { + g_printerr ("Could not initialize parser functions: %s\n", + g_module_error ()); + } + + TRACKER_NOTE (COLLATION, g_message ("Initialized collator %s", g_module_name (module))); + + g_module_make_resident (module); + g_module_close (module); + } +} + +TrackerParser * +tracker_parser_new (void) +{ + ensure_init_parser (); + + return parser_new (); +} + +void +tracker_parser_free (TrackerParser *parser) +{ + parser_free (parser); +} + +void +tracker_parser_reset (TrackerParser *parser, + const gchar *txt, + gint txt_size, + guint max_word_length, + gboolean enable_stemmer, + gboolean enable_unaccent, + gboolean ignore_stop_words, + gboolean ignore_reserved_words, + gboolean ignore_numbers) +{ + parser_reset (parser, txt, txt_size, + max_word_length, + enable_stemmer, + enable_unaccent, + ignore_stop_words, + ignore_reserved_words, + ignore_numbers); +} + +const gchar * +tracker_parser_next (TrackerParser *parser, + gint *position, + gint *byte_offset_start, + gint *byte_offset_end, + gboolean *stop_word, + gint *word_length) +{ + return parser_next (parser, position, + byte_offset_start, + byte_offset_end, + stop_word, + word_length); +} + +gpointer +tracker_collation_init (void) +{ + ensure_init_parser (); + + return collation_init (); +} + +void +tracker_collation_shutdown (gpointer collator) +{ + collation_shutdown (collator); +} + +gint +tracker_collation_utf8 (gpointer collator, + gint len1, + gconstpointer str1, + gint len2, + gconstpointer str2) +{ + return collation_utf8 (collator, len1, str1, len2, str2); +} + +gunichar2 * +tracker_parser_tolower (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + ensure_init_parser (); + + return util_tolower (input, len, len_out); +} + +gunichar2 * +tracker_parser_toupper (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + ensure_init_parser (); + + return util_toupper (input, len, len_out); +} + +gunichar2 * +tracker_parser_casefold (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + ensure_init_parser (); + + return util_casefold (input, len, len_out); +} + +gunichar2 * +tracker_parser_normalize (const gunichar2 *input, + GNormalizeMode mode, + gsize len, + gsize *len_out) +{ + ensure_init_parser (); + + return util_normalize (input, mode, len, len_out); +} + +gunichar2 * +tracker_parser_unaccent (const gunichar2 *input, + gsize len, + gsize *len_out) +{ + ensure_init_parser (); + + return util_unaccent (input, len, len_out); +} diff --git a/src/libtracker-common/tracker-parser.h b/src/libtracker-common/tracker-parser.h index 3c8271503..78d67e21f 100644 --- a/src/libtracker-common/tracker-parser.h +++ b/src/libtracker-common/tracker-parser.h @@ -34,9 +34,10 @@ G_BEGIN_DECLS +/* Parser */ typedef struct TrackerParser TrackerParser; -TrackerParser *tracker_parser_new (TrackerLanguage *language); +TrackerParser *tracker_parser_new (void); void tracker_parser_reset (TrackerParser *parser, const gchar *txt, @@ -57,10 +58,39 @@ const gchar * tracker_parser_next (TrackerParser *parser, void tracker_parser_free (TrackerParser *parser); +/* Collation */ +gpointer tracker_collation_init (void); + +void tracker_collation_shutdown (gpointer collator); + +gint tracker_collation_utf8 (gpointer collator, + gint len1, + gconstpointer str1, + gint len2, + gconstpointer str2); + /* Other helper methods */ -gboolean tracker_parser_unaccent_nfkd_string (gpointer str, - gsize *str_length); +gunichar2 * tracker_parser_tolower (const gunichar2 *input, + gsize len, + gsize *len_out); + +gunichar2 * tracker_parser_toupper (const gunichar2 *input, + gsize len, + gsize *len_out); + +gunichar2 * tracker_parser_casefold (const gunichar2 *input, + gsize len, + gsize *len_out); + +gunichar2 * tracker_parser_normalize (const gunichar2 *input, + GNormalizeMode mode, + gsize len, + gsize *len_out); + +gunichar2 * tracker_parser_unaccent (const gunichar2 *input, + gsize len, + gsize *len_out); G_END_DECLS diff --git a/src/libtracker-sparql/core/tracker-collation.c b/src/libtracker-sparql/core/tracker-collation.c index beca29e3b..0e82d66dd 100644 --- a/src/libtracker-sparql/core/tracker-collation.c +++ b/src/libtracker-sparql/core/tracker-collation.c @@ -18,229 +18,12 @@ */ #include "config.h" + #include <glib.h> #include <glib/gi18n.h> -#include <string.h> -#include <locale.h> -#include <libtracker-common/tracker-debug.h> -#include <libtracker-common/tracker-locale.h> #include "tracker-collation.h" -/* If defined, will dump additional traces */ -#ifdef G_ENABLE_DEBUG -#define trace(message, ...) TRACKER_NOTE (COLLATION, g_message (message, ##__VA_ARGS__)) -#else -#define trace(...) -#endif - -#ifdef HAVE_LIBUNISTRING -/* libunistring versions prior to 9.1.2 need this hack */ -#define _UNUSED_PARAMETER_ -#include <unistr.h> -#elif defined(HAVE_LIBICU) -#include <unicode/ucol.h> -#include <unicode/utypes.h> -#endif - -/* If string lenth less than this value, allocating from the stack */ -#define MAX_STACK_STR_SIZE 8192 - -#ifdef HAVE_LIBUNISTRING /* ---- GNU libunistring based collation ---- */ - -gpointer -tracker_collation_init (void) -{ - gchar *locale; - - /* Get locale! */ - locale = tracker_locale_get (TRACKER_LOCALE_COLLATE); - TRACKER_NOTE (COLLATION, g_message ("[libunistring collation] Initializing collator for locale '%s'", locale)); - g_free (locale); - /* Nothing to do */ - return NULL; -} - -void -tracker_collation_shutdown (gpointer collator) -{ - /* Nothing to do */ -} - -gint -tracker_collation_utf8 (gpointer collator, - gint len1, - gconstpointer str1, - gint len2, - gconstpointer str2) -{ - gint result; - gchar *aux1; - gchar *aux2; - - /* Note: str1 and str2 are NOT NUL-terminated */ - aux1 = (len1 < MAX_STACK_STR_SIZE) ? g_alloca (len1+1) : g_malloc (len1+1); - aux2 = (len2 < MAX_STACK_STR_SIZE) ? g_alloca (len2+1) : g_malloc (len2+1); - - memcpy (aux1, str1, len1); aux1[len1] = '\0'; - memcpy (aux2, str2, len2); aux2[len2] = '\0'; - - result = u8_strcoll (aux1, aux2); - - trace ("(libunistring) Collating '%s' and '%s' (%d)", - aux1, aux2, result); - - if (len1 >= MAX_STACK_STR_SIZE) - g_free (aux1); - if (len2 >= MAX_STACK_STR_SIZE) - g_free (aux2); - return result; -} - -#elif defined(HAVE_LIBICU) /* ---- ICU based collation (UTF-16) ----*/ - -gpointer -tracker_collation_init (void) -{ - UCollator *collator = NULL; - UErrorCode status = U_ZERO_ERROR; - gchar *locale; - - /* Get locale! */ - locale = tracker_locale_get (TRACKER_LOCALE_COLLATE); - - TRACKER_NOTE (COLLATION, g_message ("[ICU collation] Initializing collator for locale '%s'", locale)); - collator = ucol_open (locale, &status); - if (!collator) { - g_warning ("[ICU collation] Collator for locale '%s' cannot be created: %s", - locale, u_errorName (status)); - /* Try to get UCA collator then... */ - status = U_ZERO_ERROR; - collator = ucol_open ("root", &status); - if (!collator) { - g_critical ("[ICU collation] UCA Collator cannot be created: %s", - u_errorName (status)); - } - } - g_free (locale); - return collator; -} - -void -tracker_collation_shutdown (gpointer collator) -{ - if (collator) - ucol_close ((UCollator *)collator); -} - -gint -tracker_collation_utf8 (gpointer collator, - gint len1, - gconstpointer str1, - gint len2, - gconstpointer str2) -{ - UErrorCode status = U_ZERO_ERROR; - UCharIterator iter1; - UCharIterator iter2; - UCollationResult result; - - /* Collator must be created before trying to collate */ - g_return_val_if_fail (collator, -1); - - /* Setup iterators */ - uiter_setUTF8 (&iter1, str1, len1); - uiter_setUTF8 (&iter2, str2, len2); - - result = ucol_strcollIter ((UCollator *)collator, - &iter1, - &iter2, - &status); - if (status != U_ZERO_ERROR) - g_critical ("Error collating: %s", u_errorName (status)); - -#ifdef ENABLE_TRACE - { - gchar *aux1; - gchar *aux2; - - /* Note: str1 and str2 are NOT NUL-terminated */ - aux1 = (len1 < MAX_STACK_STR_SIZE) ? g_alloca (len1+1) : g_malloc (len1+1); - aux2 = (len2 < MAX_STACK_STR_SIZE) ? g_alloca (len2+1) : g_malloc (len2+1); - - memcpy (aux1, str1, len1); aux1[len1] = '\0'; - memcpy (aux2, str2, len2); aux2[len2] = '\0'; - - trace ("(ICU) Collating '%s' and '%s' (%d)", - aux1, aux2, result); - - if (len1 >= MAX_STACK_STR_SIZE) - g_free (aux1); - if (len2 >= MAX_STACK_STR_SIZE) - g_free (aux2); - } -#endif /* ENABLE_TRACE */ - - if (result == UCOL_GREATER) - return 1; - if (result == UCOL_LESS) - return -1; - return 0; -} - -#else /* ---- GLib based collation ---- */ - -gpointer -tracker_collation_init (void) -{ - gchar *locale; - - /* Get locale! */ - locale = tracker_locale_get (TRACKER_LOCALE_COLLATE); - TRACKER_NOTE (COLLATION, g_message ("[GLib collation] Initializing collator for locale '%s'", locale)); - g_free (locale); - /* Nothing to do */ - return NULL; -} - -void -tracker_collation_shutdown (gpointer collator) -{ - /* Nothing to do */ -} - -gint -tracker_collation_utf8 (gpointer collator, - gint len1, - gconstpointer str1, - gint len2, - gconstpointer str2) -{ - gint result; - gchar *aux1; - gchar *aux2; - - /* Note: str1 and str2 are NOT NUL-terminated */ - aux1 = (len1 < MAX_STACK_STR_SIZE) ? g_alloca (len1+1) : g_malloc (len1+1); - aux2 = (len2 < MAX_STACK_STR_SIZE) ? g_alloca (len2+1) : g_malloc (len2+1); - - memcpy (aux1, str1, len1); aux1[len1] = '\0'; - memcpy (aux2, str2, len2); aux2[len2] = '\0'; - - result = g_utf8_collate (aux1, aux2); - - trace ("(GLib) Collating '%s' and '%s' (%d)", - aux1, aux2, result); - - if (len1 >= MAX_STACK_STR_SIZE) - g_free (aux1); - if (len2 >= MAX_STACK_STR_SIZE) - g_free (aux2); - return result; -} - -#endif - static gboolean skip_non_alphanumeric (const gchar **str, gint *len) diff --git a/src/libtracker-sparql/core/tracker-collation.h b/src/libtracker-sparql/core/tracker-collation.h index 95551a9f0..6369aefba 100644 --- a/src/libtracker-sparql/core/tracker-collation.h +++ b/src/libtracker-sparql/core/tracker-collation.h @@ -22,13 +22,7 @@ G_BEGIN_DECLS -gpointer tracker_collation_init (void); -void tracker_collation_shutdown (gpointer collator); -gint tracker_collation_utf8 (gpointer collator, - gint len1, - gconstpointer str1, - gint len2, - gconstpointer str2); +#include <libtracker-common/tracker-parser.h> gint tracker_collation_utf8_title (gpointer collator, gint len1, @@ -36,12 +30,7 @@ gint tracker_collation_utf8_title (gpointer collator, gint len2, gconstpointer str2); -#ifdef HAVE_LIBICU #define TRACKER_COLLATION_LAST_CHAR ((gunichar) 0x10fffd) -#else -/* glibc-based collators do not properly sort private use characters */ -#define TRACKER_COLLATION_LAST_CHAR ((gunichar) 0x9fa5) -#endif G_END_DECLS diff --git a/src/libtracker-sparql/core/tracker-data-manager.c b/src/libtracker-sparql/core/tracker-data-manager.c index 1481a1a02..80e53623e 100644 --- a/src/libtracker-sparql/core/tracker-data-manager.c +++ b/src/libtracker-sparql/core/tracker-data-manager.c @@ -25,7 +25,6 @@ #include <glib/gstdio.h> #include <libtracker-common/tracker-debug.h> -#include <libtracker-common/tracker-locale.h> #include <libtracker-sparql/tracker-deserializer-rdf.h> diff --git a/src/libtracker-sparql/core/tracker-db-interface-sqlite.c b/src/libtracker-sparql/core/tracker-db-interface-sqlite.c index 6ec1c1194..24c863616 100644 --- a/src/libtracker-sparql/core/tracker-db-interface-sqlite.c +++ b/src/libtracker-sparql/core/tracker-db-interface-sqlite.c @@ -28,30 +28,13 @@ #include <libtracker-common/tracker-date-time.h> #include <libtracker-common/tracker-debug.h> -#include <libtracker-common/tracker-locale.h> #include <libtracker-common/tracker-parser.h> #include <libtracker-sparql/tracker-cursor.h> #include <libtracker-sparql/tracker-private.h> #include "tracker-fts.h" - - -#ifdef HAVE_LIBUNISTRING -/* libunistring versions prior to 9.1.2 need this hack */ -#define _UNUSED_PARAMETER_ -#include <unistr.h> -#include <unicase.h> -#elif defined(HAVE_LIBICU) -#include <unicode/utypes.h> -#include <unicode/uregex.h> -#include <unicode/ustring.h> -#include <unicode/ucol.h> -#include <unicode/unorm2.h> -#endif - #include "tracker-collation.h" - #include "tracker-db-interface-sqlite.h" #include "tracker-db-manager.h" #include "tracker-data-enum-types.h" @@ -971,19 +954,21 @@ function_sparql_replace (sqlite3_context *context, g_free (unescaped); } -#ifdef HAVE_LIBUNISTRING - static void function_sparql_lower_case (sqlite3_context *context, int argc, sqlite3_value *argv[]) { - const uint16_t *zInput; - uint16_t *zOutput; - size_t written = 0; + const gchar *fn = "fn:lower-case"; + const gunichar2 *zInput; + gunichar2 *zOutput; int nInput; + gsize nOutput; - g_assert (argc == 1); + if (argc != 1) { + result_context_function_error (context, fn, "Invalid argument count"); + return; + } zInput = sqlite3_value_text16 (argv[0]); @@ -993,9 +978,8 @@ function_sparql_lower_case (sqlite3_context *context, nInput = sqlite3_value_bytes16 (argv[0]); - zOutput = u16_tolower (zInput, nInput/2, NULL, NULL, NULL, &written); - - sqlite3_result_text16 (context, zOutput, written * 2, free); + zOutput = tracker_parser_tolower (zInput, nInput, &nOutput); + sqlite3_result_text16 (context, zOutput, -1, free); } static void @@ -1003,12 +987,16 @@ function_sparql_upper_case (sqlite3_context *context, int argc, sqlite3_value *argv[]) { - const uint16_t *zInput; - uint16_t *zOutput; - size_t written = 0; + const gchar *fn = "fn:upper-case"; + const gunichar2 *zInput; + gunichar2 *zOutput; int nInput; + gsize nOutput; - g_assert (argc == 1); + if (argc != 1) { + result_context_function_error (context, fn, "Invalid argument count"); + return; + } zInput = sqlite3_value_text16 (argv[0]); @@ -1018,9 +1006,8 @@ function_sparql_upper_case (sqlite3_context *context, nInput = sqlite3_value_bytes16 (argv[0]); - zOutput = u16_toupper (zInput, nInput / 2, NULL, NULL, NULL, &written); - - sqlite3_result_text16 (context, zOutput, written * 2, free); + zOutput = tracker_parser_toupper (zInput, nInput, &nOutput); + sqlite3_result_text16 (context, zOutput, -1, free); } static void @@ -1028,12 +1015,16 @@ function_sparql_case_fold (sqlite3_context *context, int argc, sqlite3_value *argv[]) { - const uint16_t *zInput; - uint16_t *zOutput; - size_t written = 0; + const gchar *fn = "tracker:case-fold"; + const gunichar2 *zInput; + gunichar2 *zOutput; int nInput; + gsize nOutput; - g_assert (argc == 1); + if (argc != 1) { + result_context_function_error (context, fn, "Invalid argument count"); + return; + } zInput = sqlite3_value_text16 (argv[0]); @@ -1043,9 +1034,8 @@ function_sparql_case_fold (sqlite3_context *context, nInput = sqlite3_value_bytes16 (argv[0]); - zOutput = u16_casefold (zInput, nInput/2, NULL, NULL, NULL, &written); - - sqlite3_result_text16 (context, zOutput, written * 2, free); + zOutput = tracker_parser_casefold (zInput, nInput, &nOutput); + sqlite3_result_text16 (context, zOutput, -1, free); } static void @@ -1055,11 +1045,11 @@ function_sparql_normalize (sqlite3_context *context, { const gchar *fn = "tracker:normalize"; const gchar *nfstr; - const uint16_t *zInput; - uint16_t *zOutput; - size_t written = 0; + const gunichar2 *zInput; + gunichar2 *zOutput = NULL; + GNormalizeMode mode; int nInput; - uninorm_t nf; + gsize nOutput; if (argc != 2) { result_context_function_error (context, fn, "Invalid argument count"); @@ -1072,25 +1062,24 @@ function_sparql_normalize (sqlite3_context *context, return; } - nfstr = sqlite3_value_text (argv[1]); + nInput = sqlite3_value_bytes16 (argv[0]); + + nfstr = (gchar *)sqlite3_value_text (argv[1]); if (g_ascii_strcasecmp (nfstr, "nfc") == 0) - nf = UNINORM_NFC; + mode = G_NORMALIZE_NFC; else if (g_ascii_strcasecmp (nfstr, "nfd") == 0) - nf = UNINORM_NFD; + mode = G_NORMALIZE_NFD; else if (g_ascii_strcasecmp (nfstr, "nfkc") == 0) - nf = UNINORM_NFKC; + mode = G_NORMALIZE_NFKC; else if (g_ascii_strcasecmp (nfstr, "nfkd") == 0) - nf = UNINORM_NFKD; + mode = G_NORMALIZE_NFKD; else { - result_context_function_error (context, fn, "Invalid normalization specified, options are 'nfc', 'nfd', 'nfkc' or 'nfkd'"); + result_context_function_error (context, fn, "Invalid normalization specified"); return; } - nInput = sqlite3_value_bytes16 (argv[0]); - - zOutput = u16_normalize (nf, zInput, nInput/2, NULL, &written); - - sqlite3_result_text16 (context, zOutput, written * 2, free); + zOutput = tracker_parser_normalize (zInput, mode, nInput, &nOutput); + sqlite3_result_text16 (context, zOutput, nOutput * sizeof (gunichar2), free); } static void @@ -1098,131 +1087,17 @@ function_sparql_unaccent (sqlite3_context *context, int argc, sqlite3_value *argv[]) { - const gchar *zInput; - gchar *zOutput; - gsize written = 0; - int nInput; - - g_assert (argc == 1); - - zInput = sqlite3_value_text (argv[0]); - - if (!zInput) { - return; - } - - nInput = sqlite3_value_bytes (argv[0]); - - zOutput = u8_normalize (UNINORM_NFKD, zInput, nInput, NULL, &written); - - /* Unaccenting is done in place */ - tracker_parser_unaccent_nfkd_string (zOutput, &written); - - sqlite3_result_text (context, zOutput, written, free); -} - -#elif defined(HAVE_LIBICU) - -static void -function_sparql_lower_case (sqlite3_context *context, - int argc, - sqlite3_value *argv[]) -{ - const gchar *fn = "fn:lower-case"; - const UChar *zInput; - UChar *zOutput; - int nInput; - int nOutput; - UErrorCode status = U_ZERO_ERROR; - - g_assert (argc == 1); - - zInput = sqlite3_value_text16 (argv[0]); - - if (!zInput) { - return; - } - - nInput = sqlite3_value_bytes16 (argv[0]); - - nOutput = nInput * 2 + 2; - zOutput = sqlite3_malloc (nOutput); - - if (!zOutput) { - return; - } - - u_strToLower (zOutput, nOutput/2, zInput, nInput/2, NULL, &status); - - if (!U_SUCCESS (status)){ - char zBuf[128]; - sqlite3_snprintf (128, zBuf, "ICU error: u_strToLower(): %s", u_errorName (status)); - zBuf[127] = '\0'; - sqlite3_free (zOutput); - result_context_function_error (context, fn, zBuf); - return; - } - - sqlite3_result_text16 (context, zOutput, -1, sqlite3_free); -} - -static void -function_sparql_upper_case (sqlite3_context *context, - int argc, - sqlite3_value *argv[]) -{ - const gchar *fn = "fn:upper-case"; - const UChar *zInput; - UChar *zOutput; + const gchar *fn = "tracker:unaccent"; + const gunichar2 *zInput; + gunichar2 *zOutput = NULL; int nInput; - int nOutput; - UErrorCode status = U_ZERO_ERROR; - - g_assert (argc == 1); - - zInput = sqlite3_value_text16 (argv[0]); - - if (!zInput) { - return; - } - - nInput = sqlite3_value_bytes16 (argv[0]); - - nOutput = nInput * 2 + 2; - zOutput = sqlite3_malloc (nOutput); - - if (!zOutput) { - return; - } - - u_strToUpper (zOutput, nOutput / 2, zInput, nInput / 2, NULL, &status); + gsize nOutput; - if (!U_SUCCESS (status)){ - char zBuf[128]; - sqlite3_snprintf (128, zBuf, "ICU error: u_strToUpper(): %s", u_errorName (status)); - zBuf[127] = '\0'; - sqlite3_free (zOutput); - result_context_function_error (context, fn, zBuf); + if (argc != 1) { + result_context_function_error (context, fn, "Invalid argument count"); return; } - sqlite3_result_text16 (context, zOutput, -1, sqlite3_free); -} - -static void -function_sparql_case_fold (sqlite3_context *context, - int argc, - sqlite3_value *argv[]) -{ - const gchar *fn = "tracker:case-fold"; - const UChar *zInput; - UChar *zOutput; - int nInput; - int nOutput; - UErrorCode status = U_ZERO_ERROR; - - g_assert (argc == 1); - zInput = sqlite3_value_text16 (argv[0]); if (!zInput) { @@ -1231,25 +1106,8 @@ function_sparql_case_fold (sqlite3_context *context, nInput = sqlite3_value_bytes16 (argv[0]); - nOutput = nInput * 2 + 2; - zOutput = sqlite3_malloc (nOutput); - - if (!zOutput) { - return; - } - - u_strFoldCase (zOutput, nOutput/2, zInput, nInput/2, U_FOLD_CASE_DEFAULT, &status); - - if (!U_SUCCESS (status)){ - char zBuf[128]; - sqlite3_snprintf (128, zBuf, "ICU error: u_strFoldCase: %s", u_errorName (status)); - zBuf[127] = '\0'; - sqlite3_free (zOutput); - result_context_function_error (context, fn, zBuf); - return; - } - - sqlite3_result_text16 (context, zOutput, -1, sqlite3_free); + zOutput = tracker_parser_unaccent (zInput, nInput, &nOutput); + sqlite3_result_text16 (context, zOutput, nOutput * sizeof (gunichar2), free); } static void @@ -1277,141 +1135,6 @@ function_sparql_strip_punctuation (sqlite3_context *context, sqlite3_result_text (context, output, -1, g_free); } -static gunichar2 * -normalize_string (const gunichar2 *string, - gsize string_len, /* In gunichar2s */ - const UNormalizer2 *normalizer, - gsize *len_out, /* In gunichar2s */ - UErrorCode *status) -{ - int nOutput; - gunichar2 *zOutput; - - nOutput = (string_len * 2) + 1; - zOutput = g_new0 (gunichar2, nOutput); - - nOutput = unorm2_normalize (normalizer, string, string_len, zOutput, nOutput, status); - - if (*status == U_BUFFER_OVERFLOW_ERROR) { - /* Try again after allocating enough space for the normalization */ - *status = U_ZERO_ERROR; - zOutput = g_renew (gunichar2, zOutput, nOutput); - memset (zOutput, 0, nOutput * sizeof (gunichar2)); - nOutput = unorm2_normalize (normalizer, string, string_len, zOutput, nOutput, status); - } - - if (!U_SUCCESS (*status)) { - g_clear_pointer (&zOutput, g_free); - nOutput = 0; - } - - if (len_out) - *len_out = nOutput; - - return zOutput; -} - -static void -function_sparql_normalize (sqlite3_context *context, - int argc, - sqlite3_value *argv[]) -{ - const gchar *fn = "tracker:normalize"; - const gchar *nfstr; - const uint16_t *zInput; - uint16_t *zOutput = NULL; - int nInput; - gsize nOutput; - const UNormalizer2 *normalizer; - UErrorCode status = U_ZERO_ERROR; - - if (argc != 2) { - result_context_function_error (context, fn, "Invalid argument count"); - return; - } - - zInput = sqlite3_value_text16 (argv[0]); - - if (!zInput) { - return; - } - - nfstr = (gchar *)sqlite3_value_text (argv[1]); - if (g_ascii_strcasecmp (nfstr, "nfc") == 0) - normalizer = unorm2_getNFCInstance (&status); - else if (g_ascii_strcasecmp (nfstr, "nfd") == 0) - normalizer = unorm2_getNFDInstance (&status); - else if (g_ascii_strcasecmp (nfstr, "nfkc") == 0) - normalizer = unorm2_getNFKCInstance (&status); - else if (g_ascii_strcasecmp (nfstr, "nfkd") == 0) - normalizer = unorm2_getNFKDInstance (&status); - else { - result_context_function_error (context, fn, "Invalid normalization specified"); - return; - } - - if (U_SUCCESS (status)) { - nInput = sqlite3_value_bytes16 (argv[0]); - zOutput = normalize_string (zInput, nInput / 2, normalizer, &nOutput, &status); - } - - if (!U_SUCCESS (status)) { - char zBuf[128]; - sqlite3_snprintf (128, zBuf, "ICU error: unorm_normalize: %s", u_errorName (status)); - zBuf[127] = '\0'; - g_free (zOutput); - result_context_function_error (context, fn, zBuf); - return; - } - - sqlite3_result_text16 (context, zOutput, nOutput * sizeof (gunichar2), g_free); -} - -static void -function_sparql_unaccent (sqlite3_context *context, - int argc, - sqlite3_value *argv[]) -{ - const gchar *fn = "tracker:unaccent"; - const uint16_t *zInput; - uint16_t *zOutput = NULL; - int nInput; - gsize nOutput; - const UNormalizer2 *normalizer; - UErrorCode status = U_ZERO_ERROR; - - g_assert (argc == 1); - - zInput = sqlite3_value_text16 (argv[0]); - - if (!zInput) { - return; - } - - normalizer = unorm2_getNFKDInstance (&status); - - if (U_SUCCESS (status)) { - nInput = sqlite3_value_bytes16 (argv[0]); - zOutput = normalize_string (zInput, nInput / 2, normalizer, &nOutput, &status); - } - - if (!U_SUCCESS (status)) { - char zBuf[128]; - sqlite3_snprintf (128, zBuf, "ICU error: unorm_normalize: %s", u_errorName (status)); - zBuf[127] = '\0'; - g_free (zOutput); - result_context_function_error (context, fn, zBuf); - return; - } - - /* Unaccenting is done in place */ - tracker_parser_unaccent_nfkd_string (zOutput, &nOutput); - - sqlite3_result_text16 (context, zOutput, nOutput * sizeof (gunichar2), g_free); -} - -#endif - static void function_sparql_encode_for_uri (sqlite3_context *context, int argc, diff --git a/src/libtracker-sparql/core/tracker-db-manager.c b/src/libtracker-sparql/core/tracker-db-manager.c index cb4318727..cebf1fe5b 100644 --- a/src/libtracker-sparql/core/tracker-db-manager.c +++ b/src/libtracker-sparql/core/tracker-db-manager.c @@ -22,6 +22,7 @@ #include <fcntl.h> #include <glib/gstdio.h> +#include <locale.h> #include <libtracker-common/tracker-common.h> #include <libtracker-common/tracker-parser.h> @@ -335,11 +336,11 @@ tracker_db_manager_locale_changed (TrackerDBManager *db_manager, GError **error) { gchar *db_locale; - gchar *current_locale; + const gchar *current_locale; gboolean changed; /* Get current collation locale */ - current_locale = tracker_locale_get (TRACKER_LOCALE_COLLATE); + current_locale = setlocale (LC_COLLATE, NULL); /* Get db locale */ db_locale = db_get_locale (db_manager); @@ -361,7 +362,6 @@ tracker_db_manager_locale_changed (TrackerDBManager *db_manager, } g_free (db_locale); - g_free (current_locale); return changed; } @@ -369,13 +369,12 @@ tracker_db_manager_locale_changed (TrackerDBManager *db_manager, void tracker_db_manager_set_current_locale (TrackerDBManager *db_manager) { - gchar *current_locale; + const gchar *current_locale; /* Get current collation locale */ - current_locale = tracker_locale_get (TRACKER_LOCALE_COLLATE); + current_locale = setlocale (LC_COLLATE, NULL); g_debug ("Saving DB locale as: '%s'", current_locale); db_set_locale (db_manager, current_locale); - g_free (current_locale); } static void diff --git a/src/libtracker-sparql/core/tracker-fts-tokenizer.c b/src/libtracker-sparql/core/tracker-fts-tokenizer.c index 66f68a069..e9dac1efa 100644 --- a/src/libtracker-sparql/core/tracker-fts-tokenizer.c +++ b/src/libtracker-sparql/core/tracker-fts-tokenizer.c @@ -38,7 +38,6 @@ typedef struct TrackerTokenizer TrackerTokenizer; typedef struct TrackerTokenizerFunctionData TrackerTokenizerFunctionData; struct TrackerTokenizerData { - TrackerLanguage *language; TrackerDBManagerFlags flags; }; @@ -65,7 +64,7 @@ tracker_tokenizer_create (void *data, tokenizer = g_new0 (TrackerTokenizer, 1); tokenizer->data = data; - tokenizer->parser = tracker_parser_new (tokenizer->data->language); + tokenizer->parser = tracker_parser_new (); *tokenizer_out = (Fts5Tokenizer *) tokenizer; @@ -159,7 +158,6 @@ tracker_tokenizer_data_new (TrackerDBManagerFlags flags) TrackerTokenizerData *p; p = g_new0 (TrackerTokenizerData, 1); - p->language = tracker_language_new (NULL); p->flags = flags; return p; @@ -170,7 +168,6 @@ tracker_tokenizer_data_free (gpointer user_data) { TrackerTokenizerData *data = user_data; - g_object_unref (data->language); g_free (data); } diff --git a/src/libtracker-sparql/direct/tracker-direct.c b/src/libtracker-sparql/direct/tracker-direct.c index 2e70a3513..c44254bcb 100644 --- a/src/libtracker-sparql/direct/tracker-direct.c +++ b/src/libtracker-sparql/direct/tracker-direct.c @@ -489,8 +489,6 @@ tracker_direct_connection_initable_init (GInitable *initable, conn = TRACKER_DIRECT_CONNECTION (initable); priv = tracker_direct_connection_get_instance_private (conn); - tracker_locale_sanity_check (); - if (!set_up_thread_pools (conn, error)) return FALSE; diff --git a/src/libtracker-sparql/meson.build b/src/libtracker-sparql/meson.build index 157ebccd2..cc236806e 100644 --- a/src/libtracker-sparql/meson.build +++ b/src/libtracker-sparql/meson.build @@ -11,7 +11,7 @@ version_header = configure_file( configuration: conf) enum_types = gnome.mkenums('tracker-sparql-enum-types', - sources: ['tracker-notifier.h', 'tracker-connection.h', 'tracker-enums.h'], + sources: ['tracker-notifier.h', 'tracker-connection.h', 'tracker-enums.h', 'tracker-error.h'], c_template: 'tracker-sparql-enum-types.c.template', h_template: 'tracker-sparql-enum-types.h.template', install_dir: join_paths(get_option('prefix'), get_option('includedir'), 'tracker-@0@'.format(tracker_api_version), 'libtracker-sparql'), @@ -169,6 +169,8 @@ if get_option('introspection').enabled() libtracker_sparql_sources, libtracker_sparql_public_headers, introspection_extra_sources, + version_header, + enum_types, ], dependencies: introspection_extra_deps, nsversion: tracker_api_version, diff --git a/src/libtracker-sparql/tracker-batch.c b/src/libtracker-sparql/tracker-batch.c index 3a20e27a5..38c074fd2 100644 --- a/src/libtracker-sparql/tracker-batch.c +++ b/src/libtracker-sparql/tracker-batch.c @@ -19,30 +19,27 @@ * Author: Carlos Garnacho <carlosg@gnome.org> */ /** - * SECTION: tracker-batch - * @short_description: Update batches - * @title: TrackerBatch - * @stability: Stable - * @include: tracker-sparql.h - * - * #TrackerBatch is an object containing a series of SPARQL updates, - * in either SPARQL string or #TrackerResource form. This object has - * a single use, after the batch is executed, it can only be finished - * and freed. - * - * A batch is created with tracker_sparql_connection_create_batch(). - * To add resources use tracker_batch_add_resource() or - * tracker_batch_add_sparql(). - * - * When a batch is ready for execution, use tracker_batch_execute() - * or tracker_batch_execute_async(). The batch is executed as a single + * TrackerBatch: + * + * `TrackerBatch` executes a series of SPARQL updates and RDF data + * insertions within a transaction. + * + * A batch is created with [method@Tracker.SparqlConnection.create_batch]. + * To add resources use [method@Tracker.Batch.add_resource], + * [method@Tracker.Batch.add_sparql] or [method@Batch.add_statement]. + * + * When a batch is ready for execution, use [method@Tracker.Batch.execute] + * or [method@Tracker.Batch.execute_async]. The batch is executed as a single * transaction, it will succeed or fail entirely. * - * The mapping of blank node labels is global in a #TrackerBatch, + * This object has a single use, after the batch is executed it can + * only be finished and freed. + * + * The mapping of blank node labels is global in a `TrackerBatch`, * referencing the same blank node label in different operations in * a batch will resolve to the same resource. * - * This object was added in Tracker 3.1. + * Since: 3.1 */ #include "config.h" @@ -133,7 +130,7 @@ tracker_batch_class_init (TrackerBatchClass *klass) /** * TrackerBatch:connection: * - * The #TrackerSparqlConnection the batch belongs to. + * The [class@Tracker.SparqlConnection] the batch belongs to. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -150,9 +147,10 @@ tracker_batch_class_init (TrackerBatchClass *klass) /** * tracker_batch_get_connection: - * @batch: a #TrackerBatch + * @batch: A `TrackerBatch` * - * Returns the #TrackerSparqlConnection that this batch was created from. + * Returns the [class@Tracker.SparqlConnection] that this batch was created + * from. * * Returns: (transfer none): The SPARQL connection of this batch. **/ @@ -168,8 +166,8 @@ tracker_batch_get_connection (TrackerBatch *batch) /** * tracker_batch_add_sparql: - * @batch: a #TrackerBatch - * @sparql: a SPARQL update string + * @batch: A `TrackerBatch` + * @sparql: A SPARQL update string * * Adds an SPARQL update string to @batch. * @@ -190,9 +188,9 @@ tracker_batch_add_sparql (TrackerBatch *batch, /** * tracker_batch_add_resource: - * @batch: a #TrackerBatch + * @batch: A `TrackerBatch` * @graph: (nullable): RDF graph to insert the resource to - * @resource: a #TrackerResource + * @resource: A [class@Tracker.Resource] * * Adds the RDF represented by @resource to @batch. * @@ -214,17 +212,18 @@ tracker_batch_add_resource (TrackerBatch *batch, /** * tracker_batch_add_statement: (skip): - * @batch: a #TrackerBatch - * @stmt: a #TrackerSparqlStatement containing a SPARQL update - * @...: parameters bound to @stmt, in triples of name/type/value + * @batch: a `TrackerBatch` + * @stmt: a [class@Tracker.SparqlStatement] containing a SPARQL update + * @...: NULL-terminated list of parameters bound to @stmt, in triplets of name, type and value. * - * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will + * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will * be executed once in the batch, with the parameters bound as specified in the * variable arguments. * - * The variable arguments are a NULL terminated set of variable name, value GType, - * and actual value. For example, for a statement that has a single `~name` parameter, - * it could be given a value for execution with the given code: + * The variable arguments are a NULL terminated set of variable name, type [type@GObject.Type], + * and value. The value C type must correspond to the given [type@GObject.Type]. For example, for + * a statement that has a single `~name` parameter, it could be given a value for execution + * with the following code: * * ```c * tracker_batch_add_statement (batch, stmt, @@ -232,13 +231,13 @@ tracker_batch_add_resource (TrackerBatch *batch, * NULL); * ``` * - * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement() - * calls with the same or different values, on the same or different #TrackerBatch + * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement] + * calls with the same or different values, on the same or different `TrackerBatch` * objects. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on [class@Tracker.SparqlStatement] objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource]. * * Since: 3.5 **/ @@ -295,22 +294,20 @@ tracker_batch_add_statement (TrackerBatch *batch, /** * tracker_batch_add_statementv: (rename-to tracker_batch_add_statement) - * @batch: a #TrackerBatch - * @stmt: a #TrackerSparqlStatement containing a SPARQL update - * @n_values: the number of bound parameters - * @variable_names: (array length=n_values): the names of each bound parameter - * @values: (array length=n_values): the values of each bound parameter + * @batch: A `TrackerBatch` + * @stmt: A [class@Tracker.SparqlStatement] containing a SPARQL update + * @n_values: The number of bound parameters + * @variable_names: (array length=n_values): The names of each bound parameter + * @values: (array length=n_values): The values of each bound parameter * - * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will + * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will * be executed once in the batch, with the values bound as specified by @variable_names * and @values. * * For example, for a statement that has a single `~name` parameter, * it could be given a value for execution with the given code: * - * <div class="gi-lang-c"><pre><code class="language-c"> - * - * ``` + * ```c * const char *names = { "name" }; * const GValue values[G_N_ELEMENTS (names)] = { 0, }; * @@ -320,29 +317,20 @@ tracker_batch_add_statement (TrackerBatch *batch, * G_N_ELEMENTS (names), * names, values); * ``` - * </code></pre></div> - * - * <div class="gi-lang-python"><pre><code class="language-python"> - * - * ``` + * ```python * batch.add_statement(stmt, ['name'], ['John Smith']); * ``` - * </code></pre></div> - * - * <div class="gi-lang-javascript"><pre><code class="language-javascript"> - * - * ``` + * ```js * batch.add_statement(stmt, ['name'], ['John Smith']); * ``` - * </code></pre></div> * - * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement() - * calls with the same or different values, on the same or different #TrackerBatch + * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement] + * calls with the same or different values, on the same or different `TrackerBatch` * objects. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on [class@Tracker.SparqlStatement] objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource]. * * Since: 3.5 **/ @@ -366,9 +354,9 @@ tracker_batch_add_statementv (TrackerBatch *batch, /** * tracker_batch_execute: - * @batch: a #TrackerBatch - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: location for a #GError, or %NULL + * @batch: a `TrackerBatch` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Executes the batch. This operations happens synchronously. * @@ -394,11 +382,11 @@ tracker_batch_execute (TrackerBatch *batch, /** * tracker_batch_execute_async: - * @batch: a #TrackerBatch - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback + * @batch: A `TrackerBatch` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes the batch. This operation happens asynchronously, when * finished @callback will be executed. @@ -424,11 +412,11 @@ tracker_batch_execute_async (TrackerBatch *batch, /** * tracker_batch_execute_finish: - * @batch: a #TrackerBatch - * @res: a #GAsyncResult with the result of the operation - * @error: location for a #GError, or %NULL + * @batch: A `TrackerBatch` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the operation started with tracker_batch_execute_async(). + * Finishes the operation started with [method@Tracker.Batch.execute_async]. * * Returns: %TRUE of there were no errors, %FALSE otherwise * diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c index 017ac88eb..600367894 100644 --- a/src/libtracker-sparql/tracker-connection.c +++ b/src/libtracker-sparql/tracker-connection.c @@ -18,43 +18,67 @@ */ /** - * SECTION: tracker-sparql-connection - * @short_description: Connection to SPARQL triple store - * @title: TrackerSparqlConnection - * @stability: Stable - * @include: tracker-sparql.h - * - * #TrackerSparqlConnection is an object that represents a connection to a - * SPARQL triple store. This store may be local and private (see - * tracker_sparql_connection_new()), or it may be a remote connection to a - * public endpoint (See tracker_sparql_connection_bus_new() and - * tracker_sparql_connection_remote_new()). - * - * A #TrackerSparqlConnection is private to the calling process, it can be - * exposed publicly via a #TrackerEndpoint, see tracker_endpoint_dbus_new(). - * - * Updates on a connection are performed via the tracker_sparql_connection_update() - * family of calls. tracker_sparql_connection_update_array() may be used for batched - * updates. All functions have asynchronous variants. - * - * Queries on a connection are performed via tracker_sparql_connection_query() - * and tracker_sparql_connection_query_statement(). The first call receives a - * query string and returns a #TrackerSparqlCursor to iterate the results. The - * second call returns a #TrackerSparqlStatement object that may be reused for - * repeatable queries with variable parameters. tracker_sparql_statement_execute() - * will returns a #TrackerSparqlCursor. - * - * Depending on the ontology definition, #TrackerSparqlConnection may emit - * notifications whenever changes happen in the stored data. These notifications - * can be processed via a #TrackerNotifier obtained with - * tracker_sparql_connection_create_notifier(). - * - * After use, a #TrackerSparqlConnection should be closed. See - * tracker_sparql_connection_close() and tracker_sparql_connection_close_async(). - * - * A #TrackerSparqlConnection may be used from multiple threads, asynchronous - * database updates are executed sequentially on arrival order, asynchronous - * queries are executed in a thread pool. + * TrackerSparqlConnection: + * + * `TrackerSparqlConnection` holds a connection to a RDF triple store. + * + * This triple store may be of three types: + * + * - Local to the process, created through [ctor@Tracker.SparqlConnection.new]. + * - A HTTP SPARQL endpoint over the network, created through + * [ctor@Tracker.SparqlConnection.remote_new] + * - A DBus SPARQL endpoint owned by another process in the same machine, created + * through [ctor@Tracker.SparqlConnection.bus_new] + * + * When creating a local triple store, it is required to give details about its + * structure. This is done by passing a location to an ontology, see more + * on how are [ontologies defined](ontologies.html). A local database may be + * stored in a filesystem location, or it may reside in memory. + * + * A `TrackerSparqlConnection` is private to the calling process, it can be + * exposed to other hosts/processes via a [class@Tracker.Endpoint], see + * [ctor@Tracker.EndpointDBus.new] and [ctor@Tracker.EndpointHttp.new]. + * + * When issuing SPARQL queries and updates, it is recommended that these are + * created through [class@Tracker.SparqlStatement] to avoid the SPARQL + * injection class of bugs, see [method@Tracker.SparqlConnection.query_statement] + * and [method@Tracker.SparqlConnection.update_statement]. For SPARQL updates + * it is also possible to use a "builder" approach to generate RDF data, see + * [class@Tracker.Resource]. It is also possible to create [class@Tracker.SparqlStatement] + * objects for SPARQL queries and updates from SPARQL strings embedded in a + * [struct@Gio.Resource], see [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * + * To get the best performance, it is recommended that SPARQL updates are clustered + * through [class@Tracker.Batch]. + * + * `TrackerSparqlConnection` also offers a number of methods for the simple cases, + * [method@Tracker.SparqlConnection.query] may be used when there is a SPARQL + * query string directly available, and the [method@Tracker.SparqlConnection.update] + * family of functions may be used for one-off updates. All functions have asynchronous + * variants. + * + * When a SPARQL query is executed, a [class@Tracker.SparqlCursor] will be obtained + * to iterate over the query results. + * + * Depending on the ontology definition, `TrackerSparqlConnection` may emit + * notifications whenever resources of certain types get insert, modified or + * deleted from the triple store (see [nrl:notify](nrl-ontology.html#nrl:notify). + * These notifications can be handled via a [class@Tracker.Notifier] obtained with + * [method@Tracker.SparqlConnection.create_notifier]. + * + * After done with a connection, it is recommended to call [method@Tracker.SparqlConnection.close] + * or [method@Tracker.SparqlConnection.close_async] explicitly to cleanly close the + * connection and prevent consistency checks on future runs. The triple store + * connection will be implicitly closed when the `TrackerSparqlConnection` object + * is disposed. + * + * A `TrackerSparqlConnection` may be used from multiple threads, asynchronous + * updates are executed sequentially on arrival order, asynchronous + * queries are dispatched in a thread pool. + * + * If you ever have the need to procedurally compose SPARQL query strings, consider + * the use of [func@Tracker.sparql_escape_string] for literal strings and + * the [func@Tracker.sparql_escape_uri] family of functions for URIs. */ #include "config.h" @@ -118,21 +142,25 @@ tracker_sparql_connection_lookup_dbus_service (TrackerSparqlConnection *connect /** * tracker_sparql_connection_query: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes a SPARQL query on. The API call is completely synchronous, so - * it may block. + * Executes a SPARQL query on @connection. * - * The @sparql query should be built with #TrackerResource, or - * its parts correctly escaped using tracker_sparql_escape_string(), - * otherwise SPARQL injection is possible. + * This method is synchronous and will block until the query + * is executed. See [method@Tracker.SparqlConnection.query_async] + * for an asynchronous variant. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. * - * Returns: (transfer full): a #TrackerSparqlCursor if results were found. - * On error, #NULL is returned and the @error is set accordingly. - * Call g_object_unref() on the returned cursor when no longer needed. + * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results. */ TrackerSparqlCursor * tracker_sparql_connection_query (TrackerSparqlConnection *connection, @@ -159,14 +187,21 @@ tracker_sparql_connection_query (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_query_async: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL query - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback - * - * Executes asynchronously a SPARQL query. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Executes asynchronously a SPARQL query on @connection + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_query_async (TrackerSparqlConnection *connection, @@ -188,15 +223,13 @@ tracker_sparql_connection_query_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_query_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL query operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.query_async]. * - * Returns: (transfer full): a #TrackerSparqlCursor if results were found. - * On error, #NULL is returned and the @error is set accordingly. - * Call g_object_unref() on the returned cursor when no longer needed. + * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results. */ TrackerSparqlCursor * tracker_sparql_connection_query_finish (TrackerSparqlConnection *connection, @@ -220,17 +253,28 @@ tracker_sparql_connection_query_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. - * - * Executes a SPARQL update. The API call is completely - * synchronous, so it may block. - * - * The @sparql query should be built with #TrackerResource, or - * its parts correctly escaped using tracker_sparql_escape_string(), - * otherwise SPARQL injection is possible. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Executes a SPARQL update on @connection. + * + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_async] + * for an asynchronous variant. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update (TrackerSparqlConnection *connection, @@ -251,14 +295,26 @@ tracker_sparql_connection_update (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_async: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes asynchronously a SPARQL update. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update_async (TrackerSparqlConnection *connection, @@ -280,11 +336,11 @@ tracker_sparql_connection_update_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL update operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_async]. */ void tracker_sparql_connection_update_finish (TrackerSparqlConnection *connection, @@ -302,16 +358,24 @@ tracker_sparql_connection_update_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_array_async: - * @connection: a #TrackerSparqlConnection - * @sparql: an array of strings containing the SPARQL update queries - * @sparql_length: the amount of strings you pass as @sparql - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback + * @connection: A `TrackerSparqlConnection` + * @sparql: An array of strings containing the SPARQL update queries + * @sparql_length: The amount of strings you pass as @sparql + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes asynchronously an array of SPARQL updates. All updates in the * array are handled within a single transaction. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update_array_async (TrackerSparqlConnection *connection, @@ -335,11 +399,11 @@ tracker_sparql_connection_update_array_async (TrackerSparqlConnection *connecti /** * tracker_sparql_connection_update_array_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL update_array operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_array_async]. * * Returns: #TRUE if there were no errors. */ @@ -360,16 +424,19 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection *connect /** * tracker_sparql_connection_update_blank: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Executes a SPARQL update and returns the names of the generated blank nodes. * - * Executes a SPARQL update and returns the URNs of the generated nodes, - * if any. The API call is completely synchronous, so it may block. + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_blank_async] + * for an asynchronous variant. * - * The @sparql query should be built with #TrackerResource, or - * its parts correctly escaped using tracker_sparql_escape_string(), + * The @sparql query should be built with [class@Tracker.Resource], or + * its parts correctly escaped using [func@Tracker.sparql_escape_string], * otherwise SPARQL injection is possible. * * The format string of the `GVariant` is `aaa{ss}` (an array of an array @@ -379,14 +446,13 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection *connect * (e.g. `foo` for the blank node `_:foo`) and the URN that was generated for * it. For most updates the first two outer arrays will only contain one item. * - * Returns: a #GVariant with the generated URNs, which should be freed with - * g_variant_unref() when no longer used. + * Returns: a [type@GLib.Variant] with the generated URNs. * * Deprecated: 3.5: This function makes the expectation that blank nodes have * a durable name that persist. The SPARQL and RDF specs define a much more * reduced scope for blank node labels. This function advises a behavior that * goes against that reduced scope, and will directly make the returned values - * meaningless if the %TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag + * meaningless if the #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag * is defined in the connection. * * Users that want names generated for them, should look for other methods @@ -411,18 +477,20 @@ tracker_sparql_connection_update_blank (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_blank_async: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback - * - * Executes asynchronously a SPARQL update with blank nodes. See - * the tracker_sparql_connection_update_blank() documentation to - * see the differences with tracker_sparql_connection_update(). - * - * Deprecated: 3.5: See tracker_sparql_connection_update_blank(). + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * + * Executes asynchronously a SPARQL update and returns the names of the generated blank nodes. + * + * See the [method@Tracker.SparqlConnection.update_blank] documentation to + * learn the differences with [method@Tracker.SparqlConnection.update]. + * + * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank]. */ void tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection, @@ -444,19 +512,19 @@ tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connectio /** * tracker_sparql_connection_update_blank_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location + * + * Finishes the operation started with [method@Tracker.SparqlConnection.update_blank_async]. * - * Finishes the asynchronous SPARQL update operation, and returns - * the URNs of the generated nodes, if any. See the - * tracker_sparql_connection_update_blank() documentation for the interpretation - * of the returned #GVariant. + * This method returns the URNs of the generated nodes, if any. See the + * [method@Tracker.SparqlConnection.update_blank] documentation for the interpretation + * of the returned [type@GLib.Variant]. * - * Returns: a #GVariant with the generated URNs, which should be freed with - * g_variant_unref() when no longer used. + * Returns: a [type@GLib.Variant] with the generated URNs. * - * Deprecated: 3.5: See tracker_sparql_connection_update_blank(). + * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank]. */ GVariant * tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection *connection, @@ -474,14 +542,21 @@ tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection *connect /** * tracker_sparql_connection_update_resource: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph - * @resource: a #TrackerResource - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError, or %NULL + * @resource: A [class@Tracker.Resource] + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Inserts a resource as described by @resource on the given @graph. * - * Inserts a resource as described by @resource, on the graph described by @graph. - * This operation blocks until done. + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_resource_async] + * for an asynchronous variant. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. * * Returns: #TRUE if there were no errors. * @@ -508,16 +583,19 @@ tracker_sparql_connection_update_resource (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_resource_async: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph - * @resource: a #TrackerResource - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @resource: A [class@Tracker.Resource] + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Inserts asynchronously a resource as described by @resource on the given @graph. * - * Inserts a resource as described by @resource, on the graph described by @graph. - * This operation is executed asynchronously, when finished @callback will be - * executed. + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. * * Since: 3.1 **/ @@ -544,11 +622,11 @@ tracker_sparql_connection_update_resource_async (TrackerSparqlConnection *connec /** * tracker_sparql_connection_update_resource_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: pointer to a #GError, or %NULL + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_update_resource_async() operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_resource_async]. * * Returns: #TRUE if there were no errors. * @@ -570,13 +648,12 @@ tracker_sparql_connection_update_resource_finish (TrackerSparqlConnection *conn /** * tracker_sparql_connection_get_namespace_manager: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * - * Retrieves a #TrackerNamespaceManager that contains all + * Returns a [class@Tracker.NamespaceManager] that contains all * prefixes in the ontology of @connection. * - * Returns: (transfer none): a #TrackerNamespaceManager for this - * connection. This object is owned by @connection and must not be freed. + * Returns: (transfer none): a [class@Tracker.NamespaceManager] with the prefixes of @connection. */ TrackerNamespaceManager * tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connection) @@ -593,16 +670,18 @@ tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connec /** * tracker_sparql_connection_query_statement: - * @connection: a #TrackerSparqlConnection - * @sparql: the SPARQL query - * @cancellable: a #GCancellable used to cancel the operation, or %NULL - * @error: a #TrackerSparqlError or %NULL if no error occured + * @connection: A `TrackerSparqlConnection` + * @sparql: The SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Prepares the given SELECT/DESCRIBE/CONSTRUCT @sparql as a #TrackerSparqlStatement. - * This prepared statement can be executed through tracker_sparql_statement_execute() - * or tracker_sparql_statement_serialize_async() families of functions. + * Prepares the given `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL query as a + * [class@Tracker.SparqlStatement]. * - * Returns: (transfer full) (nullable): a prepared statement + * This prepared statement can be executed through [method@Tracker.SparqlStatement.execute] + * or [method@Tracker.SparqlStatement.serialize_async] families of functions. + * + * Returns: (transfer full) (nullable): A prepared statement */ TrackerSparqlStatement * tracker_sparql_connection_query_statement (TrackerSparqlConnection *connection, @@ -623,16 +702,17 @@ tracker_sparql_connection_query_statement (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_statement: - * @connection: a #TrackerSparqlConnection - * @sparql: the SPARQL update - * @cancellable: a #GCancellable used to cancel the operation, or %NULL - * @error: a #TrackerSparqlError or %NULL if no error occured + * @connection: A `TrackerSparqlConnection` + * @sparql: The SPARQL update + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Prepares the given `INSERT`/`DELETE` SPARQL as a [class@Tracker.SparqlStatement]. * - * Prepares the given INSERT/DELETE/LOAD/CLEAR/DROP/ADD/MOVE/COPY/CREATE @sparql - * as a #TrackerSparqlStatement. This prepared statement can be executed through - * the tracker_sparql_statement_update() family of functions. + * This prepared statement can be executed through + * the [method@Tracker.SparqlStatement.update] family of functions. * - * Returns: (transfer full) (nullable): a prepared statement + * Returns: (transfer full) (nullable): A prepared statement * * Since: 3.5 */ @@ -658,35 +738,39 @@ tracker_sparql_connection_update_statement (TrackerSparqlConnection *connection /** * tracker_sparql_connection_create_notifier: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` + * + * Creates a new [class@Tracker.Notifier] to receive notifications about changes in @connection. * - * Creates a new #TrackerNotifier to notify about changes in @connection. - * See #TrackerNotifier documentation for information about how to use this + * See [class@Tracker.Notifier] documentation for information about how to use this * object. * - * Returns: (transfer full): a newly created notifier. Free with g_object_unref() - * when no longer needed. + * Connections to HTTP endpoints will return %NULL. + * + * Returns: (transfer full) (nullable): A newly created notifier. **/ TrackerNotifier * tracker_sparql_connection_create_notifier (TrackerSparqlConnection *connection) { g_return_val_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection), NULL); + if (!TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier) + return NULL; + return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier (connection); } /** * tracker_sparql_connection_close: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` + * + * Closes a SPARQL connection. * - * Closes a SPARQL connection. No other API calls than g_object_unref() - * should happen after this call. + * No other API calls than g_object_unref() should happen after this call. * * This call is blocking. All pending updates will be flushed, and the * store databases will be closed orderly. All ongoing SELECT queries * will be cancelled. Notifiers will no longer emit events. - * - * Since: 3.0 */ void tracker_sparql_connection_close (TrackerSparqlConnection *connection) @@ -698,17 +782,15 @@ tracker_sparql_connection_close (TrackerSparqlConnection *connection) /** * tracker_sparql_connection_close_async: - * @connection: a #TrackerSparqlConnection - * @cancellable: a #GCancellable, or %NULL - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. - * @user_data: user-defined data to be passed to @callback + * @connection: A `TrackerSparqlConnection` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Closes a connection asynchronously. No other API calls than g_object_unref() - * should happen after this call. See tracker_sparql_connection_close() for more - * information. + * Closes a SPARQL connection asynchronously. * - * Since: 3.0 + * No other API calls than g_object_unref() should happen after this call. **/ void tracker_sparql_connection_close_async (TrackerSparqlConnection *connection, @@ -726,15 +808,13 @@ tracker_sparql_connection_close_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_close_finish: - * @connection: a #TrackerSparqlConnection - * @res: the #GAsyncResult - * @error: pointer to a #GError + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous connection close. + * Finishes the operation started with [method@Tracker.SparqlConnection.close_async]. * * Returns: %FALSE if some error occurred, %TRUE otherwise - * - * Since: 3.0 **/ gboolean tracker_sparql_connection_close_finish (TrackerSparqlConnection *connection, @@ -749,12 +829,13 @@ tracker_sparql_connection_close_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_create_batch: - * @connection: a #TrackerSparqlConnection + * @connection: a `TrackerSparqlConnection` + * + * Creates a new [class@Tracker.Batch] to store and execute SPARQL updates. * - * Creates a new batch to store and execute update commands. If the connection - * is readonly or cannot issue SPARQL updates, %NULL will be returned. + * If the connection is readonly or cannot issue SPARQL updates, %NULL will be returned. * - * Returns: (transfer full): (nullable): A new #TrackerBatch + * Returns: (transfer full): (nullable): A new [class@Tracker.Batch] **/ TrackerBatch * tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection) @@ -769,15 +850,19 @@ tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection) /** * tracker_sparql_connection_load_statement_from_gresource: - * @connection: a #TrackerSparqlConnection - * @resource_path: the resource path of the file to parse. - * @cancellable: a #GCancellable, or %NULL - * @error: return location for an error, or %NULL + * @connection: A `TrackerSparqlConnection` + * @resource_path: The resource path of the file to parse. + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Prepares a [class@Tracker.SparqlStatement] for the SPARQL contained as a [struct@Gio.Resource] + * file at @resource_path. * - * Prepares a #TrackerSparqlStatement for the SPARQL query contained as a resource - * file at @resource_path. SPARQL Query files typically have the .rq extension. + * SPARQL Query files typically have the .rq extension. This will use + * [method@Tracker.SparqlConnection.query_statement] or [method@Tracker.SparqlConnection.update_statement] + * underneath to indistinctly return SPARQL query or update statements. * - * Returns: (transfer full) (nullable): a prepared statement + * Returns: (transfer full) (nullable): A prepared statement * * Since: 3.3 **/ @@ -830,17 +915,19 @@ tracker_sparql_connection_load_statement_from_gresource (TrackerSparqlConnection /** * tracker_sparql_connection_serialize_async: - * @connection: a #TrackerSparqlConnection - * @flags: serialization flags - * @format: output RDF format + * @connection: A `TrackerSparqlConnection` + * @flags: Serialization flags + * @format: Output RDF format * @query: SPARQL query - * @cancellable: a #GCancellable - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Serializes data into the specified RDF format. @query must be either a - * `DESCRIBE` or `CONSTRUCT` query. This is an asynchronous operation, - * @callback will be invoked when the data is available for reading. + * Serializes a `DESCRIBE` or `CONSTRUCT` query into the specified RDF format. + * + * This is an asynchronous operation, @callback will be invoked when + * the data is available for reading. * * The SPARQL endpoint may not support the specified format, in that case * an error will be raised. @@ -877,14 +964,13 @@ tracker_sparql_connection_serialize_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_serialize_finish: - * @connection: a #TrackerSparqlConnection - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @connection: A `TrackerSparqlConnection` + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_serialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the operation started with [method@Tracker.SparqlConnection.serialize_async]. * - * Returns: (transfer full): a #GInputStream to read RDF content. + * Returns: (transfer full): A [class@Gio.InputStream] to read RDF content. * * Since: 3.3 **/ @@ -904,22 +990,23 @@ tracker_sparql_connection_serialize_finish (TrackerSparqlConnection *connection /** * tracker_sparql_connection_deserialize_async: - * @connection: a #TrackerSparqlConnection - * @flags: deserialization flags + * @connection: A `TrackerSparqlConnection` + * @flags: Deserialization flags * @format: RDF format of data in stream - * @default_graph: default graph that will receive the RDF data - * @stream: input stream with RDF data - * @cancellable: a #GCancellable - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback - * - * Incorporates the contents of the RDF data contained in @stream into the - * data stored by @connection. This is an asynchronous operation, - * @callback will be invoked when the data has been fully inserted to - * @connection. - * - * RDF data will be inserted in the given @default_graph if one is provided, - * or the default graph if @default_graph is %NULL. Any RDF data that has a + * @default_graph: Default graph that will receive the RDF data + * @stream: Input stream with RDF data + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Loads the RDF data contained in @stream into the given @connection. + + * This is an asynchronous operation, @callback will be invoked when the + * data has been fully inserted to @connection. + * + * The RDF data will be inserted in the given @default_graph if one is provided, + * or the anonymous graph if @default_graph is %NULL. Any RDF data that has a * graph specified (e.g. using the `GRAPH` clause in the Trig format) will * be inserted in the specified graph instead of @default_graph. * @@ -957,12 +1044,11 @@ tracker_sparql_connection_deserialize_async (TrackerSparqlConnection *connection /** * tracker_sparql_connection_deserialize_finish: - * @connection: a #TrackerSparqlConnection - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @connection: A `TrackerSparqlConnection` + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_deserialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the operation started with [method@Tracker.SparqlConnection.deserialize_async]. * * Returns: %TRUE if all data was inserted successfully. * @@ -984,14 +1070,21 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection *connecti /** * tracker_sparql_connection_map_connection: - * @connection: a #TrackerSparqlConnection - * @handle_name: handle name for @service_connection - * @service_connection: a #TrackerSparqlConnection to use from @connection + * @connection: A `TrackerSparqlConnection` + * @handle_name: Handle name for @service_connection + * @service_connection: a `TrackerSparqlConnection` to use from @connection + * + * Maps a `TrackerSparqlConnection` onto another through a `private:@handle_name` URI. * - * Maps @service_connection so it is available as a "private:@handle_name" URI - * in @connection. This can be accessed via the SERVICE SPARQL syntax in + * This can be accessed via the SERVICE SPARQL syntax in * queries from @connection. E.g.: * + * ```c + * tracker_sparql_connection_map_connection (connection, + * "other-connection", + * other_connection); + * ``` + * * ```sparql * SELECT ?u { * SERVICE <private:other-connection> { @@ -1001,11 +1094,11 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection *connecti * ``` * * This is useful to interrelate data from multiple - * #TrackerSparqlConnection instances maintained by the same process, + * `TrackerSparqlConnection` instances maintained by the same process, * without creating a public endpoint for @service_connection. * - * @connection may only be a #TrackerSparqlConnection created via - * tracker_sparql_connection_new() and tracker_sparql_connection_new_async(). + * @connection may only be a `TrackerSparqlConnection` created via + * [ctor@Tracker.SparqlConnection.new] and [func@Tracker.SparqlConnection.new_async]. * * Since: 3.3 **/ @@ -1030,11 +1123,12 @@ tracker_sparql_connection_map_connection (TrackerSparqlConnection *connection, * tracker_sparql_connection_remote_new: * @uri_base: Base URI of the remote connection * - * Connects to a remote SPARQL endpoint. The connection is made using the libsoup - * HTTP library. The connection will normally use the http:// or https:// protocol. + * Creates a connection to a remote HTTP SPARQL endpoint. + * + * The connection is made using the libsoup HTTP library. The connection will + * normally use the `https://` or `http://` protocols. * - * Returns: (transfer full): a new remote #TrackerSparqlConnection. Call - * g_object_unref() on the object when no longer used. + * Returns: (transfer full): a new remote `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_remote_new (const gchar *uri_base) @@ -1044,39 +1138,47 @@ tracker_sparql_connection_remote_new (const gchar *uri_base) /** * tracker_sparql_connection_new: - * @flags: values from #TrackerSparqlConnectionFlags - * @store: (nullable): the directory that contains the database as a #GFile, or %NULL - * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @flags: Connection flags to define the SPARQL connection behavior + * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL + * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Creates or opens a database. + * Creates or opens a process-local database. * * This method should only be used for databases owned by the current process. * To connect to databases managed by other processes, use - * tracker_sparql_connection_bus_new(). + * [ctor@Tracker.SparqlConnection.bus_new]. * * If @store is %NULL, the database will be created in memory. * - * The @ontologies parameter must point to a location containing suitable - * `.ontology` files in Turtle format. These control the database schema that - * is used. You can use the default Nepomuk ontologies by calling - * tracker_sparql_get_ontology_nepomuk (). - * - * If you open an existing database using a different @ontology to the one it - * was created with, Tracker will attempt to migrate the existing data to the - * new schema. This may raise an error. In particular, not all migrations are - * possible without causing data loss and Tracker will refuse to delete data - * during a migration. - * - * You can also pass %NULL for @ontologies to mean "use the ontologies that the - * database was created with". This will fail if the database doesn't already - * exist. - * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call - * g_object_unref() on the object when no longer used. - * - * Since: 3.0 + * If defined, the @ontology argument must point to a location containing + * suitable `.ontology` files in Turtle format. These define the structure of + * the triple store. You can learn more about [ontologies](ontologies.html), + * or you can use the stock Nepomuk ontologies by calling + * [func@Tracker.sparql_get_ontology_nepomuk]. + * + * If opening an existing database, it is possible to pass %NULL as the + * @ontology location, the ontology will be introspected from the database. + * Passing a %NULL @ontology will raise an error if the database does not exist. + * + * If a database is opened without the #TRACKER_SPARQL_CONNECTION_FLAG_READONLY + * flag enabled, and the given @ontology holds differences with the current + * data layout, migration to the new structure will be attempted. This operation + * may raise an error. In particular, not all migrations are possible without + * causing data loss and Tracker will refuse to delete data during a migration. + * The database is always left in a consistent state, either prior or posterior + * to migration. + * + * It is considered a developer error to ship ontologies that contain format + * errors, or that fail at migrations. + * + * It is encouraged to use `resource:///` URI locations for @ontology wherever + * possible, so the triple store structure is tied to the executable binary, + * and in order to minimize disk seeks during `TrackerSparqlConnection` + * initialization. + * + * Returns: (transfer full): a new `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_new (TrackerSparqlConnectionFlags flags, @@ -1112,16 +1214,17 @@ new_async_cb (GObject *source, /** * tracker_sparql_connection_new_async: - * @flags: values from #TrackerSparqlConnectionFlags - * @store: (nullable): the directory that contains the database as a #GFile, or %NULL - * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @flags: Connection flags to define the SPARQL connection behavior + * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL + * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Asynchronous version of tracker_sparql_connection_new(). + * Creates or opens a process-local database asynchronously. * - * Since: 3.0 + * See [ctor@Tracker.SparqlConnection.new] for more information. */ void @@ -1147,12 +1250,10 @@ tracker_sparql_connection_new_async (TrackerSparqlConnectionFlags flags, /** * tracker_sparql_connection_new_finish: - * @result: the #GAsyncResult - * @error: pointer to a #GError - * - * Completion function for tracker_sparql_connection_new_async(). + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Since: 3.0 + * Finishes the operation started with [func@Tracker.SparqlConnection.new_async]. */ TrackerSparqlConnection * tracker_sparql_connection_new_finish (GAsyncResult *res, @@ -1170,16 +1271,13 @@ tracker_sparql_connection_new_finish (GAsyncResult *res, * tracker_sparql_connection_bus_new: * @service_name: The name of the D-Bus service to connect to. * @object_path: (nullable): The path to the object, or %NULL to use the default. - * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus - * @error: pointer to a #GError + * @dbus_connection: (nullable): The [type@Gio.DBusConnection] to use, or %NULL to use the session bus + * @error: Error location * * Connects to a database owned by another process on the - * local machine. + * local machine via DBus. * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the - * object when no longer used. - * - * Since: 3.0 + * Returns: (transfer full): a new `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_bus_new (const gchar *service, @@ -1220,13 +1318,14 @@ bus_new_cb (GObject *source, * tracker_sparql_connection_bus_new_async: * @service_name: The name of the D-Bus service to connect to. * @object_path: (nullable): The path to the object, or %NULL to use the default. - * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @dbus_connection: (nullable): The [class@Gio.DBusConnection] to use, or %NULL to use the session bus + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Connects to a database owned by another process on the - * local machine. This is an asynchronous operation. + * Connects asynchronously to a database owned by another process on the + * local machine via DBus. * * Since: 3.1 */ @@ -1257,13 +1356,12 @@ tracker_sparql_connection_bus_new_async (const gchar *service, /** * tracker_sparql_connection_bus_new_finish: - * @result: the #GAsyncResult - * @error: pointer to a #GError + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Completion function for tracker_sparql_connection_bus_new_async(). + * Finishes the operation started with [func@Tracker.SparqlConnection.bus_new_async]. * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the - * object when no longer used. + * Returns: (transfer full): a new `TrackerSparqlConnection`. * * Since: 3.1 */ diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h index d0923c9cd..f31c37890 100644 --- a/src/libtracker-sparql/tracker-connection.h +++ b/src/libtracker-sparql/tracker-connection.h @@ -55,6 +55,12 @@ typedef enum { TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES = 1 << 5, } TrackerSparqlConnectionFlags; +/** + * TrackerSerializeFlags: + * @TRACKER_SERIALIZE_FLAGS_NONE: No flags. + * + * Flags affecting serialization into a RDF data format. + */ typedef enum { TRACKER_SERIALIZE_FLAGS_NONE = 0, } TrackerSerializeFlags; @@ -63,18 +69,12 @@ typedef enum { * TrackerDeserializeFlags: * @TRACKER_DESERIALIZE_FLAGS_NONE: No flags. * - * Flags affecting deserialization of RDF. + * Flags affecting deserialization from a RDF data format. */ typedef enum { TRACKER_DESERIALIZE_FLAGS_NONE = 0, } TrackerDeserializeFlags; -/** - * TrackerSparqlConnection: - * - * The <structname>TrackerSparqlConnection</structname> object represents a - * SPARQL connection. - */ #define TRACKER_TYPE_SPARQL_CONNECTION tracker_sparql_connection_get_type () #define TRACKER_SPARQL_TYPE_CONNECTION TRACKER_TYPE_SPARQL_CONNECTION diff --git a/src/libtracker-sparql/tracker-cursor.c b/src/libtracker-sparql/tracker-cursor.c index d7eb83685..42a531aeb 100644 --- a/src/libtracker-sparql/tracker-cursor.c +++ b/src/libtracker-sparql/tracker-cursor.c @@ -17,16 +17,31 @@ * Boston, MA 02110-1301, USA. */ /** - * SECTION: tracker-sparql-cursor - * @short_description: Iteration of the query results - * @title: TrackerSparqlCursor - * @stability: Stable - * @include: tracker-sparql.h + * TrackerSparqlCursor: * - * #TrackerSparqlCursor is an object which provides methods to iterate the - * results of a query to the Tracker Store. + * `TrackerSparqlCursor` provides the methods to iterate the results of a SPARQL query. * - * It is possible to use a given #TrackerSparqlCursor in other threads than + * Cursors are obtained through e.g. [method@Tracker.SparqlStatement.execute] + * or [method@Tracker.SparqlConnection.query] after the SPARQL query has been + * executed. + * + * When created, a cursor does not point to any element, [method@Tracker.SparqlCursor.next] + * is necessary to iterate one by one to the first (and following) results. + * When the cursor iterated across all rows in the result set, [method@Tracker.SparqlCursor.next] + * will return %FALSE with no error set. + * + * On each row, it is possible to extract the result values through the + * [method@Tracker.SparqlCursor.get_integer], [method@Tracker.SparqlCursor.get_string], etc... family + * of methods. The column index of those functions starts at 0. The number of columns is + * dependent on the SPARQL query issued, but may be checked at runtime through the + * [method@Tracker.SparqlCursor.get_n_columns] method. + * + * After a cursor is iterated, it is recommended to call [method@Tracker.SparqlCursor.close] + * explicitly to free up resources for other users of the same [class@Tracker.SparqlConnection], + * this is especially important in garbage collected languages. These resources + * will be also implicitly freed on cursor object finalization. + * + * It is possible to use a given `TrackerSparqlCursor` in other threads than * the one it was created from. It must be however used from just one thread * at any given time. */ @@ -187,7 +202,7 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) /** * TrackerSparqlCursor:connection: * - * The #TrackerSparqlConnection used to retrieve the results. + * The [class@Tracker.SparqlConnection] used to retrieve the results. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -199,9 +214,9 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) G_PARAM_READABLE | G_PARAM_WRITABLE); /** - * TrackerSparqlCursor:n_columns: + * TrackerSparqlCursor:n-columns: * - * Number of columns available in the results to iterate. + * Number of columns available in the result set. */ props[PROP_N_COLUMNS] = g_param_spec_int ("n-columns", @@ -216,12 +231,12 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) /** * tracker_sparql_cursor_get_connection: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * - * Returns the #TrackerSparqlConnection associated with this - * #TrackerSparqlCursor. + * Returns the [class@Tracker.SparqlConnection] associated with this + * `TrackerSparqlCursor`. * - * Returns: (transfer none): the cursor #TrackerSparqlConnection. The + * Returns: (transfer none): the cursor [class@Tracker.SparqlConnection]. The * returned object must not be unreferenced by the caller. */ TrackerSparqlConnection * @@ -248,14 +263,15 @@ tracker_sparql_cursor_set_connection (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_n_columns: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` + * + * Retrieves the number of columns available in the result set. * * This method should only be called after a successful - * tracker_sparql_cursor_next(); otherwise its return value + * [method@Tracker.SparqlCursor.next], otherwise its return value * will be undefined. * - * Returns: a #gint representing the number of columns available in the - * results to iterate. + * Returns: The number of columns returned in the result set. */ gint tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor) @@ -267,15 +283,19 @@ tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor) /** * tracker_sparql_cursor_get_string: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * @length: (out) (nullable): length of the returned string, or %NULL * * Retrieves a string representation of the data in the current * row in @column. * + * Any type may be converted to a string. If the value is not bound + * (See [method@Tracker.SparqlCursor.is_bound]) this method will return %NULL. + * * Returns: (nullable): a string which must not be freed. %NULL is returned if - * the column is not in the [0,#n_columns] range. + * the column is not in the `[0, n_columns]` range, or if the row/column + * refer to a nullable optional value in the result set. */ const gchar * tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor, @@ -291,12 +311,15 @@ tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_boolean: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve a boolean for the current row in @column. * - * Returns: a #gboolean. + * If the row/column do not have a boolean value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a boolean value. */ gboolean tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor, @@ -310,12 +333,15 @@ tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_double: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve a double for the current row in @column. * - * Returns: a double. + * If the row/column do not have a integer or double value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a double value. */ gdouble tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor, @@ -329,12 +355,15 @@ tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_integer: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve an integer for the current row in @column. * - * Returns: a #gint64. + * If the row/column do not have an integer value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a 64-bit integer value. */ gint64 tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor, @@ -348,12 +377,23 @@ tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_value_type: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * The data type bound to the current row in @column is returned. + * Returns the data type bound to the current row and the given @column. + * + * If the column is unbound, the value will be %TRACKER_SPARQL_VALUE_TYPE_UNBOUND. + * See also [method@Tracker.SparqlCursor.is_bound]. * - * Returns: a #TrackerSparqlValueType. + * Values of type #TRACKER_SPARQL_VALUE_TYPE_RESOURCE and + * #TRACKER_SPARQL_VALUE_TYPE_BLANK_NODE can be considered equivalent, the + * difference is the resource being referenced as a named IRI or a blank + * node. + * + * All other [enum@Tracker.SparqlValueType] value types refer to literal values. + * + * Returns: a [enum@Tracker.SparqlValueType] expressing the content type of + * the given column for the current row. */ TrackerSparqlValueType tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor, @@ -368,12 +408,17 @@ tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_variable_name: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * Retrieves the variable name for the current row in @column. + * Retrieves the name of the given @column. + * + * This name will be defined at the SPARQL query, either + * implicitly from the names of the variables returned in + * the resultset, or explicitly through the `AS ?var` SPARQL + * syntax. * - * Returns: a string which must not be freed. + * Returns: (nullable): The name of the given column. */ const gchar * tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor, @@ -387,12 +432,14 @@ tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_datetime: - * @cursor: a #TrackerSparqlCursor - * @column: column number to retrieve (first one is 0) + * @cursor: a `TrackerSparqlCursor` + * @column: Column number to retrieve (first one is 0) + * + * Retrieves a [type@GLib.DateTime] pointer for the current row in @column. * - * Retrieve an GDateTime pointer for the current row in @column. + * Returns: (transfer full) (nullable): [type@GLib.DateTime] object, or %NULL if the given column does not + * contain a [xsd:date](xsd-ontology.html#xsd:date) or [xsd:dateTime](xsd-ontology.html#xsd:dateTime). * - * Returns: (transfer full) (nullable): #GDateTime object, or %NULL if the given column does not contain a xsd:date or xsd:dateTime * Since: 3.2 */ GDateTime * @@ -407,9 +454,9 @@ tracker_sparql_cursor_get_datetime (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_close: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * - * Closes the iterator, making it invalid. + * Closes the cursor. The object can only be freed after this call. */ void tracker_sparql_cursor_close (TrackerSparqlCursor *cursor) @@ -421,10 +468,12 @@ tracker_sparql_cursor_close (TrackerSparqlCursor *cursor) /** * tracker_sparql_cursor_is_bound: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * If the current row and @column are bound to a value, %TRUE is returned. + * Returns whether the given @column has a bound value in the current row. + * + * This may not be the case through e.g. the `OPTIONAL { }` SPARQL syntax. * * Returns: a %TRUE or %FALSE. */ @@ -439,14 +488,17 @@ tracker_sparql_cursor_is_bound (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next: - * @cursor: a #TrackerSparqlCursor - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @cursor: a `TrackerSparqlCursor` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Iterates the cursor to the next result. * - * Iterates to the next result. This is completely synchronous and - * it may block. + * If the cursor was not started, it will point to the first result after + * this call. This operation is completely synchronous and it may block, + * see [method@Tracker.SparqlCursor.next_async] for an asynchronous variant. * - * Returns: %FALSE if no more results found, otherwise %TRUE. + * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE. */ gboolean tracker_sparql_cursor_next (TrackerSparqlCursor *cursor, @@ -472,13 +524,21 @@ tracker_sparql_cursor_next (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next_async: - * @cursor: a #TrackerSparqlCursor - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when + * @cursor: a `TrackerSparqlCursor` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when * asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Iterates, asynchronously, to the next result. + * Iterates the cursor asyncronously to the next result. + * + * If the cursor was not started, it will point to the first result after + * this operation completes. + * + * In the period between this call and the corresponding + * [method@Tracker.SparqlCursor.next_finish] call, the other cursor methods + * should not be used, nor their results trusted. The cursor should only + * be iterated once at a time. */ void tracker_sparql_cursor_next_async (TrackerSparqlCursor *cursor, @@ -497,13 +557,14 @@ tracker_sparql_cursor_next_async (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next_finish: - * @cursor: a #TrackerSparqlCursor - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @cursor: a `TrackerSparqlCursor` + * @res: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous iteration to the next result. + * Finishes the asynchronous iteration to the next result started with + * [method@Tracker.SparqlCursor.next_async]. * - * Returns: %FALSE if no more results found, otherwise %TRUE. + * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE. */ gboolean tracker_sparql_cursor_next_finish (TrackerSparqlCursor *cursor, @@ -529,12 +590,12 @@ tracker_sparql_cursor_next_finish (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_rewind: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * * Resets the iterator to point back to the first result. * * Deprecated: 3.5: This function only works on cursors - * from direct #TrackerSparqlConnection objects and cannot work + * from direct [class@Tracker.SparqlConnection] objects and cannot work * reliably across all cursor types. Issue a different query to * obtain a new cursor. */ diff --git a/src/libtracker-sparql/tracker-cursor.h b/src/libtracker-sparql/tracker-cursor.h index 2316202e4..f96c44129 100644 --- a/src/libtracker-sparql/tracker-cursor.h +++ b/src/libtracker-sparql/tracker-cursor.h @@ -28,12 +28,6 @@ G_BEGIN_DECLS -/** - * TrackerSparqlCursor: - * - * The <structname>TrackerSparqlCursor</structname> object represents an - * iterator of results. - */ #define TRACKER_TYPE_SPARQL_CURSOR tracker_sparql_cursor_get_type () #define TRACKER_SPARQL_TYPE_CURSOR TRACKER_TYPE_SPARQL_CURSOR TRACKER_AVAILABLE_IN_ALL diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c index 14e6f274d..3d0b86a3a 100644 --- a/src/libtracker-sparql/tracker-endpoint-dbus.c +++ b/src/libtracker-sparql/tracker-endpoint-dbus.c @@ -20,23 +20,42 @@ */ /** - * SECTION: tracker-endpoint-dbus - * @short_description: DBus endpoint - * @title: TrackerEndpointDBus - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerEndpointDBus: * - * #TrackerEndpointDBus is an endpoint implementation that exports - * a local #TrackerSparqlConnection so it is accessible in the given - * bus connection. + * `TrackerEndpointDBus` makes the RDF data in a [class@Tracker.SparqlConnection] + * accessible to other processes via DBus. + * + * This object is a [class@Tracker.Endpoint] subclass that exports + * a [class@Tracker.SparqlConnection] so its RDF data is accessible to other + * processes through the given [class@Gio.DBusConnection]. + * + * ```c + * // This process already has org.example.Endpoint bus name + * endpoint = tracker_endpoint_dbus_new (sparql_connection, + * dbus_connection, + * NULL, + * NULL, + * &error); + * + * // From another process + * connection = tracker_sparql_connection_bus_new ("org.example.Endpoint", + * NULL, + * dbus_connection, + * &error); + * ``` + * + * The `TrackerEndpointDBus` will manage a DBus object at the given path + * with the `org.freedesktop.Tracker3.Endpoint` interface, if no path is + * given the object will be at the default `/org/freedesktop/Tracker3/Endpoint` + * location. * * Access to these endpoints may be transparently managed through * the Tracker portal service for applications sandboxed via Flatpak, and * access to data constrained to the graphs defined in the applications * manifest. * - * A #TrackerEndpointDBus may be created on a different thread/main - * context than the one creating the #TrackerSparqlConnection. + * A `TrackerEndpointDBus` may be created on a different thread/main + * context from the one that created [class@Tracker.SparqlConnection]. */ #include "config.h" @@ -1376,12 +1395,22 @@ tracker_endpoint_dbus_class_init (TrackerEndpointDBusClass *klass) object_class->set_property = tracker_endpoint_dbus_set_property; object_class->get_property = tracker_endpoint_dbus_get_property; + /** + * TrackerEndpointDBus:dbus-connection: + * + * The [class@Gio.DBusConnection] where the connection is proxied through. + */ props[PROP_DBUS_CONNECTION] = g_param_spec_object ("dbus-connection", "DBus connection", "DBus connection", G_TYPE_DBUS_CONNECTION, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * TrackerEndpointDBus:object-path: + * + * The DBus object path that this endpoint manages. + */ props[PROP_OBJECT_PATH] = g_param_spec_string ("object-path", "DBus object path", @@ -1400,16 +1429,16 @@ tracker_endpoint_dbus_init (TrackerEndpointDBus *endpoint) /** * tracker_endpoint_dbus_new: - * @sparql_connection: a #TrackerSparqlConnection - * @dbus_connection: a #GDBusConnection - * @object_path: (nullable): the object path to use, or %NULL for the default - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @sparql_connection: The [class@Tracker.SparqlConnection] being made public + * @dbus_connection: #GDBusConnection to expose the DBus object over + * @object_path: (nullable): The object path to use, or %NULL to use the default + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Registers a Tracker endpoint object at @object_path on @dbus_connection. - * The default object path is "/org/freedesktop/Tracker3/Endpoint". + * The default object path is `/org/freedesktop/Tracker3/Endpoint`. * - * Returns: (transfer full): a #TrackerEndpointDBus object. + * Returns: (transfer full): a `TrackerEndpointDBus` object. */ TrackerEndpointDBus * tracker_endpoint_dbus_new (TrackerSparqlConnection *sparql_connection, diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.h b/src/libtracker-sparql/tracker-endpoint-dbus.h index 8c999f3ec..5f47eac9a 100644 --- a/src/libtracker-sparql/tracker-endpoint-dbus.h +++ b/src/libtracker-sparql/tracker-endpoint-dbus.h @@ -38,12 +38,6 @@ G_BEGIN_DECLS #define TRACKER_IS_ENDPOINT_DBUS_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), TRACKER_TYPE_ENDPOINT_DBUS)) #define TRACKER_ENDPOINT_DBUS_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_DBUS, TrackerEndpointDBusClass)) -/** - * TrackerEndpointDBus: - * - * The <structname>TrackerEndpointDBus</structname> object represents a public - * connection to a #TrackerSparqlConnection on a DBus object path. - */ typedef struct _TrackerEndpointDBus TrackerEndpointDBus; G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointDBus, g_object_unref) diff --git a/src/libtracker-sparql/tracker-endpoint-http.c b/src/libtracker-sparql/tracker-endpoint-http.c index e38bb78bb..6ae2340ae 100644 --- a/src/libtracker-sparql/tracker-endpoint-http.c +++ b/src/libtracker-sparql/tracker-endpoint-http.c @@ -20,33 +20,49 @@ */ /** - * SECTION: tracker-endpoint-http - * @short_description: HTTP endpoint - * @title: TrackerEndpointHttp - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerEndpointHttp: * - * #TrackerEndpointHttp is an endpoint implementation that exports - * a local #TrackerSparqlConnection so it is accessible via HTTP - * requests. + * `TrackerEndpointHttp` makes the RDF data in a [class@Tracker.SparqlConnection] + * accessible to other hosts via HTTP. * - * Access to these endpoints may be managed via the - * #TrackerEndpointHttp::block-remote-address signal, the boolean + * This object is a [class@Tracker.Endpoint] subclass that exports + * a [class@Tracker.SparqlConnection] so its RDF data is accessible via HTTP + * requests on the given port. This endpoint implementation is compliant + * with the [SPARQL protocol specifications](https://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/) + * and may interoperate with other implementations. + * + * ```c + * // This host has "example.local" hostname + * endpoint = tracker_endpoint_http_new (sparql_connection, + * 8080, + * tls_certificate, + * NULL, + * &error); + * + * // From another host + * connection = tracker_sparql_connection_remote_new ("http://example.local:8080/sparql"); + * ``` + * + * Access to HTTP endpoints may be managed via the + * [signal@Tracker.EndpointHttp::block-remote-address] signal, the boolean * return value expressing whether the connection is blocked or not. * Inspection of the requester address is left up to the user. The * default value allows all requests independently of their provenance, * users are encouraged to add a handler. * - * If the provided #GTlsCertificate is %NULL, the endpoint will allow + * If the provided [class@Gio.TlsCertificate] is %NULL, the endpoint will allow * plain HTTP connections. Users are encouraged to provide a certificate * in order to use HTTPS. * - * As a security measure, and in compliance with the SPARQL 1.1 specifications, - * the HTTP endpoint does not support database updates or modifications in any - * way. The database is completely owned by the host. + * As a security measure, and in compliance specifications, + * the HTTP endpoint does not handle database updates or modifications in any + * way. The database content is considered to be entirely managed by the + * process that creates the HTTP endpoint and owns the [class@Tracker.SparqlConnection]. * - * A #TrackerEndpointHttp may be created on a different thread/main - * context than the one creating the #TrackerSparqlConnection. + * A `TrackerEndpointHttp` may be created on a different thread/main + * context from the one that created [class@Tracker.SparqlConnection]. + * + * Since: 3.1 */ #include "config.h" @@ -388,7 +404,7 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) /** * TrackerEndpointHttp::block-remote-address: - * @self: The #TrackerNotifier + * @self: The `TrackerEndpointHttp` * @address: The socket address of the remote connection * * Allows control over the connections stablished. The given @@ -404,6 +420,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) g_signal_accumulator_first_wins, NULL, NULL, G_TYPE_BOOLEAN, 1, G_TYPE_SOCKET_ADDRESS); + /** + * TrackerEndpointHttp:http-port: + * + * HTTP port used to listen requests. + */ props[PROP_HTTP_PORT] = g_param_spec_uint ("http-port", "HTTP Port", @@ -411,6 +432,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) 0, G_MAXUINT, 8080, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * TrackerEndpointHttp:http-certificate: + * + * [class@Gio.TlsCertificate] to encrypt the communication. + */ props[PROP_HTTP_CERTIFICATE] = g_param_spec_object ("http-certificate", "HTTP certificate", @@ -429,17 +455,17 @@ tracker_endpoint_http_init (TrackerEndpointHttp *endpoint) /** * tracker_endpoint_http_new: - * @sparql_connection: a #TrackerSparqlConnection - * @port: HTTP port to listen to - * @certificate: (nullable): certificate to use for encription, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @sparql_connection: The [class@Tracker.SparqlConnection] being made public + * @port: HTTP port to handle incoming requests + * @certificate: (nullable): Optional [type@Gio.TlsCertificate] to use for encription + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Sets up a Tracker endpoint to listen via HTTP, in the given @port. * If @certificate is not %NULL, HTTPS may be used to connect to the * endpoint. * - * Returns: (transfer full): a #TrackerEndpointDBus object. + * Returns: (transfer full): a `TrackerEndpointHttp` object. * * Since: 3.1 **/ diff --git a/src/libtracker-sparql/tracker-endpoint-http.h b/src/libtracker-sparql/tracker-endpoint-http.h index be6e6f408..a3c5a9dfa 100644 --- a/src/libtracker-sparql/tracker-endpoint-http.h +++ b/src/libtracker-sparql/tracker-endpoint-http.h @@ -33,17 +33,8 @@ G_BEGIN_DECLS #define TRACKER_TYPE_ENDPOINT_HTTP (tracker_endpoint_http_get_type()) #define TRACKER_ENDPOINT_HTTP(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttp)) -#define TRACKER_ENDPOINT_HTTP_CLASS(c) (G_TYPE_CHECK_CLASS_CAST ((c), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass)) #define TRACKER_IS_ENDPOINT_HTTP(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), TRACKER_TYPE_ENDPOINT_HTTP)) -#define TRACKER_IS_ENDPOINT_HTTP_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), TRACKER_TYPE_ENDPOINT_HTTP)) -#define TRACKER_ENDPOINT_HTTP_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass)) -/** - * TrackerEndpointHttp: - * - * The <structname>TrackerEndpointHttp</structname> object represents a public - * connection to a #TrackerSparqlConnection on a HTTP port. - */ typedef struct _TrackerEndpointHttp TrackerEndpointHttp; G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointHttp, g_object_unref) diff --git a/src/libtracker-sparql/tracker-endpoint.c b/src/libtracker-sparql/tracker-endpoint.c index f404e3f0c..10f3cb8be 100644 --- a/src/libtracker-sparql/tracker-endpoint.c +++ b/src/libtracker-sparql/tracker-endpoint.c @@ -39,20 +39,21 @@ typedef struct { G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (TrackerEndpoint, tracker_endpoint, G_TYPE_OBJECT) /** - * SECTION: tracker-endpoint - * @short_description: Expose a database outside the process - * @title: TrackerEndpoint - * @stability: Stable - * @include: tracker-endpoint.h + * TrackerEndpoint: * - * #TrackerEndpoint allows sharing data, either with other processes on the - * system via a Tracker-specific D-Bus API, or remote peers via the HTTP - * SPARQL protocol. + * `TrackerEndpoint` is a helper object to make RDF triple stores represented + * by a [class@Tracker.SparqlConnection] publicly available to other processes/hosts. * - * When it is shared in this way, other peers can connect to your database using - * tracker_sparql_connection_bus_new() or tracker_sparql_connection_remote_new(), - * and can also fetch data directly from SPARQL queries using the - * <userinput>SELECT { SERVICE ... }</userinput> syntax. + * This is a base abstract object, see [class@Tracker.EndpointDBus] to make + * RDF triple stores available to other processes in the same machine, and + * [class@Tracker.EndpointHttp] to make it available to other hosts in the + * network. + * + * When the RDF triple store represented by a [class@Tracker.SparqlConnection] + * is made public this way, other peers may connect to the database using + * [ctor@Tracker.SparqlConnection.bus_new] or [ctor@Tracker.SparqlConnection.remote_new] + * to access this endpoint exclusively, or they may use the `SERVICE <uri> { ... }` SPARQL + * syntax from their own [class@Tracker.SparqlConnection]s to expand their data set. */ static void @@ -113,6 +114,11 @@ tracker_endpoint_class_init (TrackerEndpointClass *klass) object_class->set_property = tracker_endpoint_set_property; object_class->get_property = tracker_endpoint_get_property; + /** + * TrackerEndpoint:sparql-connection: + * + * The [class@Tracker.SparqlConnection] being proxied by this endpoint. + */ props[PROP_SPARQL_CONNECTION] = g_param_spec_object ("sparql-connection", "Sparql connection", @@ -129,9 +135,10 @@ tracker_endpoint_init (TrackerEndpoint *endpoint) /** * tracker_endpoint_get_sparql_connection: - * @endpoint: a #TrackerEndpoint + * @endpoint: a `TrackerEndpoint` * - * Returns the #TrackerSparqlConnection that this endpoint proxies. + * Returns the [class@Tracker.SparqlConnection] that this endpoint proxies + * to a wider audience. * * Returns: (transfer none): The proxied SPARQL connection **/ diff --git a/src/libtracker-sparql/tracker-endpoint.h b/src/libtracker-sparql/tracker-endpoint.h index b764f5e35..4bcddda84 100644 --- a/src/libtracker-sparql/tracker-endpoint.h +++ b/src/libtracker-sparql/tracker-endpoint.h @@ -32,12 +32,6 @@ G_BEGIN_DECLS -/** - * TrackerEndpoint: - * - * The <structname>TrackerEndpoint</structname> object represents a public - * connection to a #TrackerSparqlConnection. - */ #define TRACKER_TYPE_ENDPOINT tracker_endpoint_get_type() TRACKER_AVAILABLE_IN_ALL G_DECLARE_DERIVABLE_TYPE (TrackerEndpoint, tracker_endpoint, TRACKER, ENDPOINT, GObject) diff --git a/src/libtracker-sparql/tracker-error.c b/src/libtracker-sparql/tracker-error.c index 600427433..c9964382b 100644 --- a/src/libtracker-sparql/tracker-error.c +++ b/src/libtracker-sparql/tracker-error.c @@ -43,20 +43,16 @@ static const GDBusErrorEntry tracker_sparql_error_entries[] = G_STATIC_ASSERT (G_N_ELEMENTS (tracker_sparql_error_entries) == TRACKER_SPARQL_N_ERRORS); -/** - * tracker_sparql_error_quark: - * - * Returns: The error domain quark used for Tracker errors. - **/ GQuark tracker_sparql_error_quark (void) { - static volatile gsize quark_volatile = 0; - g_dbus_error_register_error_domain ("tracker-sparql-error-quark", - &quark_volatile, - tracker_sparql_error_entries, - G_N_ELEMENTS (tracker_sparql_error_entries)); - return (GQuark) quark_volatile; + static gsize quark = 0; + + g_dbus_error_register_error_domain ("tracker-sparql-error-quark", + &quark, + tracker_sparql_error_entries, + G_N_ELEMENTS (tracker_sparql_error_entries)); + return (GQuark) quark; } /* Converts internal error codes into public diff --git a/src/libtracker-sparql/tracker-error.h b/src/libtracker-sparql/tracker-error.h index 3ea9729a2..40ff3a709 100644 --- a/src/libtracker-sparql/tracker-error.h +++ b/src/libtracker-sparql/tracker-error.h @@ -27,14 +27,6 @@ G_BEGIN_DECLS /** - * SECTION: tracker-sparql-error - * @short_description: Error codes - * @title: TrackerSparqlError - * @stability: Stable - * @include: tracker-sparql.h - */ - -/** * TrackerSparqlError: * @TRACKER_SPARQL_ERROR_CONSTRAINT: Subject is not in the domain of a property or * trying to set multiple values for a single valued @@ -56,7 +48,7 @@ G_BEGIN_DECLS * @TRACKER_SPARQL_ERROR_LAST: The total number of error codes. * * Error domain for Tracker Sparql. Errors in this domain will be from the - * #TrackerSparqlError enumeration. See #GError for more information on error + * [error@Tracker.SparqlError] enumeration. See [struct@GLib.Error] for more information on error * domains. */ typedef enum { @@ -79,7 +71,7 @@ typedef enum { } TrackerSparqlError; #define TRACKER_SPARQL_N_ERRORS TRACKER_SPARQL_ERROR_LAST -#define TRACKER_SPARQL_ERROR tracker_sparql_error_quark () +#define TRACKER_SPARQL_ERROR (tracker_sparql_error_quark ()) TRACKER_AVAILABLE_IN_ALL GQuark tracker_sparql_error_quark (void); diff --git a/src/libtracker-sparql/tracker-namespace-manager.c b/src/libtracker-sparql/tracker-namespace-manager.c index f2eabdf00..2e13e3a8c 100644 --- a/src/libtracker-sparql/tracker-namespace-manager.c +++ b/src/libtracker-sparql/tracker-namespace-manager.c @@ -47,21 +47,19 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerNamespaceManager, tracker_namespace_manager, #define GET_PRIVATE(object) (tracker_namespace_manager_get_instance_private (object)) /** - * SECTION: tracker-namespace-manager - * @short_description: A set of well-known namespaces, and known abbreviations for them - * @title: TrackerNamespaceManager - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerNamespaceManager: * - * #TrackerNamespaceManager keeps track of namespaces. It allows you to assign - * short prefixes for them to avoid typing full URLs all the time. + * `TrackerNamespaceManager` object represents a mapping between namespaces and + * their shortened prefixes. * - * The syntax used is that of Compact URIs (CURIEs) as defined here: - * (https://www.w3.org/TR/2010/NOTE-curie-20101216) + * This object keeps track of namespaces, and allows you to assign + * short prefixes for them to avoid frequent use of full namespace IRIs. The syntax + * used is that of [Compact URIs (CURIEs)](https://www.w3.org/TR/2010/NOTE-curie-20101216). * - * Usually you will want to use the default namespace manager, as returned by - * tracker_namespace_manager_get_default(). This has a set of well-known - * prefixes predefined. + * Usually you will want to use a namespace manager obtained through + * [method@Tracker.SparqlConnection.get_namespace_manager] from the + * [class@Tracker.SparqlConnection] that manages the RDF data, as that will + * contain all prefixes and namespaces that are pre-defined by its ontology. */ static void finalize (GObject *object); @@ -101,9 +99,9 @@ finalize (GObject *object) /** * tracker_namespace_manager_new: * - * Creates a new #TrackerNamespaceManager instance. + * Creates a new, empty `TrackerNamespaceManager` instance. * - * Returns: a new #TrackerNamespaceManager instance + * Returns: a new `TrackerNamespaceManager` instance */ TrackerNamespaceManager * tracker_namespace_manager_new () @@ -118,16 +116,16 @@ tracker_namespace_manager_new () /** * tracker_namespace_manager_get_default: * - * Returns the global #TrackerNamespaceManager that contains a set of well-known - * namespaces and prefixes, such as rdf:, rdfs:, nie:, tracker:, etc. + * Returns the global `TrackerNamespaceManager` that contains a set of well-known + * namespaces and prefixes, such as `rdf:`, `rdfs:`, `nie:`, `tracker:`, etc. * * Note that the list of prefixes and namespaces is hardcoded in * libtracker-sparql. It may not correspond with the installed set of * ontologies, if they have been modified since they were installed. * - * Returns: (transfer none): a global, shared #TrackerNamespaceManager instance + * Returns: (transfer none): a global, shared `TrackerNamespaceManager` instance * - * Deprecated: 3.3: Use tracker_sparql_connection_get_namespace_manager() instead. + * Deprecated: 3.3: Use [method@Tracker.SparqlConnection.get_namespace_manager] instead. */ TrackerNamespaceManager * tracker_namespace_manager_get_default () @@ -164,12 +162,12 @@ tracker_namespace_manager_get_default () /** * tracker_namespace_manager_has_prefix: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @prefix: a string * * Returns whether @prefix is known. * - * Returns: %TRUE if the #TrackerNamespaceManager knows about @prefix, %FALSE otherwise + * Returns: %TRUE if the `TrackerNamespaceManager` knows about @prefix, %FALSE otherwise */ gboolean tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self, @@ -186,13 +184,13 @@ tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_lookup_prefix: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @prefix: a string * * Looks up the namespace URI corresponding to @prefix, or %NULL if the prefix * is not known. * - * Returns: (nullable): a string owned by the #TrackerNamespaceManager, or %NULL + * Returns: (nullable): a string owned by the `TrackerNamespaceManager`, or %NULL */ const char * tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, @@ -209,7 +207,7 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_add_prefix: - * @self: a #TrackerNamespaceManager + * @self: A `TrackerNamespaceManager` * @prefix: a short, unique prefix to identify @namespace * @ns: the URL of the given namespace * @@ -218,9 +216,9 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, * Only one prefix is allowed for a given namespace, and all prefixes must * be unique. * - * Since 3.3, This function may not be used on #TrackerNamespaceManager - * instances that were obtained through - * tracker_sparql_connection_get_namespace_manager(). + * Since 3.3, The `TrackerNamespaceManager` instances obtained through + * [method@Tracker.SparqlConnection.get_namespace_manager] are "sealed", + * this API call should not performed on those. */ void tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self, @@ -270,14 +268,14 @@ tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_expand_uri: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @compact_uri: a URI or compact URI * * If @compact_uri begins with one of the prefixes known to this - * #TrackerNamespaceManager, then the return value will be the + * `TrackerNamespaceManager`, then the return value will be the * expanded URI. Otherwise, a copy of @compact_uri will be returned. * - * Returns: a newly-allocated string + * Returns: The possibly expanded URI in a newly-allocated string. */ char * tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self, @@ -314,11 +312,11 @@ tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self, /** * tracker_namespace_manager_compress_uri: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @uri: a URI or compact URI * * If @uri begins with one of the namespaces known to this - * #TrackerNamespaceManager, then the return value will be the + * `TrackerNamespaceManager`, then the return value will be the * compressed URI. Otherwise, %NULL will be returned. * * Returns: (transfer full): (nullable): the compressed URI @@ -360,9 +358,10 @@ tracker_namespace_manager_compress_uri (TrackerNamespaceManager *self, /** * tracker_namespace_manager_print_turtle: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * - * Writes out all namespaces as Turtle @prefix statements. + * Writes out all namespaces as `@prefix` statements in + * the [Turtle](https://www.w3.org/TR/turtle/) RDF format. * * Returns: a newly-allocated string */ @@ -391,7 +390,7 @@ tracker_namespace_manager_print_turtle (TrackerNamespaceManager *self) /** * tracker_namespace_manager_foreach: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @func: (scope call): the function to call for each prefix / URI pair * @user_data: user data to pass to the function * diff --git a/src/libtracker-sparql/tracker-namespace-manager.h b/src/libtracker-sparql/tracker-namespace-manager.h index 04e081356..f418cc71d 100644 --- a/src/libtracker-sparql/tracker-namespace-manager.h +++ b/src/libtracker-sparql/tracker-namespace-manager.h @@ -30,12 +30,6 @@ G_BEGIN_DECLS #include <libtracker-sparql/tracker-version.h> -/** - * TrackerNamespaceManager: - * - * The <structname>TrackerNamespaceManager</structname> object represents a - * mapping of prefixes and namespaces. - */ #define TRACKER_TYPE_NAMESPACE_MANAGER (tracker_namespace_manager_get_type()) TRACKER_AVAILABLE_IN_ALL G_DECLARE_FINAL_TYPE (TrackerNamespaceManager, tracker_namespace_manager, TRACKER, NAMESPACE_MANAGER, GObject) diff --git a/src/libtracker-sparql/tracker-notifier.c b/src/libtracker-sparql/tracker-notifier.c index 78056c2c0..1ac26e019 100644 --- a/src/libtracker-sparql/tracker-notifier.c +++ b/src/libtracker-sparql/tracker-notifier.c @@ -18,30 +18,36 @@ */ /** - * SECTION: tracker-notifier - * @title: TrackerNotifier - * @short_description: Listen to changes in the Tracker database - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerNotifier: * - * #TrackerNotifier is an object that receives notifications about - * changes to the Tracker database. A #TrackerNotifier is created - * through tracker_sparql_connection_create_notifier(), after the notifier - * is created, events can be listened for by connecting to the - * #TrackerNotifier::events signal. + * `TrackerNotifier` allows receiving notification on changes + * in the data stored by a [class@Tracker.SparqlConnection]. * - * # Known caveats + * This object may be created through [method@Tracker.SparqlConnection.create_notifier], + * events can then be listened for by connecting to the + * [signal@Tracker.Notifier::events] signal. * - * * The %TRACKER_NOTIFIER_EVENT_DELETE events will be received after the - * resource has been deleted. At that time queries on those elements will - * not bring any metadata. Only the ID/URN obtained through the event - * remain meaningful. - * * Notifications of files being moved across indexed folders will - * appear as %TRACKER_NOTIFIER_EVENT_UPDATE events, containing - * the new location (if requested). The older location is no longer - * known to Tracker, this may make tracking of elements in specific - * folders hard using solely the #TrackerNotifier/Tracker data - * available at event notification time. + * Not every change is notified, only RDF resources with a + * class that has the [nrl:notify](nrl-ontology.html#nrl:notify) + * property defined by the ontology will be notified upon changes. + * + * Database changes are communicated through [struct@Tracker.NotifierEvent] events on + * individual graph/resource pairs. The event type obtained through + * [method@Tracker.NotifierEvent.get_event_type] will determine the type of event. + * Insertion of new resources is notified through + * %TRACKER_NOTIFIER_EVENT_CREATE events, deletion of + * resources is notified through %TRACKER_NOTIFIER_EVENT_DELETE + * events, and changes on any property of the resource is notified + * through %TRACKER_NOTIFIER_EVENT_UPDATE events. + * + * The events happen in reaction to database changes, after a `TrackerNotifier` + * received an event of type %TRACKER_NOTIFIER_EVENT_DELETE, the resource will + * not exist anymore and only the information in the [struct@Tracker.NotifierEvent] + * will remain. + * + * Similarly, when receiving an event of type %TRACKER_NOTIFIER_EVENT_UPDATE, + * the resource will have already changed, so the data previous to the update is + * no longer available. */ #include "config.h" @@ -745,10 +751,10 @@ tracker_notifier_class_init (TrackerNotifierClass *klass) /** * TrackerNotifier::events: - * @self: The #TrackerNotifier + * @self: The `TrackerNotifier` * @service: The SPARQL service that originated the events, %NULL for the local store * @graph: The graph where the events happened on, %NULL for the default anonymous graph - * @events: (element-type TrackerNotifierEvent): A #GPtrArray of #TrackerNotifierEvent + * @events: (transfer none) (type GLib.PtrArray) (element-type TrackerNotifierEvent): A [type@GLib.PtrArray] of [struct@Tracker.NotifierEvent] * * Notifies of changes in the Tracker database. */ @@ -793,23 +799,26 @@ tracker_notifier_init (TrackerNotifier *notifier) /** * tracker_notifier_signal_subscribe: - * @notifier: a #TrackerNotifier - * @connection: a #GDBusConnection + * @notifier: A `TrackerNotifier` + * @connection: A [class@Gio.DBusConnection] * @service: DBus service name to subscribe to events for * @object_path: (nullable): DBus object path to subscribe to events for, or %NULL - * @graph: (nullable): graph to listen events for, or %NULL + * @graph: (nullable): Graph to listen events for, or %NULL * - * Listens to notification events from a remote SPARQL endpoint as a DBus - * service (see #TrackerEndpointDBus). If the @object_path argument is - * %NULL, the default "/org/freedesktop/Tracker3/Endpoint" path will be + * Listens to notification events from a remote DBus SPARQL endpoint. + * + * If the @object_path argument is %NULL, the default + * `/org/freedesktop/Tracker3/Endpoint` path will be * used. If @graph is %NULL, all graphs will be listened for. * * The signal subscription can be removed with - * tracker_notifier_signal_unsubscribe(). + * [method@Tracker.Notifier.signal_unsubscribe]. * - * Returns: An ID for this subscription + * Note that this call is not necessary to receive notifications on + * a connection obtained through [ctor@Tracker.SparqlConnection.bus_new], + * only to listen to update notifications from additional DBus endpoints. * - * Since: 3.0 + * Returns: An ID for this subscription **/ guint tracker_notifier_signal_subscribe (TrackerNotifier *notifier, @@ -874,13 +883,12 @@ tracker_notifier_signal_subscribe (TrackerNotifier *notifier, /** * tracker_notifier_signal_unsubscribe: - * @notifier: a #TrackerNotifier - * @handler_id: a handler ID obtained with tracker_notifier_signal_subscribe() + * @notifier: A `TrackerNotifier` + * @handler_id: A signal subscription handler ID * - * Undoes a DBus signal subscription, the @handler_id argument was previously - * obtained with a tracker_notifier_signal_subscribe() call. + * Undoes a signal subscription done through [method@Tracker.Notifier.signal_subscribe]. * - * Since: 3.0 + * The @handler_id argument was previously obtained during signal subscription creation. **/ void tracker_notifier_signal_unsubscribe (TrackerNotifier *notifier, @@ -908,7 +916,7 @@ _tracker_notifier_get_connection (TrackerNotifier *notifier) /** * tracker_notifier_event_get_event_type: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the event type. * @@ -923,7 +931,7 @@ tracker_notifier_event_get_event_type (TrackerNotifierEvent *event) /** * tracker_notifier_event_get_id: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the tracker:id of the element being notified upon. This is a #gint64 * which is used as efficient internal identifier for the resource. @@ -939,13 +947,13 @@ tracker_notifier_event_get_id (TrackerNotifierEvent *event) /** * tracker_notifier_event_get_urn: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the Uniform Resource Name of the element. This is Tracker's * public identifier for the resource. * * This URN is an unique string identifier for the resource being - * notified upon, typically of the form "urn:uuid:...". + * notified upon, typically of the form `urn:uuid:...`. * * Returns: The element URN **/ diff --git a/src/libtracker-sparql/tracker-notifier.h b/src/libtracker-sparql/tracker-notifier.h index 962d03198..aff34e3c4 100644 --- a/src/libtracker-sparql/tracker-notifier.h +++ b/src/libtracker-sparql/tracker-notifier.h @@ -32,12 +32,6 @@ G_BEGIN_DECLS #define TRACKER_TYPE_NOTIFIER (tracker_notifier_get_type ()) #define TRACKER_TYPE_NOTIFIER_EVENT (tracker_notifier_event_get_type ()) -/** - * TrackerNotifier: - * - * The <structname>TrackerNotifier</structname> object allows subscribing - * to changes in the stored data. - */ TRACKER_AVAILABLE_IN_ALL G_DECLARE_DERIVABLE_TYPE (TrackerNotifier, tracker_notifier, TRACKER, NOTIFIER, GObject) diff --git a/src/libtracker-sparql/tracker-ontologies.h b/src/libtracker-sparql/tracker-ontologies.h index 8713b4fb6..bb678b67f 100644 --- a/src/libtracker-sparql/tracker-ontologies.h +++ b/src/libtracker-sparql/tracker-ontologies.h @@ -18,17 +18,6 @@ * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-ontologies - * @short_description: Utility prefix definitions for common ontologies - * @title: Utility Ontology Defines - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h - * - * Utility defines for the common namespace prefixes. - */ - - #ifndef __LIBTRACKER_SPARQL_ONTOLOGIES_H__ #define __LIBTRACKER_SPARQL_ONTOLOGIES_H__ diff --git a/src/libtracker-sparql/tracker-resource.c b/src/libtracker-sparql/tracker-resource.c index ab579135b..1d06d0841 100644 --- a/src/libtracker-sparql/tracker-resource.c +++ b/src/libtracker-sparql/tracker-resource.c @@ -47,14 +47,37 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerResource, tracker_resource, G_TYPE_OBJECT) #define GET_PRIVATE(object) (tracker_resource_get_instance_private (object)) /** - * SECTION: tracker-resource - * @short_description: Represents a single Tracker resource - * @title: TrackerResource - * @stability: Stable - * @include: tracker-resource.h - * - * #TrackerResource keeps track of a set of properties for a given resource. - * The resulting data can be serialized in several ways. + * TrackerResource: + * + * `TrackerResource` is an in-memory representation of RDF data about a given resource. + * + * This object keeps track of a set of properties for a given resource, and can + * also link to other `TrackerResource` objects to form trees or graphs of RDF + * data. See [method@Tracker.Resource.set_relation] and [method@Tracker.Resource.set_uri] + * on how to link a `TrackerResource` to other RDF data. + * + * `TrackerResource` may also hold data about literal values, added through + * the specialized [method@Tracker.Resource.set_int64], [method@Tracker.Resource.set_string], + * etc family of functions, or the generic [method@Tracker.Resource.set_gvalue] method. + * + * Since RDF properties may be multi-valued, for every `set` call there exists + * another `add` call (e.g. [method@Tracker.Resource.add_int64], [method@Tracker.Resource.add_string] + * and so on). The `set` methods do also reset any previously value the + * property might hold for the given resource. + * + * Resources may have an IRI set at creation through [ctor@Tracker.Resource.new], + * or set afterwards through [method@Tracker.Resource.set_identifier]. Resources + * without a name will represent a blank node, and will be dealt with as such + * during database insertions. + * + * `TrackerResource` performs no validation on the data being coherent as per + * any ontology. Errors will be found out at the time of using the TrackerResource + * for e.g. database updates. + * + * Once the RDF data is built in memory, the (tree of) `TrackerResource` may be + * converted to a RDF format through [method@Tracker.Resource.print_rdf], or + * directly inserted into a database through [method@Tracker.Batch.add_resource] + * or [method@Tracker.SparqlConnection.update_resource]. */ static char * @@ -65,13 +88,6 @@ generate_blank_node_identifier (void) return g_strdup_printf("_:%" G_GINT64_FORMAT, counter++); } -/** - * TrackerResource: - * - * The <structname>TrackerResource</structname> object represents information - * about a given resource. - */ - enum { PROP_0, @@ -247,7 +263,7 @@ set_property (GObject *object, * * Creates a TrackerResource instance. * - * Returns: a newly created #TrackerResource. Free with g_object_unref() when done + * Returns: a newly created `TrackerResource`. */ TrackerResource * tracker_resource_new (const char *identifier) @@ -269,18 +285,17 @@ tracker_resource_new (const char *identifier) /** * tracker_resource_set_gvalue: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to set - * @value: an initialised #GValue + * @value: an initialised [struct@GObject.Value] * - * State that the only value for the given property is 'value'. Any existing - * values for 'property' will be removed. + * Replace any previously existing value for @property_uri with @value. * * When serialising to SPARQL, any properties that were set with this function * will get a corresponding DELETE statement to remove any existing values in * the database. * - * You can pass any kind of GValue for @value, but serialization functions will + * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will * normally only be able to serialize URIs/relationships and fundamental value * types (string, int, etc.). */ @@ -382,52 +397,65 @@ value_set_uri (GValue *value, /** * tracker_resource_set_boolean: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property boolean value * - * Sets a single-valued boolean object. + * Sets a boolean property. Replaces any previous value. + * + * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean) /** * tracker_resource_set_double: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property object + * + * Sets a numeric property with double precision. Replaces any previous value. * - * Sets a single-valued double object. + * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double) /** * tracker_resource_set_int: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property object * - * Sets a single-valued integer object. + * Sets a numeric property with integer precision. Replaces any previous value. + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int, int, G_TYPE_INT, g_value_set_int, validate_int) /** * tracker_resource_set_int64: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued integer object. + * Sets a numeric property with 64-bit integer precision. Replaces any previous value. + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64) /** * tracker_resource_set_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: the property object * - * Sets a single-valued resource object as a #TrackerResource. This - * function produces similar RDF to tracker_resource_set_uri(), + * Sets a resource property as a `TrackerResource`. Replaces any previous value. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_uri], * although in this function the URI will depend on the identifier * set on @resource. */ @@ -435,59 +463,76 @@ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_relation, TrackerResource *, TRACKE /** * tracker_resource_set_take_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: (transfer full): the property object * - * Sets a single-valued resource object as a #TrackerResource. This - * function produces similar RDF to tracker_resource_set_uri(), + * Sets a resource property as a `TrackerResource`. Replaces any previous value. + * Takes ownership on the given @resource. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_uri], * although in this function the URI will depend on the identifier - * set on @resource. This function takes ownership of @resource. + * set on @resource. */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_take_relation, TrackerResource *, TRACKER_TYPE_RESOURCE, g_value_take_object, validate_pointer) /** * tracker_resource_set_string: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued string object. + * Sets a string property. Replaces any previous value. + * + * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer) /** * tracker_resource_set_uri: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued resource object as a string URI. This function - * produces similar RDF to tracker_resource_set_relation(), although + * Sets a resource property as an URI string. Replaces any previous value. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_relation], although * it requires that the URI is previously known. */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer) /** * tracker_resource_set_datetime: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued GDateTime as a #TrackerResource + * Sets a date property as a [type@GLib.DateTime]. Replaces any previous value. + * + * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and + * [xsd:dateTime](xsd-ontology.html#xsd:dateTime). + * * Since: 3.2 */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer) /** * tracker_resource_add_gvalue: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to set - * @value: an initialised #GValue + * @value: an initialised [struct@GObject.Value] * - * Add 'value' to the list of values for given property. + * Add @value to the list of values for given property. * - * You can pass any kind of GValue for @value, but serialization functions will + * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will * normally only be able to serialize URIs/relationships and fundamental value * types (string, int, etc.). */ @@ -595,52 +640,80 @@ tracker_resource_add_gvalue (TrackerResource *self, /** * tracker_resource_add_boolean: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property boolean value + * + * Adds a boolean property. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). * - * Adds a boolean object to a multi-valued property. + * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean) /** * tracker_resource_add_double: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a double object to a multi-valued property. + * Adds a numeric property with double precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double) /** * tracker_resource_add_int: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds an integer object to a multi-valued property. + * Adds a numeric property with integer precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int, int, G_TYPE_INT, g_value_set_int, validate_int) /** * tracker_resource_add_int64: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds an integer object to a multi-valued property. + * Adds a numeric property with 64-bit integer precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64) /** * tracker_resource_add_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: the property object * - * Adds a resource object to a multi-valued property. This - * function produces similar RDF to tracker_resource_add_uri(), + * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This method produces similar RDF to [method@Tracker.Resource.add_uri], * although in this function the URI will depend on the identifier * set on @resource. */ @@ -648,12 +721,21 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_relation, TrackerResource *, TRACKE /** * tracker_resource_add_take_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: (transfer full): the property object * - * Adds a resource object to a multi-valued property. This - * function produces similar RDF to tracker_resource_add_uri(), + * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept. + * Takes ownership on the given @resource. + * + * This method is meant to RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.add_uri], * although in this function the URI will depend on the identifier * set on @resource. This function takes ownership of @resource. */ @@ -662,46 +744,67 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_take_relation, TrackerResource *, T /** * tracker_resource_add_string: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a string object to a multi-valued property. + * Adds a string property. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer) /** * tracker_resource_add_uri: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a resource object to a multi-valued property. This function - * produces similar RDF to tracker_resource_add_relation(), although + * Adds a resource property as an URI string. Previous values for the same property are kept. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This function produces similar RDF to [method@Tracker.Resource.add_relation], although * it requires that the URI is previously known. */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer) /** * tracker_resource_add_datetime: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds GDateTime object to the multi-valued property. + * Adds a date property as a [type@GLib.DateTime]. Previous values for the + * same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and + * [xsd:dateTime](xsd-ontology.html#xsd:dateTime). + * * Since: 3.2 */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer) /** * tracker_resource_get_values: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the list of all known values of the given property. * - * Returns: (transfer container) (element-type GValue) (nullable): a #GList of - * #GValue instances. The list should be freed with g_list_free() + * Returns: (transfer container) (element-type GValue) (nullable): a [struct@GLib.List] of + * [struct@GObject.Value] instances. The list should be freed with [func@GLib.List.free] */ GList *tracker_resource_get_values (TrackerResource *self, const char *property_uri) @@ -771,7 +874,7 @@ GList *tracker_resource_get_values (TrackerResource *self, /** * tracker_resource_get_first_boolean: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first boolean object previously assigned to a property. @@ -782,7 +885,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_boolean, gboolean, G_TYPE_BOO /** * tracker_resource_get_first_double: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first double object previously assigned to a property. @@ -793,7 +896,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_double, double, G_TYPE_DOUBLE /** * tracker_resource_get_first_int: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first integer object previously assigned to a property. @@ -804,7 +907,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int, int, G_TYPE_INT, g_value /** * tracker_resource_get_first_int64: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first integer object previously assigned to a property. @@ -815,7 +918,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int64, gint64, G_TYPE_INT64, /** * tracker_resource_get_first_relation: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first resource object previously assigned to a property. @@ -826,7 +929,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_relation, TrackerResource *, /** * tracker_resource_get_first_string: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first string object previously assigned to a property. @@ -837,7 +940,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_string, const char *, G_TYPE_ /** * tracker_resource_get_first_uri: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first resource object previously assigned to a property. @@ -848,10 +951,10 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_uri, const char *, TRACKER_TY /** * tracker_resource_get_first_datetime: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * - * Returns the first resource object previously assigned to a property. + * Returns the first [type@GLib.DateTime] previously assigned to a property. * * Returns: (transfer none) (nullable): the first GDateTime object * Since: 3.2 @@ -860,12 +963,12 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_datetime, GDateTime *, G_TYPE /** * tracker_resource_get_identifier: - * @self: A #TrackerResource + * @self: A `TrackerResource` * * Returns the identifier of a resource. * - * If the identifier was set to NULL, the identifier returned will be a unique - * SPARQL blank node identifier, such as "_:123". + * If the identifier was set to NULL, the identifier returned will be a locally + * unique SPARQL blank node identifier, such as `_:123`. * * Returns: (nullable): a string owned by the resource */ @@ -886,16 +989,16 @@ tracker_resource_get_identifier (TrackerResource *self) /** * tracker_resource_set_identifier: - * @self: a #TrackerResource + * @self: A `TrackerResource` * @identifier: (nullable): a string identifying the resource * - * Changes the identifier of a #TrackerResource. The identifier should be a + * Changes the identifier of a `TrackerResource`. The identifier should be a * URI or compact URI, but this is not necessarily enforced. Invalid * identifiers may cause errors when serializing the resource or trying to * insert the results in a database. * * If the identifier is set to %NULL, a SPARQL blank node identifier such as - * "_:123" is assigned to the resource. + * `_:123` is assigned to the resource. */ void tracker_resource_set_identifier (TrackerResource *self, @@ -913,10 +1016,10 @@ tracker_resource_set_identifier (TrackerResource *self, /** * tracker_resource_identifier_compare_func: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * @identifier: a string identifying the resource * - * A helper function that compares a #TrackerResource by its identifier + * A helper function that compares a `TrackerResource` by its identifier * string. * * Returns: an integer less than, equal to, or greater than zero, if the @@ -934,8 +1037,8 @@ tracker_resource_identifier_compare_func (TrackerResource *resource, /** * tracker_resource_compare: - * @a: A #TrackerResource - * @b: A second #TrackerResource to compare + * @a: A `TrackerResource` + * @b: A second `TrackerResource` to compare * * Compare the identifiers of two TrackerResource instances. The resources * are considered identical if they have the same identifier. @@ -959,14 +1062,11 @@ tracker_resource_compare (TrackerResource *a, /** * tracker_resource_get_properties: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * * Gets the list of properties defined in @resource * * Returns: (transfer container) (element-type utf8): The list of properties. - * The list should be freed with g_list_free(). - * - * Since: 3.0 **/ GList * tracker_resource_get_properties (TrackerResource *resource) @@ -1191,7 +1291,7 @@ generate_turtle_property (const char *property, /** * tracker_resource_print_turtle: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @@ -1201,12 +1301,12 @@ generate_turtle_property (const char *property, * <https://www.w3.org/TR/2014/REC-turtle-20140225/> * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string * - * Deprecated: 3.4: Use tracker_resource_print_rdf() instead. + * Deprecated: 3.4: Use [method@Tracker.Resource.print_rdf] instead. */ char * tracker_resource_print_turtle (TrackerResource *self, @@ -1423,7 +1523,7 @@ generate_sparql_insert_pattern (TrackerResource *resource, /** * tracker_resource_print_sparql_update: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @graph_id: (allow-none): the URN of the graph the data should be added to, @@ -1433,7 +1533,7 @@ generate_sparql_insert_pattern (TrackerResource *resource, * stored in @resource. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing a SPARQL update command. @@ -1502,7 +1602,7 @@ tracker_resource_print_sparql_update (TrackerResource *resource, /** * tracker_resource_print_jsonld: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (nullable): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @@ -1512,12 +1612,12 @@ tracker_resource_print_sparql_update (TrackerResource *resource, * serialization format. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing JSON-LD data. * - * Deprecated: 3.5: Use tracker_resource_print_rdf() + * Deprecated: 3.5: Use [method@Tracker.Resource.print_rdf] instead. */ char * tracker_resource_print_jsonld (TrackerResource *self, @@ -1553,7 +1653,7 @@ convert_format (TrackerRdfFormat format) /** * tracker_resource_print_rdf: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: a set of prefixed URLs * @format: RDF format of the printed string * @graph: (nullable): target graph of the resource RDF, or %NULL for the @@ -1562,7 +1662,7 @@ convert_format (TrackerRdfFormat format) * Serialize all the information in @resource into the selected RDF format. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing RDF data in the requested format. @@ -1675,11 +1775,11 @@ tracker_serialize_single_value (TrackerResource *resource, /** * tracker_resource_serialize: - * @resource: A #TrackerResource + * @resource: A `TrackerResource` * - * Serializes a #TrackerResource to a #GVariant in a lossless way. + * Serializes a `TrackerResource` to a [type@GLib.Variant] in a lossless way. * All child resources are subsequently serialized. It is implied - * that both ends use a common #TrackerNamespaceManager. + * that both ends use a common [class@Tracker.NamespaceManager]. * * Returns: (transfer floating) (nullable): A variant describing the resource, * the reference is floating. @@ -1751,11 +1851,11 @@ tracker_resource_serialize (TrackerResource *resource) /** * tracker_resource_deserialize: - * @variant: a #GVariant + * @variant: a [type@GLib.Variant] * - * Deserializes a #TrackerResource previously serialized with - * tracker_resource_serialize(). It is implied that both ends - * use a common #TrackerNamespaceManager. + * Deserializes a `TrackerResource` previously serialized with + * [method@Tracker.Resource.serialize]. It is implied that both ends + * use a common [class@Tracker.NamespaceManager]. * * Returns: (transfer full) (nullable): A TrackerResource, or %NULL if * deserialization fails. @@ -1872,7 +1972,7 @@ tracker_resource_deserialize (GVariant *variant) /** * tracker_resource_get_property_overwrite: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * @property_uri: a string identifying the property to query * * Returns whether the prior values for this property would be deleted diff --git a/src/libtracker-sparql/tracker-sparql-enum-types.h.template b/src/libtracker-sparql/tracker-sparql-enum-types.h.template index c0afe7b37..a7aced5a8 100644 --- a/src/libtracker-sparql/tracker-sparql-enum-types.h.template +++ b/src/libtracker-sparql/tracker-sparql-enum-types.h.template @@ -1,10 +1,11 @@ /*** BEGIN file-header ***/ -#ifndef __TRACKER_NOTIFY_ENUM_TYPES_H__ -#define __TRACKER_NOTIFY_ENUM_TYPES_H__ +#ifndef __TRACKER_SPARQL_ENUM_TYPES_H__ +#define __TRACKER_SPARQL_ENUM_TYPES_H__ #include <glib-object.h> #include <libtracker-sparql/tracker-version.h> +#include <libtracker-sparql/tracker-error.h> G_BEGIN_DECLS /*** END file-header ***/ @@ -16,12 +17,12 @@ G_BEGIN_DECLS /*** BEGIN value-header ***/ TRACKER_AVAILABLE_IN_ALL -GType @enum_name@_get_type (void) G_GNUC_CONST; +GType @enum_name@_get_type (void); #define TRACKER_TYPE_@ENUMSHORT@ (@enum_name@_get_type ()) /*** END value-header ***/ /*** BEGIN file-tail ***/ G_END_DECLS -#endif /* __TRACKER_ENUMS_TYPES_H__ */ +#endif /* __TRACKER_SPARQL_ENUMS_TYPES_H__ */ /*** END file-tail ***/ diff --git a/src/libtracker-sparql/tracker-statement.c b/src/libtracker-sparql/tracker-statement.c index 7a6c26aaf..8497af779 100644 --- a/src/libtracker-sparql/tracker-statement.c +++ b/src/libtracker-sparql/tracker-statement.c @@ -17,30 +17,38 @@ * Boston, MA 02110-1301, USA. */ /** - * SECTION: tracker-sparql-statement - * @short_description: Prepared statements - * @title: TrackerSparqlStatement - * @stability: Stable - * @include: tracker-sparql.h - * - * The <structname>TrackerSparqlStatement</structname> object represents - * a SPARQL query. This query may contain parameterized variables - * (expressed as ~var in the syntax), which may be mapped to arbitrary - * values prior to execution. This statement may be reused for future + * TrackerSparqlStatement: + * + * `TrackerSparqlStatement` represents a prepared statement for a SPARQL query. + * + * The SPARQL query will be internally compiled into the format that is most + * optimal to execute the query many times. For connections created + * through [ctor@Tracker.SparqlConnection.new] that will be a + * SQLite compiled statement. + * + * The SPARQL query may contain parameterized variables expressed via the + * `~` prefix in the SPARQL syntax (e.g. `~var`), these may happen anywhere + * in the SPARQL where a literal or variable would typically happen. These + * parameterized variables may be mapped to arbitrary values prior to + * execution. The `TrackerSparqlStatement` may be reused for future * queries with different values. * - * The argument bindings may be changed through tracker_sparql_statement_bind_int(), - * tracker_sparql_statement_bind_boolean(), tracker_sparql_statement_bind_double() - * and tracker_sparql_statement_bind_string(). Those functions receive - * a @name argument corresponding for the variable name in the SPARQL query - * (eg. "var" for ~var) and a @value to map the variable to. + * The argument bindings may be changed through the [method@Tracker.SparqlStatement.bind_int], + * [method@Tracker.SparqlStatement.bind_int], etc... family of functions. Those functions + * receive a @name argument corresponding for the variable name in the SPARQL query + * (eg. `"var"` for `~var`) and a value to map the variable to. * * Once all arguments have a value, the query may be executed through - * tracker_sparql_statement_execute() or tracker_sparql_statement_execute_async(). + * [method@Tracker.SparqlStatement.execute_async] or [method@Tracker.SparqlStatement.execute]. * - * It is possible to use a given #TrackerSparqlStatement in other threads than - * the one it was created from. It must be however used from just one thread - * at any given time. + * It is possible to use any `TrackerSparqlStatement` from other threads than + * the one it was created from. However, binding values and executing the + * statement must only happen from one thread at a time. It is possible to reuse + * the `TrackerSparqlStatement` right after [method@Tracker.SparqlStatement.execute_async] + * was called, there is no need to wait for [method@Tracker.SparqlStatement.execute_finish]. + * + * In some circumstances, it is possible that the query needs to be recompiled + * from the SPARQL source. This will happen transparently. */ #include "config.h" @@ -135,7 +143,7 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass) /** * TrackerSparqlStatement:connection: * - * The #TrackerSparqlConnection used to perform the query. + * The [class@Tracker.SparqlConnection] the statement was created for. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -166,9 +174,9 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass) /** * tracker_sparql_statement_get_connection: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * - * Returns the #TrackerSparqlConnection that this statement was created from. + * Returns the [class@Tracker.SparqlConnection] that this statement was created for. * * Returns: (transfer none): The SPARQL connection of this statement. **/ @@ -184,7 +192,7 @@ tracker_sparql_statement_get_connection (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_get_sparql: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * * Returns the SPARQL string that this prepared statement holds. * @@ -202,11 +210,11 @@ tracker_sparql_statement_get_sparql (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_bind_boolean: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the boolean @value to variable @name. + * Binds the boolean @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt, @@ -223,11 +231,11 @@ tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_int: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the integer @value to variable @name. + * Binds the integer @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt, @@ -244,11 +252,11 @@ tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_double: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the double @value to variable @name. + * Binds the double @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt, @@ -265,11 +273,11 @@ tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_string: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the string @value to variable @name. + * Binds the string @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt, @@ -287,11 +295,12 @@ tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_datetime: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the GDateTime @value to variable @name. + * Binds the [type@GLib.DateTime] @value to the parameterized variable given by @name. + * * Since: 3.2 */ @@ -311,18 +320,24 @@ tracker_sparql_statement_bind_datetime (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes the SPARQL query with the currently bound values. + * Executes the `SELECT` or `ASK` SPARQL query with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_query_statement() or + * This function also works for `DESCRIBE` and `CONSTRUCT` queries that + * retrieve data from the triple store. These query forms that return + * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async]. + * + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.query_statement] or * SELECT/CONSTRUCT/DESCRIBE statements loaded through - * tracker_sparql_connection_load_statement_from_gresource(). + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on a `INSERT` or `DELETE` + * SPARQL query. * - * Returns: (transfer full): A #TrackerSparqlCursor + * Returns: (transfer full): A `TrackerSparqlCursor` with the query results. */ TrackerSparqlCursor * tracker_sparql_statement_execute (TrackerSparqlStatement *stmt, @@ -348,18 +363,24 @@ tracker_sparql_statement_execute (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute_async: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Asynchronously executes the SPARQL query with the currently bound values. + * Executes asynchronously the `SELECT` or `ASK` SPARQL query with the currently bound values. + * + * This function also works for `DESCRIBE` and `CONSTRUCT` queries that + * retrieve data from the triple store. These query forms that return + * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async]. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_query_statement() or + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.query_statement] or * SELECT/CONSTRUCT/DESCRIBE statements loaded through - * tracker_sparql_connection_load_statement_from_gresource(). + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on a `INSERT` or `DELETE` + * SPARQL query. */ void tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt, @@ -378,14 +399,14 @@ tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute_finish: - * @stmt: a #TrackerSparqlStatement - * @res: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor - * @error: The error which occurred or %NULL + * @stmt: a `TrackerSparqlStatement` + * @res: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * * Finishes the asynchronous operation started through - * tracker_sparql_statement_execute_async(). + * [method@Tracker.SparqlStatement.execute_async]. * - * Returns: (transfer full): A #TrackerSparqlCursor + * Returns: (transfer full): A `TrackerSparqlCursor` with the query results. */ TrackerSparqlCursor * tracker_sparql_statement_execute_finish (TrackerSparqlStatement *stmt, @@ -411,15 +432,18 @@ tracker_sparql_statement_execute_finish (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes the SPARQL update with the currently bound values. + * Executes the `INSERT`/`DELETE` SPARQL query series with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * `INSERT`/`DELETE` statements loaded through + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on + * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries. * * Returns: %TRUE if the update finished with no errors, %FALSE otherwise * @@ -441,17 +465,20 @@ tracker_sparql_statement_update (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update_async: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Asynchronously executes the SPARQL update query with the currently bound values. + * Executes asynchronously the `INSERT`/`DELETE` SPARQL query series with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * `INSERT`/`DELETE` statements loaded through + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on + * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries. * * Since: 3.5 */ @@ -472,12 +499,12 @@ tracker_sparql_statement_update_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update_finish: - * @stmt: a #TrackerSparqlStatement - * @result: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor - * @error: The error which occurred or %NULL + * @stmt: a `TrackerSparqlStatement` + * @result: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * * Finishes the asynchronous update started through - * tracker_sparql_statement_update_async(). + * [method@Tracker.SparqlStatement.update_async]. * * Returns: %TRUE if the update finished with no errors, %FALSE otherwise * @@ -500,11 +527,9 @@ tracker_sparql_statement_update_finish (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_clear_bindings: - * @stmt: a #TrackerSparqlStatement - * - * Clears all boolean/string/integer/double bindings. + * @stmt: a `TrackerSparqlStatement` * - * Since: 3.0 + * Clears all bindings. */ void tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) @@ -516,17 +541,18 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_serialize_async: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @flags: serialization flags * @format: RDF format of the serialized data - * @cancellable: (nullable): a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Serializes data into the specified RDF format. The query @stmt was - * created from must be either a `DESCRIBE` or `CONSTRUCT` query, an - * error will be raised otherwise. + * Serializes a `DESCRIBE` or `CONSTRUCT` query into the given RDF @format. + * + * The query @stmt was created from must be either a `DESCRIBE` or `CONSTRUCT` + * query, an error will be raised otherwise. * * This is an asynchronous operation, @callback will be invoked when the * data is available for reading. @@ -535,7 +561,7 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) * an error will be raised. * * The @flags argument is reserved for future expansions, currently - * %TRACKER_SERIALIZE_FLAGS_NONE must be passed. + * #TRACKER_SERIALIZE_FLAGS_NONE must be passed. * * Since: 3.3 **/ @@ -562,14 +588,14 @@ tracker_sparql_statement_serialize_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_serialize_finish: - * @stmt: a #TrackerSparqlStatement - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @stmt: a `TrackerSparqlStatement` + * @result: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_statement_serialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the asynchronous operation started through + * [method@Tracker.SparqlStatement.serialize_async]. * - * Returns: (transfer full): a #GInputStream to read RDF content. + * Returns: (transfer full): a [class@Gio.InputStream] to read RDF content. * * Since: 3.3 **/ diff --git a/src/libtracker-sparql/tracker-statement.h b/src/libtracker-sparql/tracker-statement.h index fc551e89a..3de04f797 100644 --- a/src/libtracker-sparql/tracker-statement.h +++ b/src/libtracker-sparql/tracker-statement.h @@ -28,12 +28,6 @@ G_BEGIN_DECLS -/** - * TrackerSparqlStatement: - * - * The <structname>TrackerSparqlStatement</structname> object represents - * a prepared query statement. - */ #define TRACKER_TYPE_SPARQL_STATEMENT tracker_sparql_statement_get_type () #define TRACKER_SPARQL_TYPE_STATEMENT TRACKER_TYPE_SPARQL_STATEMENT TRACKER_AVAILABLE_IN_ALL diff --git a/src/libtracker-sparql/tracker-uri.c b/src/libtracker-sparql/tracker-uri.c index 9238c50cb..135f5ddf7 100644 --- a/src/libtracker-sparql/tracker-uri.c +++ b/src/libtracker-sparql/tracker-uri.c @@ -19,16 +19,6 @@ * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-uri - * @short_description: URI utility functions - * @title: URI Utilities - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h - * - * Tracker defines some utility functions to deal with URI strings. - */ - #include "config.h" #include <string.h> @@ -163,14 +153,13 @@ find_conversion (const char *format, * <link linkend="string-precision">string precision pitfalls</link> documented in g_strdup_printf() * @args: the list of parameters to insert into the format string * + * Formats and escapes a string for use as a URI. This function takes a `va_list`. + * * Similar to the standard C vsprintf() function but safer, since it * calculates the maximum space required and allocates memory to hold * the result. * - * The result is escaped using g_uri_escape_string(). - * - * Returns: (transfer full): a newly-allocated string holding the result. The returned string - * should be freed with g_free() when no longer needed. + * Returns: (transfer full): a newly-allocated string holding the result. */ gchar * tracker_sparql_escape_uri_vprintf (const gchar *format, @@ -269,7 +258,7 @@ cleanup: * <link linkend="string-precision">string precision pitfalls</link> documented in g_strdup_printf() * @...: the parameters to insert into the format string * - * Calls tracker_sparql_escape_uri_vprintf() with the @... supplied. + * Formats and escapes a string for use as a URI. This function takes variadic arguments. * * Returns: (transfer full): a newly-allocated string holding the result.The returned string * should be freed with g_free() when no longer needed. @@ -291,10 +280,9 @@ tracker_sparql_escape_uri_printf (const gchar *format, ...) * tracker_sparql_escape_uri: * @uri: a string to be escaped, following the tracker sparql rules * - * Calls tracker_sparql_escape_uri_printf(). + * Escapes a string for use as a URI. * - * Returns: (transfer full): a newly-allocated string holding the result. The returned string - * should be freed with g_free() when no longer needed. + * Returns: (transfer full): a newly-allocated string holding the result. */ gchar * tracker_sparql_escape_uri (const gchar *uri) diff --git a/src/libtracker-sparql/tracker-utils.c b/src/libtracker-sparql/tracker-utils.c index 063559793..1f4639a23 100644 --- a/src/libtracker-sparql/tracker-utils.c +++ b/src/libtracker-sparql/tracker-utils.c @@ -16,15 +16,6 @@ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-misc - * @short_description: miscellaneous functionality - * @title: Utility Functions - * @stability: Stable - * @include: tracker-sparql.h - * - * Collection of Tracker utility functions. - */ #include "config.h" @@ -37,9 +28,10 @@ * @literal: a string to escape * * Escapes @literal so it is suitable for insertion in - * SPARQL queries as string literals. Manual construction - * of query strings based user input is best avoided at - * all cost, use of #TrackerSparqlStatement is recommended + * SPARQL queries as string literals. + * + * Manual construction of query strings based user input is best + * avoided at all cost, use of #TrackerSparqlStatement is recommended * instead. * * Returns: (transfer full): the escaped string diff --git a/src/libtracker-sparql/tracker-version.c b/src/libtracker-sparql/tracker-version.c index 7fd829482..ce5f9bb0d 100644 --- a/src/libtracker-sparql/tracker-version.c +++ b/src/libtracker-sparql/tracker-version.c @@ -16,17 +16,6 @@ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-version - * @short_description: variables and functions to check Tracker version - * @title: Version Information - * @stability: Stable - * @include: tracker-sparql.h - * - * Tracker provides version information, primarily useful in configure checks - * for builds that have a configure script. Applications will not typically use - * the features described here. - */ #include "config.h" @@ -47,9 +36,10 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE; * @required_minor: the required minor version. * @required_micro: the required micro version. * - * Checks that the Tracker library in use is compatible with the - * given version. Generally you would pass in the constants - * #TRACKER_MAJOR_VERSION, #TRACKER_MINOR_VERSION, #TRACKER_MICRO_VERSION + * Checks that the Tracker library in use is compatible with the given version. + * + * Generally you would pass in the constants + * [const@Tracker.MAJOR_VERSION], [const@Tracker.MINOR_VERSION], [const@Tracker.MICRO_VERSION] * as the three arguments to this function; that produces * a check that the library in use is compatible with * the version of Tracker the application or module was compiled @@ -57,15 +47,13 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE; * * Compatibility is defined by two things: first the version * of the running library is newer than the version - * @required_major.required_minor.@required_micro. Second + * @required_major.@required_minor.@required_micro. Second * the running library must be binary compatible with the - * version @required_major.required_minor.@required_micro + * version @required_major.@required_minor.@required_micro * (same major version.) * * Return value: %NULL if the Tracker library is compatible with the * given version, or a string describing the version mismatch. - * The returned string is owned by Tracker and must not be modified - * or freed. **/ const gchar * tracker_check_version (guint required_major, diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap new file mode 100644 index 000000000..98cd92118 --- /dev/null +++ b/subprojects/gi-docgen.wrap @@ -0,0 +1,6 @@ +[wrap-git] +directory=gi-docgen +url=https://gitlab.gnome.org/GNOME/gi-docgen.git +push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git +revision=main +depth=1 diff --git a/tests/core/tracker-sparql-test.c b/tests/core/tracker-sparql-test.c index 0da6acafa..d74378c91 100644 --- a/tests/core/tracker-sparql-test.c +++ b/tests/core/tracker-sparql-test.c @@ -629,17 +629,6 @@ main (int argc, char **argv) for (i = 0; tests[i].test_name; i++) { gchar *testpath; -#ifndef HAVE_LIBICU - /* Skip tests which fail collation tests and are known - * to do so. For more details see: - * - * https://bugzilla.gnome.org/show_bug.cgi?id=636074 - */ - if (strcmp (tests[i].test_name, "functions/functions-xpath-2") == 0) { - continue; - } -#endif - testpath = g_strconcat ("/core/sparql/", tests[i].test_name, NULL); g_test_add (testpath, TestInfo, &tests[i], setup, test_sparql_query, teardown); g_free (testpath); diff --git a/tests/libtracker-common/tracker-file-utils-test.c b/tests/libtracker-common/tracker-file-utils-test.c index 013e0c7d9..0d9bdd31a 100644 --- a/tests/libtracker-common/tracker-file-utils-test.c +++ b/tests/libtracker-common/tracker-file-utils-test.c @@ -28,7 +28,6 @@ #include <gio/gio.h> #include <libtracker-common/tracker-file-utils.h> -#include <libtracker-common/tracker-locale.h> #include <tracker-test-helpers.h> diff --git a/tests/libtracker-common/tracker-parser.c b/tests/libtracker-common/tracker-parser.c index db9ae2898..f3869c135 100644 --- a/tests/libtracker-common/tracker-parser.c +++ b/tests/libtracker-common/tracker-parser.c @@ -114,25 +114,16 @@ load_file_contents (void) static gboolean run_parsing (void) { - TrackerLanguage *language; TrackerParser *parser; GTimer *timer; /* Initialize timing */ timer = g_timer_new (); - /* Setup language for parser */ - language = tracker_language_new (NULL); - if (!language) { - g_printerr ("Language setup failed!\n"); - return FALSE; - } - /* Create the parser */ - parser = tracker_parser_new (language); + parser = tracker_parser_new (); if (!parser) { g_printerr ("Parser creation failed!\n"); - g_object_unref (language); return FALSE; } @@ -214,7 +205,6 @@ run_parsing (void) g_timer_destroy (timer); tracker_parser_free (parser); - g_object_unref (language); return TRUE; } diff --git a/tests/libtracker-common/tracker-utils-test.c b/tests/libtracker-common/tracker-utils-test.c index 086c27185..33f9a23aa 100644 --- a/tests/libtracker-common/tracker-utils-test.c +++ b/tests/libtracker-common/tracker-utils-test.c @@ -23,7 +23,6 @@ #include <glib-object.h> #include <libtracker-common/tracker-file-utils.h> #include <libtracker-common/tracker-utils.h> -#include <libtracker-common/tracker-locale.h> #include <locale.h> static void |
