Commit 2c624798 authored by Duncan White's avatar Duncan White
Browse files

added free_type() documentation..

parent b63f05e8
......@@ -3,14 +3,14 @@
datadec \- ANSI C data declaration module constructor
.RB [\- vno ]
.RB [\- vfno ]
.I basename
.RB [infile]
.B Datadec
takes an input file - or stdin if no input file is given -
containing a series of HOPE/Miranda style recursive data declarations
with optional hints on printing,
containing a series of Haskell style recursive (or inductive) datatype
declarations - with optional hints on printing and freeing,
and builds an definition/implementation pair of ANSI C files \-
.I "basename.h"
......@@ -30,6 +30,10 @@ enter verbose mode.
now displays the data types that it parses, along with various almost
certainly useless bits of information about optimization.
.B "\-f"
Enable experimental generation of free_TYPE() functions.
See the later section on free functions.
.B "\-n"
do not perform various optimizations.
......@@ -129,7 +133,7 @@ shape = constructor_name [ '(' params ') ] [ print ]
params = param list( ',' param)
param = type_name param_name
param = ['-'] type_name param_name
print = list(element)
......@@ -139,7 +143,7 @@ element = number | string_literal
Note that each data type is terminated by a semicolon,
and that (within one data type) each shape is separated from the next by 'or'
(just like the '|' in Miranda).
(just like the '|' in Haskell).
If a particular shape has parameters, they are separated from each other
by commas.
Each type name is simply an identifier.
......@@ -186,11 +190,77 @@ node( l=leaf("hello"), r=node(l=leaf("there"),r=leaf("how are you")))
LALR, REX, Miranda Language Definition.
LALR, REX, Haskell Language Definition.
May 2014: After saying for 20 years that
"I must implement the missing free_TYPE functions sometime",
I have now experimentally added support for this. Currently
you have to enable the generation of these via '-f',
.I "Datadec"
will then generate a series of free_TYPE( TYPE t ) functions,
essentially these will perform a post-order tree traversal,
recursively freeing every non-basic parameter in each shape.
(Basic types, not needing freeing, are things like int, long,
BOOL etc).
However, in C you often share pointers (most obviously to readonly
string literals, but whole data structures can be shared),
so the user may or may not want to free these. To handle this,
the above grammar has been extended to allow optional '-' hints
(meaning "never free this") on parameters within shapes.
So, for instance, given the type:
strlist = nil
or cons( string h, strlist t )
the corresponding free_strlist() function will attempt to
free_string( head_of_list );
(assuming that in the GLOBAL section you will then provide
a function or macro to implement free_string(), as in:
#define free_string(s) free(s)
But if you prepend a '-' to the "string h" part of the type, i.e.:
strlist = nil
or cons( -string h, strlist t )
then no call to free_string( head_of_list ) will be made.
However, even with this mechanism, it is still incredibly easy to
share pointers when building data structures, such that you
.I sometimes
want to free a parameter, and sometimes don't.
I am still thinking about this.
For now, I recommend that you compile all datadec generated
modules (with free functions in) against a memory checking
system like memlib, or use a tool like valgrind's memcheck
to validate your memory allocation and deallocation.
I must implement the missing free_TYPE functions sometime.
A cool extra would be a sprint_TYPE function to print into a string.
This should be a trivial modification on the code that prints to a file,
......@@ -201,7 +271,7 @@ Some single letter typenames (eg. "f" or "p") could clash with internal
parameter names in the print routines, leading to syntax errors when you
compile the files generated by datadec.
And, finally, one day I'll have to write the C++ and Java versions :-)
And, finally, one day I'll have to write the Perl, C++ and (perhaps) Java versions :-)
Duncan C. White,
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment