Reading ontologies

Ontology objects

Ontologies can be read from files, memory buffers or input streams (see UIStream). The easiest way to read an ontology is using CowlOntology constructors such as cowl_ontology_from_path() and cowl_ontology_from_stream(). This leverages the default reader to create a fully-fledged ontology object, which can then be queried and edited.

If you wish to use a specific reader, you can instead instantiate a CowlReader object and leverage its APIs, such as cowl_reader_read_ontology() and cowl_reader_read_ontology_from_path().

Reader objects

The architecture of Cowl is designed to support multiple ontology serialization formats. You can control which readers are available and can be used in a number of ways:

• At compile-time: readers included in the compiled library can be selected by setting the COWL_READERS CMake variable, and you can specify a default reader through the COWL_DEFAULT_READER variable. Built-in readers are exposed through cowl_reader_*() functions.

• At run-time: the default reader can be changed by calling cowl_set_reader(). You can also decide to use a specific reader by instantiating a CowlReader object.

Additional readers can be integrated by providing suitably populated CowlReader instances. When implementing one, use the provided CowlChangeHandler object to handle detected OWL constructs. The management of prefixed IRIs can be easened by using CowlPrefixMap objects. Refer to the built-in readers if you need guidance on their implementation.

struct CowlReader

A reader is an object that can read ontologies from an input stream.

Pseudo-extends: CowlObject

CowlReader *cowl_reader_functional(void)

Returns the functional syntax reader.

Note

You must release the returned object via cowl_release().

Returns:

Functional syntax reader, or NULL on error.

CowlReader *cowl_reader_protocowl(void)

Returns the ProtocOWL reader.

Note

You must release the returned object via cowl_release().

Returns:

ProtocOWL reader.

CowlReader *cowl_reader_default(void)

Returns the default reader.

Note

You must release the returned object via cowl_release().

Returns:

Default reader, or NULL on error.

CowlReader *cowl_reader(CowlReaderImpl impl)

Returns a new reader.

Note

You must release the returned object via cowl_release().

Parameters:

• impl – Reader implementation.

Returns:

Reader, or NULL on error.

char const *cowl_reader_get_name(CowlReader *reader)

Returns the name of the reader.

Parameters:

• reader – Reader.

Returns:

Name of the reader.

CowlReaderImpl *cowl_reader_get_impl(CowlReader *reader)

Returns the implementation of the reader.

Parameters:

• reader – Reader.

Returns:

Reader implementation.

cowl_ret cowl_reader_read(CowlReader *reader, UIStream *stream, CowlChangeHandler handler)

Reads an ontology from the specified input stream.

Parameters:

• reader – Reader.

• stream – Input stream.

• handler – Change handler.

Returns:

Return code.

cowl_ret cowl_reader_read_path(CowlReader *reader, UString path, CowlChangeHandler handler)

Reads an ontology from the specified file path.

Parameters:

• reader – Reader.

• path – File path.

• handler – Change handler.

Returns:

Return code.

CowlOntology *cowl_reader_read_ontology(CowlReader *reader, UIStream *stream, cowl_ret *ret)

Reads an ontology from the specified input stream.

Parameters:

• reader – Reader.

• stream – Input stream.

• ret – [out] Return code.

Returns:

Ontology, or NULL on error.

CowlOntology *cowl_reader_read_ontology_from_path(CowlReader *reader, UString path, cowl_ret *ret)

Reads an ontology from the specified file path.

Parameters:

• reader – Reader.

• path – File path.

• ret – [out] Return code.

Returns:

Ontology, or NULL on error.

CowlError const *cowl_reader_last_error(CowlReader *reader)

Returns the last error.

Parameters:

• reader – Reader.

Returns:

Last error, or NULL if no error occurred.

Axiom streams

Other than deserializing ontologies into CowlOntology instances, Cowl supports a more lightweight abstraction to access ontology contents by means of CowlChangeHandler objects. This allows you to process ontologies as streams of axioms and other constructs, without the overhead of building a complete in-memory representation.

By providing a suitably populated CowlChangeHandler object to functions such as cowl_reader_read(), you can read ontology documents as sequences of changes, each represented by a CowlChange struct. Each change indicates whether an OWL construct was added or removed, and provides access to the relevant data, so that you can process it as needed for your application.

struct CowlChangeHandler

Change handler.

Public Members

void *ctx

Context, can be anything.

cowl_ret (*handle)(void *ctx, CowlChange change)

Pointer to a function that handles the specified change.

Param ctx:

Context.

Param change:

Change.

Return:

Return code.

cowl_ret cowl_change_handler_handle(CowlChangeHandler *handler, CowlChange change)

Handles the specified change.

Parameters:

• handler – Change handler.

• change – Change.

Returns:

Return code.

CowlChangeHandler cowl_change_handler_to_ontology(CowlOntology *onto)

Initializes a change handler that modifies the specified ontology.

Parameters:

• onto – Ontology.

Returns:

Change handler.

cowl_ret cowl_change_handler_handle_ontology(CowlChangeHandler *handler, CowlOntology *onto, cowl_change_type type)

Processes the specified ontology as changes of the specified type.

Parameters:

• handler – Change handler.

• onto – Ontology.

• type – Change type.

Returns:

Return code.

enum cowl_part

Ontology part.

Values:

enumerator COWL_PART_PREFIX_DECL

CowlPrefixDecl - prefix declaration.

enumerator COWL_PART_IRI

CowlIRI - ontology IRI.

enumerator COWL_PART_VERSION

CowlIRI - version IRI.

enumerator COWL_PART_IMPORT

CowlIRI - import IRI.

enumerator COWL_PART_ANNOTATION

CowlAnnotation - Annotation.

enumerator COWL_PART_AXIOM

CowlAxiom - Axiom.

enum cowl_change_type

Change type.

Values:

enumerator COWL_CHANGE_ADD

Change is an addition.

enumerator COWL_CHANGE_REMOVE

Change is a removal.

struct CowlPrefixDecl

#include “cowl_change.h”

Prefix to namespace mapping.

Public Members

CowlString *prefix

Prefix.

CowlString *ns

Namespace.

struct CowlChange

#include “cowl_change.h”

A change in the ontology.

Public Members

cowl_change_type type

Change type.

cowl_part part

Part of the ontology that changed.

void *value

Change value.

CowlChange cowl_change(cowl_change_type type, cowl_part part, void *value)

Initializes a change object.

Parameters:

• type – Change type.

• part – Part of the ontology that changed.

• value – Change value.

Returns:

Change object.

CowlChange cowl_change_add(cowl_part part, void *value)

Initializes a change object for an addition.

Parameters:

• part – Part of the ontology that changed.

• value – Change value.

Returns:

Change object.

CowlChange cowl_change_remove(cowl_part part, void *value)

Initializes a change object for a removal.

Parameters:

• part – Part of the ontology that changed.

• value – Change value.

Returns:

Change object.

cowl_ret cowl_change_apply(CowlChange change, CowlOntology *onto)

Applies a change to an ontology.

Parameters:

• change – Change to apply.

• onto – Ontology to apply the change to.

Returns:

Return code.