Writing ontologies

Writer objects

Similarly to reading, Cowl can write ontologies to files, buffers or custom output streams (see UOStream). You can either use CowlOntology functions such as cowl_ontology_to_path() and cowl_ontology_to_stream(), which leverage the default writer to serialize the ontology, or instantiate and use a specific CowlWriter.

Writers can be configured and 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: the default writer can be changed by calling cowl_set_writer(). You can also decide to use a specific writer by instantiating a CowlWriter object.

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

struct CowlWriter

A writer is an object that can write ontologies to an output stream.

Pseudo-extends: CowlObject

CowlWriter *cowl_writer_functional(void)

Returns the functional syntax writer.

Note

You must release the returned object via cowl_release().

Returns:

Functional syntax writer, or NULL on error.

CowlWriter *cowl_writer_protocowl(void)

Returns the ProtocOWL writer.

Note

You must release the returned object via cowl_release().

Returns:

ProtocOWL writer.

void cowl_writer_protocowl_set_index_size(CowlWriter *writer, ulib_uint index_size)

Sets the index size for the specified ProtocOWL writer.

Note

This function should only be called on ProtocOWL writers.

Parameters:

  • writer – The writer.

  • index_size – The index size.

void cowl_writer_protocowl_set_encode_anon(CowlWriter *writer, bool encode_anon)

Sets whether to encode anonymous individuals.

Note

This function should only be called on ProtocOWL writers.

Parameters:

  • writer – The writer.

  • encode_anon – True to encode anonymous individuals, false otherwise.

cowl_ret cowl_writer_protocowl_write_add_frame(CowlWriter *writer, UOStream *stream)

Writes an “add” control frame to the specified output stream.

Note

This function should only be called on ProtocOWL writers.

Parameters:

  • writer – The writer.

  • stream – Output stream.

Returns:

Return code.

cowl_ret cowl_writer_protocowl_write_remove_frame(CowlWriter *writer, UOStream *stream)

Writes a “remove” control frame to the specified output stream.

Note

This function should only be called on ProtocOWL writers.

Parameters:

  • writer – The writer.

  • stream – Output stream.

Returns:

Return code.

cowl_ret cowl_writer_protocowl_write_reset_frame(CowlWriter *writer, UOStream *stream, bool reset_prefixes)

Writes a “reset” control frame to the specified output stream.

Note

This function should only be called on ProtocOWL writers.

Note

Identifiers are always reset when this function is called.

Parameters:

  • writer – The writer.

  • stream – Output stream.

  • reset_prefixes – True to reset prefixes, false otherwise.

Returns:

Return code.

CowlWriter *cowl_writer_default(void)

Returns the default writer.

Note

You must release the returned object via cowl_release().

Returns:

Default writer, or NULL on error.

CowlWriter *cowl_writer(CowlWriterImpl impl)

Returns a new writer.

Note

You must release the returned object via cowl_release().

Parameters:

  • impl – Writer implementation.

Returns:

Writer, or NULL on error.

char const *cowl_writer_get_name(CowlWriter *writer)

Returns the name of the writer.

Parameters:

  • writer – The writer.

Returns:

Name of the writer.

CowlWriterImpl *cowl_writer_get_impl(CowlWriter *writer)

Returns the implementation of the writer.

Parameters:

  • writer – The writer.

Returns:

Writer implementation.

bool cowl_writer_can_write_stream(CowlWriter *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 *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 *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_writer_write_ontology(CowlWriter *writer, UOStream *stream, CowlOntology *onto)

Writes an ontology to the specified output stream.

Parameters:

  • writer – The writer.

  • stream – Output stream.

  • onto – Ontology.

Returns:

Return code.

cowl_ret cowl_writer_write_ontology_to_path(CowlWriter *writer, UString path, CowlOntology *onto)

Writes an ontology to the specified file path.

Parameters:

  • writer – The writer.

  • path – File path.

  • onto – Ontology.

Returns:

Return code.

cowl_ret cowl_writer_write_header(CowlWriter *writer, UOStream *stream, CowlOntologyHeader header)

Writes an ontology header to the specified output stream.

Parameters:

  • writer – The writer.

  • stream – Output stream.

  • header – Ontology header.

Returns:

Return code.

cowl_ret cowl_writer_write_axiom(CowlWriter *writer, UOStream *stream, CowlAnyAxiom *axiom)

Writes an axiom to the specified output stream.

Parameters:

  • writer – The writer.

  • stream – Output stream.

  • axiom – Axiom.

Returns:

Return code.

Writes the ontology footer to the specified output stream.

Parameters:

  • writer – The writer.

  • stream – Output stream.

Returns:

Return code.

cowl_ret cowl_writer_write(CowlWriter *writer, UOStream *stream, CowlAny *object)

Writes an object to the specified output stream.

Parameters:

  • writer – The writer.

  • stream – Output stream.

  • object – Object to write.

Returns:

Return code.

cowl_ret cowl_write(UOStream *stream, CowlAny *object)

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

Note

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

Parameters:

  • stream – Output stream.

  • object – Object.

Returns:

Return code.

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

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

ulib_ret cowl_write_iri(UOStream *stream, CowlIRI *iri)

Writes an IRI to the specified output stream.

Note

The IRI is written as the concatenation of the namespace and the remainder, without any additional markup (e.g. angle brackets).

Parameters:

  • stream – Output stream.

  • iri – IRI.

Returns:

Return code.

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

ulib_ret cowl_write_error(UOStream *stream, CowlError const *error)

Writes an error to the specified output stream.

Parameters:

  • stream – Output stream.

  • error – Error information.

Returns:

Return code.

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

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

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

ulib_ret cowl_write_literal(UOStream *stream, char const string[])

Writes a string literal to the specified output stream.

Parameters:

  • stream – Output stream.

  • string – String literal.

Returns:

Return code.

ulib_ret cowl_write_static(UOStream *stream, char const string[])

Writes a string literal to the specified output stream.

Deprecated:

Use cowl_write_literal instead.

Parameters:

  • stream – Output stream.

  • string – String literal.

Returns:

Return code.

COWL_PROTOCOWL_INDEX_SIZE_UNBOUNDED

Unbounded index size for ProtocOWL writers.

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 support stream serialization by implementing the write_header, write_axiom, and write_footer` functions. To serialize an ontology document using this technique, you must first call cowl_writer_write_header() to write the header, then call cowl_writer_write_axiom() for each axiom to be serialized, and finally call cowl_writer_write_footer().

struct CowlOntologyHeader

Ontology header.

Public Members

CowlPrefixMap *pm

Prefix map.

CowlIRI *iri

Ontology IRI.

CowlIRI *version

Ontology version.

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.