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
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()
andcowl_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.
-
CowlManager *cowl_manager(void)
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 throughcowl_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 viaCowlManager::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.
-
char const *name
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.
-
void *ctx
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
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.
-
CowlManager *cowl_istream_get_manager(CowlIStream *stream)
-
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.
-
void *ctx
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.
-
CowlTable *cowl_sym_table_get_prefix_ns_map(CowlSymTable *st, bool reverse)
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 throughcowl_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 viaCowlManager::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.
-
char const *name
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.
Pointer to a function that writes the ontology footer to an output stream.
- Param stream
Output stream.
- Param st
Symbol table.
- Return
Return code.
-
cowl_ret (*write_header)(UOStream *stream, CowlSymTable *st, CowlOntologyHeader header)
-
struct CowlOStream : public CowlObject
Ontology output stream.
A lightweight way to serialize knowledge without creating CowlOntology objects.
See also
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.
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.
-
CowlManager *cowl_ostream_get_manager(CowlOStream *stream)