Examples

The following examples are designed to get you started using Cowl. They are ordered by complexity, so it is recommended that you read them sequentially.

Reading ontologies

Related documentation: ontology reading

/*
 * This introductory example shows how to read an ontology
 * and log its axioms and annotations.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2019 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.h"
#include "ulib.h"
#include <stdio.h>
#include <stdlib.h>

#define ONTO "example_pizza.owl"

int main(void) {
    // The library must always be initialized before use.
    cowl_init();

    // Read an ontology from file.
    CowlOntology *onto = cowl_ontology_from_path(ustring_literal(ONTO), NULL);

    if (!onto) {
        // The ontology could not be read.
        fprintf(stderr, "Failed to load ontology " ONTO "\n");
        return EXIT_FAILURE;
    }

    // Do stuff with the ontology. In this case it is simply logged
    // to the standard output using the default writer.
    cowl_ontology_to_stream(onto, uostream_std());

    // Release the ontology.
    cowl_release(onto);

    return EXIT_SUCCESS;
}

Error handling

Related documentation: error handling

/*
 * This example is the same as the previous one,
 * except all errors are handled and logged.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2019 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.h"
#include "ulib.h"
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define ONTO "example_pizza.owl"

static void log_error(char const *msg) {
    fprintf(stderr, "Error: %s\n", msg);
}

static void log_cowl_error(CowlError const *error) {
    // Cowl integrates with the uLib I/O API. This is usually preferable as it allows
    // writing most objects, including errors, to output streams without needing to
    // convert them to strings first (i.e. without additional allocations).
    UOStream *stream = uostream_stderr();
    cowl_write_literal(stream, "Error: ");
    cowl_write_error(stream, error);
    cowl_write_literal(stream, "\n");
}

int main(void) {
    // API initialization can fail due to low memory.
    if (cowl_is_err(cowl_init())) {
        log_error("API initialization failure");
        return EXIT_FAILURE;
    }

    // Cowl objects are allocated on the heap, so we need to check for NULL.
    CowlReader *reader = cowl_reader_functional();

    if (!reader) {
        log_error("allocation failure");
        return EXIT_FAILURE;
    }

    UString const path = ustring_literal(ONTO);

    // The returned ontology is NULL if an error occurs during reading,
    // e.g. due to I/O or syntax errors. More details about the error can be obtained
    // by inspecting the return code.
    cowl_ret ret;
    CowlOntology *onto = cowl_reader_read_ontology_from_path(reader, path, &ret);

    if (!onto) {
        if (ret == COWL_ERR_IO) {
            // An I/O error occurred, e.g. the file does not exist or is not
            // readable. Further details can be obtained by inspecting `errno`.
            log_error(errno ? strerror(errno) : "unknown I/O error");
        } else if (ret == COWL_ERR_SYNTAX) {
            // In case of syntax errors, we can log the last one.
            log_cowl_error(cowl_reader_last_error(reader));
        } else {
            // Some other error occurred.
            log_error("ontology read failure");
        }
        return EXIT_FAILURE;
    }

    // Stream operations can fail, so we need to check for errors.
    ret = cowl_ontology_to_stream(onto, uostream_std());

    if (cowl_is_err(ret)) {
        log_error("ontology write failure");
        return EXIT_FAILURE;
    }

    cowl_release_all(onto, reader);
    return EXIT_SUCCESS;
}

Querying ontologies

Related documentation: ontology querying

Basic queries

/*
 * In this example we will be logging the direct atomic subclasses of a class.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2019 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.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 "Food"

// Iterator body, invoked for each class expression matching the query.
static cowl_ret for_each_cls(void *std_out, CowlAny *cls) {
    // We are only interested in atomic classes. Note that due to pseudo-inheritance
    // this check ensures that the concrete type of 'exp' is CowlClass.
    if (cowl_cls_exp_get_type(cls) == COWL_CET_CLASS) {
        cowl_write_string(std_out, cowl_get_rem(cls));
        cowl_write_literal(std_out, "\n");
    }
    return COWL_CONTINUE;
}

int main(void) {
    cowl_init();

    CowlOntology *onto = cowl_ontology_from_path(ustring_literal(ONTO), NULL);

    if (!onto) {
        fprintf(stderr, "Failed to load ontology " ONTO "\n");
        return EXIT_FAILURE;
    }

    // Get the class whose atomic subclasses we are interested in.
    CowlClass *cls = cowl_class_from_literal(NS CLASS_NAME);

    // Run the query.
    cowl_write_literal(uostream_std(), "Subclasses of " CLASS_NAME ":\n");

    CowlIterator iter = { uostream_std(), for_each_cls };
    cowl_ontology_iterate_sub_classes(onto, cls, &iter);

    // Cleanup.
    cowl_release_all(cls, onto);

    return EXIT_SUCCESS;
}

Recursive queries

/*
 * In this example we will be logging the atomic subclasses of a class recursively.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2019 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.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 "Food"

// Custom context struct for the query.
typedef struct CustomContext {
    CowlOntology *onto;
    UOStream *stream;
} CustomContext;

// Iterator body, invoked for each class expression matching the query.
static cowl_ret for_each_cls(void *ptr, CowlAny *cls) {
    if (cowl_cls_exp_get_type(cls) != COWL_CET_CLASS) return COWL_CONTINUE;

    // Log the IRI remainder.
    CustomContext *ctx = ptr;
    cowl_write_string(ctx->stream, cowl_get_rem(cls));
    cowl_write_literal(ctx->stream, "\n");

    // Recurse.
    CowlIterator iter = { ctx, for_each_cls };
    return cowl_ontology_iterate_sub_classes(ctx->onto, cls, &iter);
}

int main(void) {
    cowl_init();

    CowlOntology *onto = cowl_ontology_from_path(ustring_literal(ONTO), NULL);

    if (!onto) {
        fprintf(stderr, "Failed to load ontology " ONTO "\n");
        return EXIT_FAILURE;
    }

    CowlClass *cls = cowl_class_from_literal(NS CLASS_NAME);
    cowl_write_literal(uostream_std(), "Recursive subclasses of " CLASS_NAME ":\n");

    // Since we are going to perform a recursive query,
    // we need the ontology to be part of the context.
    CustomContext ctx = { onto, uostream_std() };
    CowlIterator iter = { &ctx, for_each_cls };
    cowl_ontology_iterate_sub_classes(onto, cls, &iter);

    cowl_release_all(cls, onto);
    return EXIT_SUCCESS;
}

Advanced queries

/*
 * In this example we will be logging axioms of different types referencing
 * multiple entities.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2024 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://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"

int main(void) {
    cowl_init();

    CowlOntology *onto = cowl_ontology_from_path(ustring_literal(ONTO), NULL);

    if (!onto) {
        fprintf(stderr, "Failed to load ontology " ONTO "\n");
        return EXIT_FAILURE;
    }

    cowl_write_literal(uostream_std(), "Matching axioms:\n");
    CowlClass *cls = cowl_class_from_literal(NS CLASS_NAME);
    CowlObjProp *prop = cowl_obj_prop_from_literal(NS PROPERTY_NAME);

    // We want to log all SubClassOf and EquivalentClasses axioms that
    // reference both the class and the property.

    // Note that this query can be done via other functions as well,
    // though using a CowlAxiomFilter is usually more efficient, as it
    // is used 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);

    // Other than using custom iterators, Cowl provides some built-in ones
    // for common tasks. Here we use a set iterator: all axioms matching
    // the filter will be collected in a set, removing any duplicates.
    UHash(CowlObjectPtr) set = uhset(CowlObjectPtr);
    CowlIterator iter = cowl_iterator_set(&set, false);
    cowl_ontology_iterate_axioms_matching(onto, &filter, &iter);

    // [Optional] Adding the pizza prefix to the default prefix map
    // allows for more concise IRIs when logging the axioms.
    CowlPrefixMap *pm = cowl_get_prefix_map();
    UString const prefix = ustring_literal("pizza");
    UString const ns = ustring_literal(NS);
    cowl_prefix_map_add_raw(pm, prefix, ns, false);

    // We can now log the axioms by iterating over the set.
    UOStream *stream = uostream_std();
    uhash_foreach (CowlObjectPtr, &set, item) {
        cowl_write(stream, *item.key);
        cowl_write_literal(stream, "\n");
    }

    uhash_deinit(CowlObjectPtr, &set);
    cowl_release_all(cls, prop, onto);
    return EXIT_SUCCESS;
}

Editing and writing ontologies

Related documentation: ontology editing, ontology writing

/*
 * This example demonstrates ontology editing and serialization to file.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2022 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.h"
#include "ulib.h"
#include <stdio.h>
#include <stdlib.h>

#define IN_PATH "example_pizza.owl"
#define OUT_PATH "example_pizza_new.owl"
#define NS "http://www.co-ode.org/ontologies/pizza/pizza.owl#"

int main(void) {
    cowl_init();

    // We will be editing the pizza ontology by adding the Porcini pizza.
    printf("Reading ontology " IN_PATH "... ");
    CowlOntology *onto = cowl_ontology_from_path(ustring_literal(IN_PATH), NULL);

    if (onto) {
        puts("done!");
    } else {
        puts("failed");
        return EXIT_FAILURE;
    }

    // Declaration(Class(pizza:PorciniTopping))
    CowlClass *porcini_topping = cowl_class_from_literal(NS "PorciniTopping");
    CowlAnyAxiom *axiom = cowl_decl_axiom(porcini_topping, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release(axiom);

    // Declaration(Class(pizza:Porcini))
    CowlClass *porcini = cowl_class_from_literal(NS "Porcini");
    axiom = cowl_decl_axiom(porcini, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release(axiom);

    // SubClassOf(pizza:PorciniTopping pizza:MushroomTopping)
    CowlClass *mushroom_topping = cowl_class_from_literal(NS "MushroomTopping");
    axiom = cowl_sub_cls_axiom(porcini_topping, mushroom_topping, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release_all(axiom, mushroom_topping);

    // SubClassOf(pizza:Porcini pizza:NamedPizza)
    CowlClass *named_pizza = cowl_class_from_literal(NS "NamedPizza");
    axiom = cowl_sub_cls_axiom(porcini, named_pizza, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release_all(axiom, named_pizza);

    // SubClassOf(pizza:Porcini
    // ObjectSomeValuesFrom(pizza:hasTopping pizza:MozzarellaTopping))
    CowlObjProp *has_topping = cowl_obj_prop_from_literal(NS "hasTopping");
    CowlClass *mozzarella_topping = cowl_class_from_literal(NS "MozzarellaTopping");
    CowlObjQuant *obj_quant = cowl_obj_some(has_topping, mozzarella_topping);
    axiom = cowl_sub_cls_axiom(porcini, obj_quant, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release_all(axiom, obj_quant, mozzarella_topping);

    // SubClassOf(pizza:Porcini
    // ObjectSomeValuesFrom(pizza:hasTopping pizza:PorciniTopping))
    obj_quant = cowl_obj_some(has_topping, porcini_topping);
    axiom = cowl_sub_cls_axiom(porcini, obj_quant, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release_all(axiom, obj_quant);

    // SubClassOf(pizza:Porcini ObjectAllValuesFrom(pizza:hasTopping
    // ObjectUnionOf(pizza:MozzarellaTopping pizza:PorciniTopping)))
    CowlNAryCls *closure = cowl_obj_union_of(mozzarella_topping, porcini_topping);
    obj_quant = cowl_obj_all(has_topping, closure);
    axiom = cowl_sub_cls_axiom(porcini, obj_quant, NULL);
    cowl_ontology_add_axiom(onto, axiom);
    cowl_release_all(axiom, obj_quant, closure);
    cowl_release_all(porcini_topping, porcini, has_topping);

    // Serialize the edited ontology to a new file.
    printf("Writing ontology " OUT_PATH "... ");
    cowl_ret ret = cowl_ontology_to_path(onto, ustring_literal(OUT_PATH));

    if (cowl_is_err(ret)) {
        puts("failed");
    } else {
        puts("done!");
    }

    cowl_release(onto);
    return EXIT_SUCCESS;
}

Ontology streams

Related documentation: input streams, output streams

Input streams

/*
 * In this example we will be logging the direct atomic subclasses
 * of a certain class, but we will do so without instantiating a
 * CowlOntology object.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2023 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */
#include "cowl.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 "Food"

// Change handler, invoked for each construct read from the ontology document.
static cowl_ret handle_axiom(void *target_class, CowlChange change) {
    // We are only interested in subclass axioms.
    if (change.part != COWL_PART_AXIOM) return COWL_OK;

    CowlAnyAxiom *axiom = change.value;
    if (cowl_axiom_get_type(axiom) != COWL_AT_SUB_CLASS) return COWL_OK;

    // We are only interested in axioms where the superclass is the target class.
    CowlAnyClsExp *cls = cowl_sub_cls_axiom_get_super(axiom);
    if (!cowl_equals(target_class, cls)) return COWL_OK;

    // We are only interested in axioms where the subclass is atomic.
    cls = cowl_sub_cls_axiom_get_sub(axiom);
    if (cowl_cls_exp_get_type(cls) != COWL_CET_CLASS) return COWL_OK;

    // Log the IRI remainder.
    puts(cowl_string_get_cstring(cowl_get_rem(cls)));
    return COWL_OK;
}

int main(void) {
    cowl_init();

    CowlClass *target_class = cowl_class_from_literal(NS CLASS_NAME);

    // Configure the change handler for the incoming stream.
    CowlChangeHandler handler = {
        .ctx = target_class,
        .handle = handle_axiom,
    };

    // Process the ontology document as a stream of changes.
    puts("Atomic subclasses of " CLASS_NAME ":");
    CowlReader *reader = cowl_get_reader();
    if (cowl_reader_read_path(reader, ustring_literal(ONTO), handler)) {
        return EXIT_FAILURE;
    }

    cowl_release(target_class);
    return EXIT_SUCCESS;
}

Output streams

/*
 * In this example we will be creating a new ontology document by using an
 * ontology output stream.
 *
 * @note Most errors are not handled for the sake of simplicity.
 *
 * @author Ivano Bilenchi
 *
 * @copyright Copyright (c) 2023 SisInf Lab, Polytechnic University of Bari
 * @copyright <https://swot.sisinflab.poliba.it>
 * @copyright SPDX-License-Identifier: EPL-2.0
 */

#include "cowl.h"
#include "ulib.h"
#include <stdio.h>
#include <stdlib.h>

#define PATH "porcini_pizza.owl"

#define IMPORT_IRI "http://www.co-ode.org/ontologies/pizza"
#define IMPORT_NS IMPORT_IRI "/pizza.owl#"

#define IRI "http://example.com/ontologies/porcini_pizza"
#define NS IRI "/porcini_pizza.owl#"

int main(void) {
    cowl_init();

    printf("Generating ontology " PATH "... ");

    UOStream ostream;
    if (uostream_to_path(&ostream, PATH)) {
        // Initializing and writing to the stream may fail.
        // IO errors should be handled as fit for the application.
        goto err_io;
    }

    CowlWriter *writer = cowl_get_writer();

    // Optional: setup prefixes so that IRIs can be rendered in their prefixed form.
    CowlPrefixMap *map = cowl_prefix_map();
    cowl_prefix_map_add_raw(map, ustring_literal(""), ustring_literal(NS), false);
    cowl_prefix_map_add_raw(map, ustring_literal("pizza"),
                            ustring_literal(IMPORT_NS), false);

    // Write the ontology header.
    CowlIRI *iri = cowl_iri_from_literal(IRI);
    CowlIRI *import_iri = cowl_iri_from_literal(IMPORT_IRI);
    UVec(CowlObjectPtr) imports = uvec(CowlObjectPtr);
    uvec_push(CowlObjectPtr, &imports, import_iri);

    CowlOntologyHeader header = {
        .pm = map,
        .iri = iri,
        .imports = &imports,
    };

    if (cowl_writer_write_header(writer, &ostream, header)) goto err_io;

    cowl_release_all(iri, import_iri, map);
    uvec_deinit(CowlObjectPtr, &imports);

    // Write the axioms.
    // Declaration(Class(:PorciniTopping))
    CowlClass *porcini = cowl_class_from_literal(NS "PorciniTopping");
    CowlAnyAxiom *axiom = cowl_decl_axiom(porcini, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release(axiom);

    // Declaration(Class(:Porcini))
    CowlClass *porcini_pizza = cowl_class_from_literal(NS "Porcini");
    axiom = cowl_decl_axiom(porcini_pizza, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release(axiom);

    // SubClassOf(:PorciniTopping pizza:MushroomTopping)
    CowlClass *mushroom = cowl_class_from_literal(IMPORT_NS "MushroomTopping");
    axiom = cowl_sub_cls_axiom(porcini, mushroom, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release_all(axiom, mushroom);

    // SubClassOf(:Porcini pizza:NamedPizza)
    CowlClass *named_pizza = cowl_class_from_literal(IMPORT_NS "NamedPizza");
    axiom = cowl_sub_cls_axiom(porcini_pizza, named_pizza, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release_all(axiom, named_pizza);

    // SubClassOf(:Porcini
    // ObjectSomeValuesFrom(pizza:hasTopping pizza:MozzarellaTopping))
    CowlObjProp *has_topping = cowl_obj_prop_from_literal(IMPORT_NS "hasTopping");
    CowlClass *mozzarella = cowl_class_from_literal(IMPORT_NS "MozzarellaTopping");
    CowlObjQuant *obj_quant = cowl_obj_some(has_topping, mozzarella);
    axiom = cowl_sub_cls_axiom(porcini_pizza, obj_quant, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release_all(axiom, obj_quant);

    // SubClassOf(:Porcini
    // ObjectSomeValuesFrom(pizza:hasTopping :PorciniTopping))
    obj_quant = cowl_obj_some(has_topping, porcini);
    axiom = cowl_sub_cls_axiom(porcini_pizza, obj_quant, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release_all(axiom, obj_quant);

    // SubClassOf(:Porcini ObjectAllValuesFrom(pizza:hasTopping
    // ObjectUnionOf(pizza:MozzarellaTopping :PorciniTopping)))
    CowlNAryCls *closure = cowl_obj_union_of(mozzarella, porcini);
    obj_quant = cowl_obj_all(has_topping, closure);
    axiom = cowl_sub_cls_axiom(porcini_pizza, obj_quant, NULL);
    if (cowl_writer_write_axiom(writer, &ostream, axiom)) goto err_io;
    cowl_release_all(axiom, obj_quant, closure);
    cowl_release_all(porcini, porcini_pizza, has_topping, mozzarella);

    // Finally, write the footer.
    if (cowl_writer_write_footer(writer, &ostream)) goto err_io;
    uostream_deinit(&ostream);

    puts("done!");
    return EXIT_SUCCESS;

err_io:
    puts("failed");
    return EXIT_FAILURE;
}