From 74d767075ecc21a3a21ad33be8b554874037f9f2 Mon Sep 17 00:00:00 2001
From: Ivano Bilenchi <ivanobilenchi@gmail.com>
Date: Wed, 10 Jul 2024 14:33:58 +0200
Subject: [PATCH] Add example for CowlAxiomFilter API

---
 docs/howto/examples.rst                 | 11 ++--
 examples/04_advanced_query.c            | 68 +++++++++++++++++++++++++
 examples/{04_editing.c => 05_editing.c} |  0
 examples/{05_istream.c => 06_istream.c} |  0
 examples/{06_ostream.c => 07_ostream.c} |  0
 5 files changed, 76 insertions(+), 3 deletions(-)
 create mode 100644 examples/04_advanced_query.c
 rename examples/{04_editing.c => 05_editing.c} (100%)
 rename examples/{05_istream.c => 06_istream.c} (100%)
 rename examples/{06_ostream.c => 07_ostream.c} (100%)

diff --git a/docs/howto/examples.rst b/docs/howto/examples.rst
index 8be98884..a3fd646e 100644
--- a/docs/howto/examples.rst
+++ b/docs/howto/examples.rst
@@ -41,12 +41,17 @@ Recursive queries
 
 .. literalinclude:: ../../examples/03_recursive_query.c
 
+Advanced queries
+----------------
+
+.. literalinclude:: ../../examples/04_advanced_query.c
+
 Editing and writing ontologies
 ==============================
 
 Related documentation: :ref:`ontology editing <editing>`, :ref:`ontology writing <writing>`
 
-.. literalinclude:: ../../examples/04_editing.c
+.. literalinclude:: ../../examples/05_editing.c
 
 Ontology streams
 ================
@@ -56,9 +61,9 @@ Related documentation: :ref:`input streams <istream>`, :ref:`output streams <ost
 Input streams
 -------------
 
-.. literalinclude:: ../../examples/05_istream.c
+.. literalinclude:: ../../examples/06_istream.c
 
 Output streams
 --------------
 
-.. literalinclude:: ../../examples/06_ostream.c
+.. literalinclude:: ../../examples/07_ostream.c
diff --git a/examples/04_advanced_query.c b/examples/04_advanced_query.c
new file mode 100644
index 00000000..1a6e930f
--- /dev/null
+++ b/examples/04_advanced_query.c
@@ -0,0 +1,68 @@
+/*
+ * In this example we will be logging axioms of different types referencing
+ * multiple entities.
+ *
+ * @note Memory allocation failures are not handled for the sake of simplicity.
+ *
+ * @author Ivano Bilenchi
+ *
+ * @copyright Copyright (c) 2024 SisInf Lab, Polytechnic University of Bari
+ * @copyright <http://swot.sisinflab.poliba.it>
+ * @copyright SPDX-License-Identifier: EPL-2.0
+ */
+#include "cowl.h"
+#include "cowl_axiom_filter.h"
+#include "cowl_axiom_flags.h"
+#include "cowl_obj_prop.h"
+#include "cowl_writer.h"
+#include "ulib.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+#define ONTO "example_pizza.owl"
+#define NS "http://www.co-ode.org/ontologies/pizza/pizza.owl#"
+#define CLASS_NAME "ThinAndCrispyBase"
+#define PROPERTY_NAME "hasBase"
+
+// Iterator body, invoked for each axiom matching the query.
+static bool for_each_axiom(void *stream, CowlAny *axiom) {
+    cowl_write(stream, axiom);
+    cowl_write_static(stream, "\n");
+    return true;
+}
+
+int main(void) {
+    cowl_init();
+
+    CowlManager *manager = cowl_manager();
+    CowlOntology *onto = cowl_manager_read_path(manager, ustring_literal(ONTO));
+    cowl_release(manager);
+
+    if (!onto) {
+        fprintf(stderr, "Failed to load ontology " ONTO "\n");
+        return EXIT_FAILURE;
+    }
+
+    UOStream *std_out = uostream_std();
+    cowl_write_static(std_out, "Matching axioms:\n");
+    CowlClass *cls = cowl_class_from_static(NS CLASS_NAME);
+    CowlObjProp *prop = cowl_obj_prop_from_static(NS PROPERTY_NAME);
+
+    // We want to log all SubClassOf and EquivalentClasses axioms that reference
+    // both the class and the property.
+
+    // Note that this can be done via other query functions as well, though
+    // using a CowlAxiomFilter is usually more efficient, as it is used
+    // internally to determine the best indexing strategy for the query.
+    CowlAxiomFlags types = COWL_AF_SUB_CLASS | COWL_AF_EQUIV_CLASSES;
+    CowlAxiomFilter filter = cowl_axiom_filter(types);
+    cowl_axiom_filter_add_primitive(&filter, cls);
+    cowl_axiom_filter_add_primitive(&filter, prop);
+
+    CowlIterator iter = { std_out, for_each_axiom };
+    cowl_ontology_iterate_axioms_matching(onto, &filter, &iter, false);
+
+    cowl_axiom_filter_deinit(&filter);
+    cowl_release_all(cls, prop, onto);
+    return EXIT_SUCCESS;
+}
diff --git a/examples/04_editing.c b/examples/05_editing.c
similarity index 100%
rename from examples/04_editing.c
rename to examples/05_editing.c
diff --git a/examples/05_istream.c b/examples/06_istream.c
similarity index 100%
rename from examples/05_istream.c
rename to examples/06_istream.c
diff --git a/examples/06_ostream.c b/examples/07_ostream.c
similarity index 100%
rename from examples/06_ostream.c
rename to examples/07_ostream.c