@c This file is a part of the CaosDB Project.
@c
@c Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
@c Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
@c
@c This program is free software: you can redistribute it and/or modify
@c it under the terms of the GNU Affero General Public License as
@c published by the Free Software Foundation, either version 3 of the
@c License, or (at your option) any later version.
@c
@c This program is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU Affero General Public License for more details.
@c
@c You should have received a copy of the GNU Affero General Public License
@c along with this program. If not, see <https://www.gnu.org/licenses/>.

@node Top
@top CaosDB library for Octave/Matlab

This package contains utility functions to interact with CaosDB, the flexible semantic data
management platform.

It makes use of @url{https://gitlab.com/caosdb/caosdb-cpplib, libcaosdb} which must be installed on
the system.

Full documentation how to install this package and a short tutorial for first steps with the Octave
CaosDB library can be found on @url{https://docs.indiscale.com/caosdb-octavelib}, the source code
for this library is freely available at @url{https://gitlab.com/caosdb/caosdb-octavelib}.

If you are interested in the documentation of the functions and classes provided by this library,
follow this link to the @url{../overview.html, API overview}.

@menu
* Overview::  How CaosDB works in Octave, and first steps.
* CaosDB::    The CaosDB class.  This class handles connections to CaosDB servers and transactions.
* Index::     Complete index.
@end menu

@node Overview

@chapter Overview
@cindex Installation
@section Installation

@cindex Requirements for installation
Before installing the @code{caosdb} library in Octave, you first need to install @i{libcaosdb} with
Conan.  Typically, it should be sufficient to download the sources from
@url{https://gitlab.com/caosdb/caosdb-cpplib} and execute @code{make conan}.

@cindex Installation, with @code{pkg install}
@unnumberedsubsec With @code{pkg install}
Then get the Octave package for the @code{caosdb} library or its source code and install it from
within Octave with @code{pkg install caosdb.tar.gz;} (if you downloaded the package) or @code{pkg
install /path/to/source/dir;}.  To make the library contents available to your code, activate it
with @code{pkg load caosdb;}

@cindex Installation, manual
@unnumberedsubsec Manual installation
For other environments which lack a package management system, such as Matlab, you can go into the
@code{src/} directory and call @command{./configure} there, followed by @command{make install}.  You
will then have to copy the resulting files to a place which is in your search path so that the
@file{.m} and @file{.mex} files can be found.  Once the files are in your search path, they are
immediately available to your code.

@cindex Configuration (libcaosdb)
@unnumberedsubsec Configuration
Since the Octave CaosDB library uses @i{libcaosdb}, the configuration is handled by libcaosdb as
well.  In practice this means that there should be a configuration file, either in the current
directory, your home directory or at a location specified by the @env{CAOSDB_CLIENT_CONFIGURATION}
environment variable.  More information about the configuration is available at the
@url{https://docs.indiscale.com/caosdb-cpplib, libcaosdb documentation}.

@cindex First steps
@section First steps

Starting off with CaosDB in Octave is easy:

@example
%% Set up the library
pkg load caosdb;   % Not necessary if you manually put the CaosDB files into your search path.
c = Caosdb();      % Uses the default connection as defined in the configuration.
c.info()           % Output some diagnostic message.

%% Execute a simple query
my_query = 'FIND Record MusicalInstrument WITH price > 2000';
results = c.query(my_query);
disp(['Found ' num2str(numel(results)) ' results']);
if numel(results) > 0
  disp(results@{1@});
end
@end example

You can create and modify CaosDB entities much in the same way as with libcaosdb, so please refer to
the documentation available there for details.  These operations, and also inserting, updating and
deleting entities are straight-forward in Octave:

@example
%% Continuing from the code above...
my_instrument = Entity();       % Create new entity, set role and name
my_instrument.role = 'RECORD';
my_instrument.name = 'My new theremin';

% set parent
instrument_id = c.query('FIND RecordType MusicalInstrument')@{1@}.id;
instrument = Parent();
instrument.id = instrument_id;

my_instrument.set_parents(@{instrument@});

% set property
price_id = c.query('FIND Property price')@{1@}.id;
price = Property();
price.id = price_id;
price.set_datatype('DOUBLE');   % Datatype must be set in order to set a value.
price.value = 2300;             % Integer values would need to be cast to int64.

my_instrument.set_properties(@{price@});

%% Insert the instrument Record.
insert_result = c.insert(@{my_instrument@});

disp(insert_result@{1@}.id);

@end example


@section Further reading

For more information, you may want to read up on
@itemize
@item The @code{Caosdb} class, which holds connection information and handles the transactions.
@item The @code{Entity} class, a representation of CaosDB entities (Records, ReocrdTypes, Properties).
@item The subordinate classes @code{Property} and @code{Parent}, used for adding information to
      Entities.
@end itemize

@node CaosDB
@comment  node-name,  next,  previous,  up
@cindex CaosDB (class)
@chapter The CaosDB class

The CaosDB class holds information about the connection to a CaosDB server.  It provides a
convenient interface to the possible transactions (insert, query, retrieve, update, delete) with the
server.

@enumerate
@item
This is the first item.
@item
This is the second item.
@end enumerate


@deftypefn {Class} {} Caosdb ()
This is the main class of the CaosDB client for Octave.

Print usage help and return:
@example
caosdb --help;
@end example

Print the version and return:
@example
caosdb --version;
@end example

Test the default connection, print the server's version and return.
@example
caosdb --test-connection;
@end example

@end deftypefn


@node Index
@unnumbered Index
@printindex cp