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 CowlIStream object to handle detected OWL constructs. If you need to manage prefixed IRIs, you can do so through the CowlSymTable instance available by calling CowlIStream::cowl_istream_get_sym_table(). Refer to the built-in readers if you need guidance.

struct CowlReader

Defines a reader.

Public Members

char const *name: Name of the reader.

cowl_ret (*read)(UIStream *istream, CowlIStream *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 input 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 input streams

Other than deserializing ontologies into CowlOntology objects, Cowl supports a more lightweight abstraction to access ontology contents by means of CowlIStream instances, which can be obtained by calling CowlManager::cowl_manager_get_istream(). You must provide a suitably populated CowlIStreamHandlers object, which tells the stream how OWL constructs should be handled.

struct CowlIStream : public CowlObject 

Ontology input stream.

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, bool overwrite)

Registers the specified prefix-namespace mapping.

Parameters

st – The symbol table.
prefix – The prefix.
ns – The namespace.
overwrite – If true, the new mapping overwrites the previous one.

Returns

Return code.

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

Registers the specified prefix-namespace mapping.

Parameters

st – The symbol table.
prefix – The prefix.
ns – The namespace.
overwrite – If true, the new mapping overwrites the previous one.

Returns

Return code.

cowl_ret cowl_sym_table_unregister_prefix(CowlSymTable *st, CowlString *prefix)

Unregisters the specified prefix.

Parameters

st – The symbol table.
prefix – The prefix.

Returns

Return code.

cowl_ret cowl_sym_table_unregister_ns(CowlSymTable *st, CowlString *ns)

Unregisters the specified namespace.

Parameters

st – The symbol table.
ns – The namespace.

Returns

Return code.

cowl_ret cowl_sym_table_merge(CowlSymTable *dst, CowlSymTable *src, bool overwrite)

Merges the contents of a symbol table in the current one.

Parameters

dst – The destination symbol table.
src – The source symbol table.
overwrite – If true, conflicting prefixes are overwritten in the destination.

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.

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

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

Note

This member is mandatory.

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.

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

CowlStreamWriter stream: Contains the streaming implementation of this writer.

Note

This member is optional.

CowlWriter cowl_writer_functional(void)

Returns the functional syntax writer.

Returns: Functional syntax writer.

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.

Ontology output streams

Most OWL syntaxes logically consist of a header, a sequence of axioms, and a closing footer. This allows ontology documents to be serialized in a streaming fashion, greatly reducing memory usage in cases where one needs to provide a structured OWL representation of some dynamic data.

To do so, the chosen writer must implement the CowlStreamWriter interface, and the ontology document must be serialized via the CowlOStream API. Similarly to input streams, you can retrieve a CowlOStream instance via CowlManager::cowl_manager_get_ostream().

struct CowlStreamWriter

Defines functions that must be implemented by stream writers.

Public Members

cowl_ret (*write_header)(UOStream *stream, CowlSymTable *st, CowlOntologyHeader header)

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

Param stream: Output stream.
Param st: Symbol table.
Param header: Ontology header.
Return: Return code.

cowl_ret (*write_axiom)(UOStream *stream, CowlSymTable *st, CowlAnyAxiom *axiom)

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

Param stream: Output stream.
Param st: Symbol table.
Param axiom: Axiom.
Return: Return code.

cowl_ret (*write_footer)(UOStream *stream, CowlSymTable *st)

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

Param stream: Output stream.
Param st: Symbol table.
Return: Return code.

struct CowlOStream : public CowlObject 

Ontology output stream.

A lightweight way to serialize knowledge without creating CowlOntology objects.