README 3.37 KB
Newer Older
1 2
datadac-1.3, June 2018

3
Datadec takes inductive (or recursive) data types modelled on those found in
4 5
functional languages (Hope, Miranda, Haskell etc) and generates ISO/ANSI C
code to implement them.
dcw's avatar
dcw committed
6

7
			Duncan C. White, d.white@imperial.ac.uk
dcw's avatar
dcw committed
8 9
			19th March 2002

10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
New May 2014!  v1.2

- experimental free functions for every inductive data type
 (run datadec with new -f option)

New June 2018! v1.3
- converted to use stdbool.h at last, inside and out

- added new mode (-m) and new code to emit on stdout a list of all the
  metadata, i.e. for each shape of each type, typename, shapename, and
  the shape parameter types.  This will be useful for add-on tools such
  as the experimental "CPM.perl" script, which tackles client side use
  of datadec-generated types, translating C+Pattern Matches to C.

- added assert( p != NULL ) in every constructor after the NEW( T ) call.

- fixed longstanding bug whereby the top of the global section was
  copied AFTER the <<#include "thismodule.h">> whereas if it were copied
  above it could #include other stuff.  but of course now it can't use
  the defined types from "thismodule.h".

- changed the arg processing to use getopt.

- added a new "suppress function F" multi-flag, and stored the results in
  a "list (could even be a set) of strings of named functions to suppress,
  ie. perhaps because an alternative manually tweaked verson is included in
  the GLOBAL section."  Did this by importing strlist module from libADTs.
37

dcw's avatar
dcw committed
38
An Example of Datadec in Action
dcw's avatar
dcw committed
39
-------------------------------
dcw's avatar
dcw committed
40

dcw's avatar
dcw committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
To give you a feel for what datadec can do, you could write:

intlist = nil
        | cons( int first, intlist next )
        ;

illist  = nil
        | cons( intlist first, illist next )
        ;

idtree  = leaf( string id, illist l )
        | node( idtree left, idtree right )
        ;

What does this mean?  
The first rule declares that an intlist can take two basic "shapes" -
57 58
it is either empty, aka nil, or of the form cons(int,intlist).
nil() and cons() are called constructors, and define different
dcw's avatar
dcw committed
59 60
"shapes" that objects of the type can take.
However, because the second argument of a cons() constructor is itself
61
an intlist, this type is said to be recursively or inductively defined.
62

dcw's avatar
dcw committed
63 64 65 66 67 68 69 70
Functional programmers will recognise nil or cons() as the standard
way of defining a list, so more intuitively, intlist is simply
a list of integers!

Reading on, an illist is declared as a list of intlists,
and an idtree is declared as a binary tree where each leaf node
contains a (string, illist) pair.

71
Given this input, datadec can automatically construct an ISO C
dcw's avatar
dcw committed
72 73 74 75
module which implements all the data types, a constructor function for
each constructor, deconstructor functions to help you to take objects
apart again and printing functions to help you with debugging.

76 77
(Plus, new May 2014: a tree-walking free function for every type if you
invoke datadec with the new -f option).
78

dcw's avatar
dcw committed
79 80 81 82
Building and Packaging datadec
------------------------------

See the INSTALL file for building and packaging instructions.
dcw's avatar
dcw committed
83 84 85 86 87 88 89 90 91 92

Testing
-------

Having built datadec in the source directory, you can also compile and
run a test harness in the test directory.  test/cdata.in is the datadec
input file which declares some recursive data types (lists and trees),
and ctest.c is the test harness that uses them.  cd into test and run make
to turn cdata.in into cx.h and cx.c, and to compile cx.c and ctest.c and
link them..