Module eqc_c_enum

Description
Function Index
Function Details

This module provides a tool for generating conversion functions for enum-like C types.

Version: 1.42.1

Description

This module provides a tool for generating conversion functions for enum-like C types.

Example use: given the C header file answer.h:

 typedef int Answer;
 #define YES 1
 #define NO  0

we can define

 -module(enum_test).
 -compile(export_all).
 start() ->
   eqc_c_enum:load(answer_enum, ["answer.h"], {"Answer", ['YES', 'NO']}),
   eqc_c:start(answer, [{c_src, "answer.h"}, {casts, answer_enum}]).

We can then work with YES and NO as values of type Answer:

 1> enum_test:start().
 ok
 2> Ans = eqc_c:alloc("Answer", 'YES').
 {ptr, "Answer", 140243361595616}
 3> eqc_c:deref(Ans).
 'YES'

You can also generate conversion functions for bitmask types, by giving the bitmask option to eqc_c_enum:load/2. In this case C values are converted to and from lists of atoms. For example, given bitmasks.h:

 typedef int XYZ;

 #define HAS_X 1
 #define HAS_Y 2
 #define HAS_Z 4

we can load it as follows

 1> eqc_c_enum:load(xyz, ["bitmasks.h"], {"XYZ", ['HAS_X', 'HAS_Y', 'HAS_Z'], bitmask}).
 ok
 2> eqc_c:start(bitmasks, [{c_src, "bitmasks.h"}, {casts, xyz}]).
 ok
 3> eqc_c:alloc("XYZ", 5).
 {ptr, "XYZ", 140567464902656}
 4> eqc_c:deref(v(-1)).
 ['HAS_X', 'HAS_Z']

Function Index

load/3	Equivalent to `load(Module, Includes, TypeSpecs, [])`.
load/4	Generate and load a module `Module` suitable for use as a `casts` module with `eqc_c:start/2`.
load_module/2	Equivalent to `load_module(Module, Callback, [])`.
load_module/3	Given a callback module a type_cast module is generated.

Function Details

load/3

load(Module::atom(), Includes::[string()], TypeSpecs) -> ok

TypeSpecs = TypeSpec | [TypeSpec]
TypeSpec = {eqc_c:type(), [atom() | {atom(), any()}]} | {eqc_c:type(), [atom() | {atom(), any()}], TypeOptions}
TypeOptions = TypeOption | [TypeOption]
TypeOption = read_only | write_only | bitmask

Equivalent to load(Module, Includes, TypeSpecs, []).

load/4

load(Module::atom(), Includes::[string()], TypeSpecs, Options::proplists:proplist()) -> ok

TypeSpecs = TypeSpec | [TypeSpec]
TypeSpec = {eqc_c:type(), [atom() | {atom(), any()}]} | {eqc_c:type(), [atom() | {atom(), any()}], TypeOptions}
TypeOptions = TypeOption | [TypeOption]
TypeOption = read_only | write_only | read_write

Generate and load a module Module suitable for use as a casts module with eqc_c:start/2. Each TypeSpec in TypeSpecs is a tuple, {Type, Tags}. The function creates the functions to_c/2 and from_c/2 converting between C integers and the atoms given in Tags. For each tag there should be a #define in the include files Includes providing its value. If Tags is a list of pairs, the first component of each pair specifies the name of the #define and the second component the desired Erlang value.

The type options can be used to restrict the conversion to be oneway. With the read_only option no conversion will take place from Erlang to C, and with write_only there is no conversion from C to Erlang. The write_only option is useful when there is no typedef on the C side indicating when conversion to Erlang should take place.

If the bitmask option is used, conversion from C produces a list of all the atoms whose corresponding bits are set in the value. Conversion from Erlang takes a list of atoms to the bitwise or of the corresponding values.

The Options are passed to eqc_c:start/2 when starting the C program to retrieve the tag values.

load_module/2

load_module(Module::atom(), Callback::atom()) -> ok

Equivalent to load_module(Module, Callback, []).

load_module/3

load_module(Module::atom(), Callback::atom(), Options::proplists:proplist()) -> ok

Given a callback module a type_cast module is generated. A callback module contains one obligatory function includes/0, which should return all C header files with #define's in it that one wants to represent symbolically in Erlang tests.

All other 0-ary functions in the callback module are considered type definitions for the symbols. For example, a function

         'ReturnType'() -> [ 'OK', 'NOT_OK' ].

Defines a type with two values which are defined in one of the specified header files. This allows the user to use 'OK' and 'NOT_OK' in the Erlang test specifications, instead of hard-coding their actual values. Type options can be supplied by returning a pair from the function:

         'XYZ'() -> {['HAS_X', 'HAS_Y', 'HAS_Z'], bitmask}.

The provided Module is used by eqc_c as type cast module and should be added in the compiler options to eqc_c:start/2 as {casts, Module}.

Generated by EDoc, Sep 18 2017, 16:17:37.