README.md

# PropCheck.Derive
[![Hex](https://img.shields.io/hexpm/v/propcheck_derive.svg)](https://hex.pm/packages/propcheck_derive)
[![Build Status](https://travis-ci.org/evnu/propcheck_derive.svg?branch=master)](https://travis-ci.org/evnu/propcheck_derive)
![License](https://img.shields.io/hexpm/l/propcheck_derive.svg)

Generating simple PropCheck generators from type definitions.

## Usage

In order to derive a PropCheck generator with `PropCheck.Derive`, add a `use` statement to
the module for which you want to derive the generators, or use an explicit `module` argument
to define the module for which generators are to be generated. `PropCheck.Derive` will then
attempt to create a generator for each `@type`. There are some requirements which must be fulfilled
in order to do that:

1. Cyclic types are not allowed. `PropCheck.Derive` should detect those and raise an error.
1. Some types are not supported. For example, `pid()` cannot be created. Other
   types such as `maybe_improper_list` are not yet implemented, as their
   semantics are not clear.

### Usage within a module

```iex
iex> use PropCheck
iex> Application.ensure_all_started(:propcheck_derive)
iex> defmodule Hello do
...> use PropCheck.Derive
...> @type my_type :: integer()
...> end
iex> {:ok, my_type} = produce(Hello.Generate.my_type())
iex> is_integer(my_type)
true
```

### Usage outside of a module

```iex
iex> use PropCheck
iex> Application.ensure_all_started(:propcheck_derive)
iex> use PropCheck.Derive, module: String
iex> {:ok, string} = produce(String.Generate.t())
iex> is_binary(string)
true
```

## License

`PropCheck.Derive` is licensed under GPL 3 [as is PropCheck](https://github.com/alfert/propcheck#license).

## Quality of the generators

Please note that hand-written generators are likely to be better suited for non-trivial types.
`PropCheck.Derive` makes use of `oneof/1` and other simple union generators, but it does not
use `frequency/1` or similar generators to make some cases more likely then others.

## TODOs

* [ ] The semantics for `maybe_improper_list` is unclear. Can we add generators for that type?
* [ ] Opaque types are not handled. Should we create a generator for them?