Managing ontology documents

Ontology reading, editing and writing functionality is exposed via the CowlManager API. A CowlManager instance manages multiple ontology documents.

struct CowlManager : public CowlObject 

Manages ontology documents.

CowlManager supports multiple input sources, such as files, memory buffers, or buffered streams. It also supports multiple readers, either built-in or provided by the user.

Reading

Ontologies can be read from files, memory buffers or input streams (see UIStream). Cowl can attempt ontology deserialization via multiple readers, and you can control which reader is 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. Built-in readers are exposed through cowl_reader_*() functions.
At run-time, globally: you can set the default reader by calling cowl_set_reader().
At run-time, locally: you can specify which reader you want CowlManager to use via CowlManager::cowl_manager_set_reader().

You can integrate additional readers by providing suitably populated CowlReader instances. When implementing one, use the provided CowlOntology instance for CRUD operations over the ontology object. Refer to the built-in readers if you need guidance.

struct CowlReader

Defines a reader.

Public Members

char const *name: Name of the reader.

void *(*alloc)(void)

Pointer to a function that allocates the reader’s state and reserves any needed resource.

Note

This member is optional.

Return: Reader state.

void (*free)(void *state)

Pointer to a function that deallocates the reader’s state and releases reserved resources.

Note

This member is optional.

Param state: Reader state.

cowl_ret (*read)(void *state, UIStream *istream, CowlStream *stream)

Pointer to a function that reads an ontology from an input stream.

Note

This member is mandatory.

Param state: Reader state.
Param istream: Input stream.
Param stream: Ontology stream.
Return: Return code.

CowlReader cowl_reader_functional(void)

Returns the functional syntax reader.

Returns: Functional syntax reader.

Import handling

Cowl delegates locating and loading imported ontologies to the end user via the CowlImportLoader interface. Import loaders can be either provided locally to specific objects (such as via CowlManager::cowl_manager_set_import_loader()), or you can opt to specify a global import loader via cowl_set_import_loader(). If you do both, Cowl prioritizes local loaders, as you would expect.

struct CowlImportLoader

Provides a mechanism for generic handling of ontology imports.

The CowlImportLoader::load_ontology function should return the ontology having the specified CowlIRI. Imports retrieval and loading is deliberately left to the implementor.

Public Members

void *ctx: Loader context, can be anything.

CowlOntology *(*load_ontology)(void *ctx, CowlIRI *iri)

Pointer to a function that returns the ontology having the specified IRI.

Param ctx: Loader context.
Param iri: IRI of the ontology to load.
Return: The imported ontology, or NULL on error.

void (*free)(void *ctx)

Pointer to a resource deallocator function for the context.

Note

Can be NULL if the context does not need to release resources.

Param ctx: Loader context.

Ontology streams

Other than deserializing ontologies into CowlOntology objects, Cowl supports a more lightweight abstraction to access ontology contents by means of CowlStream instances. You can stream through ontologies by calling the related CowlManager APIs (such as CowlManager::cowl_manager_stream_path()) and providing suitably populated CowlStreamConfig objects.

struct CowlStream : public CowlObject 

Ontology streams.

A lightweight way to access knowledge without deserializing ontologies into CowlOntology objects.

Editing

Ontologies can be edited by adding or removing axioms, annotations and other constructs, as allowed by the CowlOntology API. They can also be created from scratch by calling CowlManager::cowl_manager_get_ontology() and specifying a unique CowlOntologyId or a NULL one (in which case an anonymous ontology is created).

Access to syntactical details that are not relevant to logic, such as the mapping between prefixed and full IRIs, is provided by a CowlSymTable instance retrievable by calling CowlOntology::cowl_ontology_get_sym_table().

struct CowlSymTable

Maps symbols to OWL constructs.

Public Functions

CowlTable *cowl_sym_table_get_prefix_ns_map(CowlSymTable *st, bool reverse)

Gets the map that associates prefixes to namespaces.

Parameters

st – The symbol table.
reverse – If true, the reversed map (namespaces to prefixes) is returned.

Returns

Prefix to namespace map, or NULL on error.

CowlString *cowl_sym_table_get_ns(CowlSymTable *st, CowlString *prefix)

Returns the namespace associated with the specified prefix.

Parameters

st – The symbol table.
prefix – The prefix.

Returns

Namespace associated with the prefix, or NULL if the prefix cannot be found.

CowlString *cowl_sym_table_get_prefix(CowlSymTable *st, CowlString *ns)

Returns the prefix associated with the specified namespace.

Parameters

st – The symbol table.
ns – The namespace.

Returns

Prefix associated with the namespace, or NULL if the prefix cannot be found.

cowl_ret cowl_sym_table_register_prefix(CowlSymTable *st, CowlString *prefix, CowlString *ns)

Registers the specified prefix-namespace mapping.

Parameters

st – The symbol table.
prefix – The prefix.
ns – The namespace.

Returns

Return code.

cowl_ret cowl_sym_table_register_prefix_raw(CowlSymTable *st, UString prefix, UString ns)

Registers the specified prefix-namespace mapping.

Parameters

st – The symbol table.
prefix – The prefix.
ns – The namespace.

Returns

Return code.

CowlIRI *cowl_sym_table_get_full_iri(CowlSymTable *st, UString ns, UString rem)

Retrieves the full IRI associated with the specified short IRI.

Parameters

st – The symbol table.
ns – The short namespace.
rem – The remainder.

Returns

IRI instance, or NULL on error.

CowlIRI *cowl_sym_table_parse_full_iri(CowlSymTable *st, UString short_iri)

Retrieves the full IRI associated with the specified short IRI.

Parameters

st – The symbol table.
short_iri – The short IRI.

Returns

IRI instance, or NULL on error.

Writing

Similarly to reading, Cowl can write ontologies to files, buffers or custom output streams (see UOStream). You can control which writer is used in a number of ways:

At compile-time: writers included in the compiled library can be selected by setting the COWL_WRITERS CMake variable. Built-in writers are exposed through cowl_writer_*() functions.
At run-time, globally: you can set the default writer by calling cowl_set_writer().
At run-time, locally: you can specify which writer you want CowlManager to use via CowlManager::cowl_manager_set_writer().

Additional writers can be integrated by providing suitably populated CowlWriter instances. Refer to the built-in writers if you need guidance.

struct CowlWriter

Defines a writer.

Public Members

char const *name: Name of the writer.

void *(*alloc)(void)

Pointer to a function that allocates the writer’s state and reserves any needed resource.

Note

This member is optional.

Return: Writer state.

void (*free)(void *state)

Pointer to a function that deallocates the writer’s state and releases reserved resources.

Note

This member is optional.

Param state: Writer state.

cowl_ret (*write_ontology)(void *state, UOStream *stream, CowlOntology *ontology)

Pointer to a function that writes an ontology to an output stream.

Note

This member is mandatory.

Param state: Writer state.
Param stream: Output stream.
Param ontology: Ontology.
Return: Return code.

cowl_ret (*write)(UOStream *stream, CowlAny *object)

Pointer to a function that writes an object to an output stream.

Note

This member is optional.

Note

As denoted by the lack of the state parameter, the writer must be stateless in order to implement this function.

Param stream: Output stream.
Param object: Object to write.
Return: Return code.

cowl_ret cowl_write(UOStream *stream, CowlAny *object)

Writes an object to the specified stream via the default writer.

Note

If no default writer is set, falls back to cowl_write_debug.

Parameters

stream – Output stream.
object – Object.

Returns

Return code.

ustream_ret cowl_write_debug(UOStream *stream, CowlAny *object)

Writes a debug representation of an object to the specified output stream.

Parameters

stream – Output stream.
object – Object.

Returns

Return code.

ustream_ret cowl_write_string(UOStream *stream, CowlString *string)

Writes a string to the specified output stream.

Parameters

stream – Output stream.
string – String.

Returns

Return code.

ustream_ret cowl_write_iri(UOStream *stream, CowlIRI *iri)

Writes an IRI to the specified output stream.

Parameters

stream – Output stream.
iri – IRI.

Returns

Return code.

ustream_ret cowl_write_object_type(UOStream *stream, CowlObjectType type)

Writes the object type to the specified output stream.

Parameters

stream – Output stream.
type – Object type.

Returns

Return code.

ustream_ret cowl_write_uint(UOStream *stream, ulib_uint uint)

Writes an unsigned integer to the specified output stream.

Parameters

stream – Output stream.
uint – Unsigned integer.

Returns

Return code.

ustream_ret cowl_write_error(UOStream *stream, CowlError const *error)

Writes an human readable representation of an error to the specified output stream.

Parameters

stream – Output stream.
error – Error.

Returns

Return code.

static inline ustream_ret cowl_write_ustring(UOStream *stream, UString const *string)

Writes a string to the specified output stream.

Parameters

stream – [UOStream *] Output stream.
string – [UString const *] String.

Returns

[ustream_ret] Return code.

cowl_write_static(stream, string)

Writes a string literal to the specified output stream.

Parameters

stream – [UOStream *] Output stream.
string – [char const[]] String.

Returns

[ustream_ret] Return code.