wrenpp/README.md

# Wrenpp #

Wrenpp is a lightweight C++ wrapper for the official [Wren](http://wren.io/) C
library. It aims to package all the features accessible through the C API in a
modern C++ interface that is easy to use, while keeping the overhead to a
minimum.

* [Building](#building)
	* [Wrenpp](#wrenpp)
	* [Wren only](#wren-only)
* [Usage](#usage)
	* [Meson](#meson)
	* [C++](#c)
		* [Header files](#header-files)
		* [Initialisation](#initialisation)

## Building ##

### Wrenpp ###

You can make a release build like this:

```bash
mkdir build
cd build
meson setup -Dbuildtype=release ..
ninja
```

The build scripts understand the following options (double check in
`meson_options.txt`):

1. `build_testing` set to true to compile Wren's unit tests too
2. `build_examples` set to true to include examples from the `examples/`
   directory in the build
3. `wren_with_cli` set to false to exclude the command line tool from the Wren
   subproject build
4. `wren_with_rand` set to true to compile Wren with
   [random](http://wren.io/modules/random/) support
5. `wren_with_meta` set to true to compile Wren with
   [meta](http://wren.io/modules/meta/) support

Note that some example projects require random support in Wren, without which
they will crash. If you want to run examples or you are getting "Address
boundary error" segfaults recompile Wrenpp after enabling the example and/or
meta options:

```
mkdir build
cd build
meson setup -Dbuildtype=debug -Dbuild_examples=true -Dwren_with_rand=true -Dwren_with_meta=true ..
ninja
```

### Wren only ###

If you only want to compile the C library of Wren, of course you can do that:

```
mkdir build
cd build
meson setup -Dbuildtype=release -Dwren_with_rand=true -Dwren_with_meta=true ../subprojects/wren
ninja
```

This will build Wren as a shared object. If you want a static library instead
you can add the `-Ddefault_library=static` parameter to your Meson command, or
`-Ddefault_library=both` if you want tboth the shared and the static version of
Wren.

## Usage ##

### Meson ###

You can use Wrenpp as a Meson
[subproject](https://mesonbuild.com/Reference-manual.html#subproject) like you
would do normally. For example:

```
wrenpp = subproject('wrenpp', default_options: ['wren_with_rand=true'])
wrenpp_dep = wrenpp.get_variable('wrenpp_dep')

executable('my_project',
  'main.cpp',
  dependencies: wrenpp_dep,
)
```

This will make Wrenpp build as part of your project with Wren's optional random
module enabled.

Alternatively you can use the subproject as a fallback if there is no Wrenpp
installed in your system already:

```
wrenpp_dep = dependency('wrenpp', version: '>=0.1.0',
  fallback: ['wrenpp', 'wrenpp_dep'],
  default_options: ['wren_with_rand=true'],
)
```

Note that when you use Wrenpp as a subproject, Wrenpp's subproject Wren will
become a sub-subproject of your project. This is how Meson works and it simply
means that in your top level source directory you will have to run this command
before you will be able to compile (Meson should detect and print this as
well):

```
meson wrap promote subprojects/wrenpp/subprojects/wren
```

### C++ ###

For working examples refer to the source files in the `examples/` directory.

#### Header files ####

In order to use Wrenpp in your project you will need to include `wrenpp/vm.hpp`
at least. A description of all the relevant header files follows:

* `vm.hpp` The `VM` class provides simple wrappers around the C API functions.
  It wraps and hides the `WrenVM` pointer and provides RAII around it.
  Available methods aim to be as close to their C counterparts as possible. You
  can use objects of this class in a way that mirrors very closely the way you
  would use the C API.
* `vm_fun.hpp` This header provides functions on top of the `VM` class. Their
  goal is to make common operations easier and more compact in your code.
* `def_configuration.hpp` The `DefConfiguration` struct extends the bare
  `Configuration` struct by providing an implementation for `write_fn`,
  `error_fn` and `reallocate_fn`. They are implemented in terms of `std::cout`,
  `std::cerr` and `new[]`/`delete[]` respectively. You can safely ignore this
  header if this is not suitable for your project.

Other header files are intended for Wrenpp's use and you shouldn't need to use
them. You are free to use them in your project if you think the code inside is
useful to you, however keep in mind that those are not providing core Wrenpp
functionalities and may be removed or modified in the future.


#### Initialisation ####

Wrenpp aims to make your code as clear and concise as possible. To instantiate
a `VM` (which wraps `WrenVM`) and run a simple script you can do the following:

```
#include <wrenpp/vm.hpp>
#include <wrenpp/def_configuration.hpp>

int main() {
	wren::DefConfiguration config;
	wren::VM vm(&config, nullptr);

	vm.interpret("main", "System.print(\"Hello world!\")");
	return 0;
}
```

*Work in progress*