Writing ontologies

Writers

Similarly to reading, Cowl can write ontologies to files, buffers or custom output streams (see UOStream) through the CowlManager object. 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 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 *onto)

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

Note

Should only be implemented by writers that either require the ontology object as a whole, or that can more efficiently encode the ontology if they have access to it. In all other cases, it is best left unimplemented.

Param stream:

Output stream.

Param onto:

Ontology.

Return:

Return code.

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

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

Note

Should only be implemented by writers used as default writers (i.e. passed to cowl_set_writer() ), so that they are able to write the string representation of arbitrary objects.

Param stream:

Output stream.

Param object:

Object to write.

Return:

Return code.

CowlStreamWriter stream

Contains the streaming implementation of this writer.

Note

This is the preferred implementation for writers.

CowlWriter cowl_writer_functional(void)

Returns the functional syntax writer.

Returns:

Functional syntax writer.

bool cowl_writer_can_write_stream(CowlWriter const *writer)

Checks whether the writer supports stream writing.

Parameters:

• writer – The writer.

Returns:

True if the writer supports stream writing, false otherwise.

bool cowl_writer_can_write_object(CowlWriter const *writer)

Checks whether the writer supports writing arbitrary objects.

Parameters:

• writer – The writer.

Returns:

True if the writer supports writing objects, false otherwise.

bool cowl_writer_can_write_ontology(CowlWriter const *writer)

Checks whether the writer has a specialized method to write ontologies.

Parameters:

• writer – The writer.

Returns:

True if the writer has a specialized method to write ontologies, false otherwise.

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.

ustream_ret cowl_write_ustring(UOStream *stream, UString const *string)

Writes a string to the specified output stream.

Parameters:

• stream – Output stream.

• string – String.

Returns:

Return code.

ustream_ret cowl_write_cstring(UOStream *stream, char const *string)

Writes a string to the specified output stream.

Parameters:

• stream – Output stream.

• string – String.

Returns:

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 literal.

Returns:

ustream_ret Return code.

Writing ontologies as axiom streams

All standard OWL serialization formats allow ontologies to be serialized in such a way that the resulting byte sequence consist of a header, a sequence of axioms, and a closing footer. Ontology documents can therefore be serialized in a streaming fashion, without first building an intermediate data store such as CowlOntology. This greatly reduces memory usage in cases where one needs to provide the 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 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 CowlOntologyHeader

Models an ontology header.

Public Members

CowlOntologyId id

Ontology identifier.

UVec_CowlObjectPtr const *imports

Import IRIs.

UVec_CowlObjectPtr const *annotations

Annotations.

CowlOntologyHeader cowl_ontology_header_empty(void)

Returns an empty ontology header.

Returns:

Empty ontology header.

struct CowlOStream

Ontology output stream.

A lightweight way to serialize knowledge without creating CowlOntology objects.

Pseudo-extends: CowlObject

See also

CowlWriter

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 *onto)

Writes the specified ontology to the stream.

Parameters:

• stream – The ontology output stream.

• onto – The ontology.

Returns:

Return code.