lib | ||
tests | ||
.travis.yml | ||
AUTHORS | ||
autogen.sh | ||
build.sh | ||
ChangeLog | ||
configure.ac | ||
COPYING | ||
COPYING.LESSER | ||
LICENSE.tinyexpr | ||
Makefile.am | ||
NEWS | ||
README | ||
README.md | ||
TODO.org |
Warning: The API is not yet stable
libdice
libdice
is a small C library for rolling P&P style dice and for
evaluating dice expressions.
Features
- Written in ANSI C99
- Uses solid and reliable RNG, no need for seeding
- Mathematic expression library for advanced dice rolling
Dice syntax
Currently the supported syntax in libdice
is rather limited. It only
supports variable amount and variable sides at the moment:
- Roll four six sided dices:
4d6
- Roll one twenty sided die:
d20
Build
libdice
requires:
- libbsd
- bison
- flex
- cmocka >= 1.0.1
To build libdice
run:
$ ./configure --prefix="/usr"
$ make
$ sudo make install
Dice API
The core api relies on dice_new
which creates a new dice (or a set of dice),
which is then freed by dice_free
. Dice can be initialised through the proper
dice_set
function, or by using either dice_simple
or dice_parse
:
#include <dice.h>
dice_t d = dice_new();
dice_set(d, DICEOPTION_AMOUNT, 4);
dice_set(d, DICEOPTION_SIDES, 6);
/* or simpler:
* d = dice_simple(4, 6);
*/
printf("%ld\n", dice_roll(d));
dice_free(d);
There is also an easier API:
dice_t d20 = dice_simple(1, 20);
printf("%ld\n", dice_roll(d20));
dice_free(d20);
And a more advanced API:
dice_t d = dice_simple(4, 6);
dice_result_t *res = NULL;
size_t reslen = 0, i = 0;
if (!dice_evaluate(d, &res, &reslen)) {
goto fail;
}
for (; i < reslen; i++) {
printf("%ld\n", res[i].result);
}
fail:
dice_result_freev(res, reslen);
dice_free(d);
You can also parse dice strings:
dice_t d20 = dice_new();
if (!dice_parse(d20, "5d20")) {
char const *err = NULL;
dice_get(d20, DICEOPTION_ERROR, &err);
fprintf(stderr, "error: %s\n", err);
}
printf("%ld\n", dice_roll(d20));
dice_free(d20);
Expression API
The expression API supports multiple die within one mathematical expression. Expressions are parsed using tinyexpr library.
int error = 0;
char const *expr = "1d20+8+4+3-1";
dice_expression_t e = dice_expression_parse(expr, &err);
int64_t result = 0;
if (e == NULL) {
fprintf(stderr, "error in expression: \"%s\": at %d\n", expr, err);
goto fail;
}
if (!dice_expression_evaluate(e, &result)) {
goto fail;
}
printf("%ld\n", result);
fail:
dice_expression_free(e);
Copyright
libdice
is dual licenced. The tinyexpr
is licenced under the zlib
licence (see COPYING.tinyexpr), and the rest of libdice
is available under
the LGPLv3.