libirmin
provides C bindings to the Irmin API.
To install from the root of this repo:
$ opam pin add libirmin .
After installing, libirmin.so
can be found in $OPAM_SWITCH_PREFIX/libirmin/lib
,
and irmin.h
will be in $OPAM_SWITCH_PREFIX/libirmin/include
.
This means when compiling programs that use libirmin
you will need to include those
directories:
$ export IRMIN_CFLAGS=-I$OPAM_SWITCH_PREFIX/libirmin/include
$ export IRMIN_LDFLAGS=-L$OPAM_SWITCH_PREFIX/libirmin/lib -lirmin
$ cc $IRMIN_CFLAGS my-program.c -o my-program $IRMIN_LDFLAGS
The first thing you will need to do is configure a backend:
Using irmin-git
:
IrminConfig *config = irmin_config_git("string");
if (config == NULL){
// Print error message
IrminString *err = irmin_error_msg();
fputs(irmin_string_data(err), stderr);
irmin_string_free(err);
}
When using irmin-mem
, irmin-fs
, or irmin-pack
, you can specify the hash type
in addition to the content type:
IrminConfig *config = irmin_config_mem("sha256", "string");
Available backends: irmin_config_mem
, irmin_config_git
, irmin_config_git_mem
, irmin_config_fs
,
irmin_config_pack
, irmin_config_tezos
If NULL
is passed for the content parameter, then string
will be used by default; and
when NULL
is passed for the hash argument, blake2b
is used.
Available content types: string
, json
(JSON objects), json-value
(any JSON value)
Available hash types: blake2b
, blake2s
, rmd160
, sha1
, sha224
, sha256
, sha384
,
sha512
, tezos
The IrminConfig*
value should eventually be freed using irmin_config_free
.
When using a backend that stores information on disk, you will probably want to set the root
parameter:
assert(irmin_config_set_root(config, "path/to/store"));
Next you can initialise the repo:
IrminRepo *repo = irmin_repo_new(config);
if (repo == NULL){
// handle error
}
From there you can create a store using the main branch:
Irmin *store = irmin_main(repo);
Or from your branch of choice:
Irmin *store = irmin_of_branch(repo, "my-branch");
Every IrminX
type should be released using the matching irmin_X_free
function:
irmin_free(store);
irmin_repo_free(repo);
irmin_config_free(config);
Setting a value when using string contents:
IrminString *value = irmin_string_new("Hello, world!", -1);
IrminPath *path = irmin_path_of_string(repo, "a/b/c");
IrminInfo *info = irmin_info_new(repo, "author", "commit message");
assert(irmin_set(store, path, (IrminContents*)value, info));
irmin_info_free(info);
irmin_path_free(path);
irmin_string_free(value);
The -1
argument to irmin_string_new
is used to pass the length of
the string. If it ends with a NULL
byte, then passing -1
will automatically
detect the string length. This also shows that IrminString
can be cast to IrminContents
safely when using string
contents.
When using json
contents:
IrminType *t = irmin_type_json();
IrminContents *value = irmin_contents_of_string(t, "{\"foo\": \"bar\"}", -1);
IrminPath *path = irmin_path_of_string(repo, "a/b/c");
IrminInfo *info = irmin_info_new(repo, "author", "commit message");
assert(irmin_set(store, path, value, info));
irmin_info_free(info);
irmin_path_free(path);
irmin_contents_free(value);
irmin_type_free(t);
The following will get the value associated with a path and print its string representation to stdout:
IrminPath *path = irmin_path_of_string(repo, "a/b/c");
IrminContents *value = irmin_find(store, path);
if (value != NULL){
// value exists, print it to stdout
IrminString *s = irmin_contents_to_string(repo, value);
puts(irmin_string_data(s));
irmin_string_free(s);
irmin_contents_free(value);
}
irmin_path_free(path);
Working with trees is similar to working with stores, only you will be using the
irmin_tree_X
functions:
IrminTree *tree = irmin_tree_new(repo);
IrminString *value = irmin_string_new("Hello, world!", -1);
IrminPath *path = irmin_path_of_string(repo, "a/b/c");
assert(irmin_tree_add(tree, path, value, NULL); // The NULL parameter here is for
// metadata and will typically be
// NULL
IrminPath *empty_path = irmin_path_empty();
IrminInfo *info = irmin_info_new(repo, "author", "commit message");
irmin_set_tree(store, empty_path, tree, info);
irmin_string_free(value);
irmin_path_free(path);
irmin_path_free(empty_path);
irmin_info_free(info);
irmin_tree_free(tree);