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.

See also

CowlReader

Public Functions

CowlManager *cowl_manager(void)

Returns a retained manager that uses the default reader and writer.

Note

You can specify the default reader and writer via cowl_set_reader() and cowl_set_writer().

Returns

Retained manager, or NULL on error.

void cowl_manager_set_reader(CowlManager *manager, CowlReader reader)

Sets the reader.

Parameters
  • manager – The manager.

  • reader – The reader.

void cowl_manager_set_writer(CowlManager *manager, CowlWriter writer)

Sets the writer.

Parameters
  • manager – The manager.

  • writer – The writer.

void cowl_manager_set_import_loader(CowlManager *manager, CowlImportLoader loader)

Sets the import loader.

Parameters
  • manager – The manager.

  • loader – The import loader.

void cowl_manager_set_error_handler(CowlManager *manager, CowlErrorHandler handler)

Sets the error handler.

Parameters
  • manager – The manager.

  • handler – The error handler.

CowlOntology *cowl_manager_get_ontology(CowlManager *manager, CowlOntologyId const *id)

Gets the ontology with the specified identifier.

If no existing ontology has the specified identifier, a new ontology is returned.

Note

The returned ontology is retained, so you are responsible for releasing it.

Parameters
  • manager – The manager.

  • id – The ontology identifier.

Returns

Ontology with the specified identifier.

CowlOntology *cowl_manager_read_path(CowlManager *manager, UString path)

Reads an ontology from the file at the specified path.

Note

The returned ontology is retained, so you are responsible for releasing it.

Parameters
  • manager – The manager.

  • path – The file path.

Returns

The read ontology, or NULL on error.

CowlOntology *cowl_manager_read_file(CowlManager *manager, FILE *file)

Reads an ontology from the specified file.

Note

The returned ontology is retained, so you are responsible for releasing it.

Parameters
  • manager – The manager.

  • file – The input file.

Returns

The read ontology, or NULL on error.

CowlOntology *cowl_manager_read_string(CowlManager *manager, UString const *string)

Reads an ontology from the specified string.

Note

The returned ontology is retained, so you are responsible for releasing it.

Parameters
  • manager – The manager.

  • string – The input string.

Returns

The read ontology, or NULL on error.

CowlOntology *cowl_manager_read_stream(CowlManager *manager, UIStream *stream)

Reads an ontology from the specified input stream.

Note

The stream is not released by the manager, you must do it yourself.

Note

The returned ontology is retained, so you are responsible for releasing it.

Parameters
  • manager – The manager.

  • stream – The input stream.

Returns

The read ontology, or NULL on error.

cowl_ret cowl_manager_write_path(CowlManager *manager, CowlOntology *ontology, UString path)

Writes the ontology to the file at the specified path.

Parameters
  • manager – The manager.

  • ontology – The ontology.

  • path – The file path.

Returns

Return code.

cowl_ret cowl_manager_write_file(CowlManager *manager, CowlOntology *ontology, FILE *file)

Writes the ontology to the specified file.

Parameters
  • manager – The manager.

  • ontology – The ontology.

  • file – The output file.

Returns

Return code.

cowl_ret cowl_manager_write_strbuf(CowlManager *manager, CowlOntology *ontology, UStrBuf *buf)

Writes the ontology to the specified string buffer.

Parameters
  • manager – The manager.

  • ontology – The ontology.

  • buf – The string buffer.

Returns

Return code.

cowl_ret cowl_manager_write_stream(CowlManager *manager, CowlOntology *ontology, UOStream *stream)

Writes the ontology to the specified output stream.

Note

The stream is not released by the manager, you must do it yourself.

Parameters
  • manager – The manager.

  • ontology – The ontology.

  • stream – The output stream.

Returns

Return code.

CowlIStream *cowl_manager_get_istream(CowlManager *manager, CowlIStreamHandlers handlers)

Returns an ontology input stream.

Note

You are responsible for releasing the returned object.

Parameters
  • manager – The manager.

  • handlers – The handlers.

Returns

Ontology input stream.

CowlIStream *cowl_manager_get_istream_to_ontology(CowlManager *manager, CowlOntology *ontology)

Returns an ontology input stream that stores constructs in the specified ontology.

Note

You are responsible for releasing the returned object.

Parameters
  • manager – The manager.

  • ontology – The ontology.

Returns

Ontology input stream.

CowlOStream *cowl_manager_get_ostream(CowlManager *manager, UOStream *stream)

Returns an ontology output stream.

Note

You are responsible for releasing the returned object.

Parameters
  • manager – The manager.

  • stream – The output stream.

Returns

Ontology output stream.

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.

See also

CowlReader

Public Functions

CowlManager *cowl_istream_get_manager(CowlIStream *stream)

Gets the manager of this ontology input stream.

Parameters

stream – The ontology input stream.

Returns

The manager.

CowlSymTable *cowl_istream_get_sym_table(CowlIStream *stream)

Gets the symbol table of this ontology input stream.

Parameters

stream – The ontology input stream.

Returns

The symbol table.

cowl_ret cowl_istream_handle_iri(CowlIStream *stream, CowlIRI *iri)

Handles the specified ontology IRI.

Parameters
  • stream – The ontology input stream.

  • iri – The ontology IRI.

Returns

Return code.

cowl_ret cowl_istream_handle_version(CowlIStream *stream, CowlIRI *version)

Handles the specified ontology version IRI.

Parameters
  • stream – The ontology input stream.

  • version – The version IRI.

Returns

Return code.

cowl_ret cowl_istream_handle_import(CowlIStream *stream, CowlIRI *import)

Handles the specified import IRI.

Parameters
  • stream – The ontology input stream.

  • import – The import IRI.

Returns

Return code.

cowl_ret cowl_istream_handle_annot(CowlIStream *stream, CowlAnnotation *annot)

Handles the specified ontology annotation.

Parameters
  • stream – The ontology input stream.

  • annot – The annotation.

Returns

Return code.

cowl_ret cowl_istream_handle_axiom(CowlIStream *stream, CowlAnyAxiom *axiom)

Handles the specified axiom.

Parameters
  • stream – The ontology input stream.

  • axiom – The axiom.

Returns

Return code.

cowl_ret cowl_istream_process_path(CowlIStream *stream, UString path)

Streams through the ontology at the specified path.

Parameters
  • stream – The ontology input stream.

  • path – The file path.

Returns

Return code.

cowl_ret cowl_istream_process_file(CowlIStream *stream, FILE *file)

Streams through the ontology read from the specified file.

Parameters
  • stream – The ontology input stream.

  • file – The file.

Returns

Return code.

cowl_ret cowl_istream_process_string(CowlIStream *stream, UString const *string)

Streams through the ontology read from the specified string.

Parameters
  • stream – The ontology input stream.

  • string – The string.

Returns

Return code.

cowl_ret cowl_istream_process_stream(CowlIStream *stream, UIStream *istream)

Streams through the ontology read from the specified input stream.

Parameters
  • stream – The ontology input stream.

  • istream – The input stream.

Returns

Return code.

cowl_ret cowl_istream_process_ontology(CowlIStream *stream, CowlOntology *ontology)

Streams through the specified ontology.

Parameters
  • stream – The ontology input stream.

  • ontology – The ontology.

Returns

Return code.

struct CowlIStreamHandlers

Ontology input stream handlers.

Public Members

void *ctx

Stream context, can be anything.

cowl_ret (*iri)(void *ctx, CowlIRI *iri)

Pointer to a function that handles the specified ontology IRI.

Param ctx

Stream context.

Param iri

The ontology IRI.

Return

Return code.

cowl_ret (*version)(void *ctx, CowlIRI *version)

Pointer to a function that handles the specified version IRI.

Param ctx

Stream context.

Param version

The version IRI.

Return

Return code.

cowl_ret (*import)(void *ctx, CowlIRI *import)

Pointer to a function that handles the specified import IRI.

Param ctx

Stream context.

Param import

The import IRI.

Return

Return code.

cowl_ret (*annot)(void *ctx, CowlAnnotation *annot)

Pointer to a function that handles the specified annotation.

Param ctx

Stream context.

Param annot

The annotation.

Return

Return code.

cowl_ret (*axiom)(void *ctx, CowlAnyAxiom *axiom)

Pointer to a function that handles the specified axiom.

Param ctx

Stream context.

Param axiom

The axiom.

Return

Return code.

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.

See also

CowlWriter

Public Functions

CowlManager *cowl_ostream_get_manager(CowlOStream *stream)

Gets the manager of this ontology output stream.

Parameters

stream – The ontology output stream.

Returns

The manager.

CowlSymTable *cowl_ostream_get_sym_table(CowlOStream *stream)

Gets the symbol table of this ontology output stream.

Parameters

stream – The ontology output stream.

Returns

The symbol table.

cowl_ret cowl_ostream_write_header(CowlOStream *stream, CowlOntologyHeader header)

Writes the ontology header.

Parameters
  • stream – The ontology output stream.

  • header – The ontology header.

Returns

Return code.

cowl_ret cowl_ostream_write_axiom(CowlOStream *stream, CowlAnyAxiom *axiom)

Writes an axiom.

Parameters
  • stream – The ontology output stream.

  • axiom – The axiom.

Returns

Return code.

cowl_ret cowl_ostream_write_footer(CowlOStream *stream)

Writes the ontology footer.

Parameters

stream – The ontology output stream.

Returns

Return code.

cowl_ret cowl_ostream_write_ontology(CowlOStream *stream, CowlOntology *ontology)

Writes the specified ontology to the stream.

Parameters
  • stream – The ontology output stream.

  • ontology – The ontology.

Returns

Return code.