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

added free_type() documentation..

parent b63f05e8
...@@ -3,14 +3,14 @@ ...@@ -3,14 +3,14 @@
datadec \- ANSI C data declaration module constructor datadec \- ANSI C data declaration module constructor
.SH SYNOPSIS .SH SYNOPSIS
datadec datadec
.RB [\- vno ] .RB [\- vfno ]
.I basename .I basename
.RB [infile] .RB [infile]
.SH DESCRIPTION .SH DESCRIPTION
.B Datadec .B Datadec
takes an input file - or stdin if no input file is given - takes an input file - or stdin if no input file is given -
containing a series of HOPE/Miranda style recursive data declarations containing a series of Haskell style recursive (or inductive) datatype
with optional hints on printing, declarations - with optional hints on printing and freeing,
and builds an definition/implementation pair of ANSI C files \- and builds an definition/implementation pair of ANSI C files \-
.I "basename.h" .I "basename.h"
and and
...@@ -30,6 +30,10 @@ enter verbose mode. ...@@ -30,6 +30,10 @@ enter verbose mode.
now displays the data types that it parses, along with various almost now displays the data types that it parses, along with various almost
certainly useless bits of information about optimization. certainly useless bits of information about optimization.
.TP .TP
.B "\-f"
Enable experimental generation of free_TYPE() functions.
See the later section on free functions.
.TP
.B "\-n" .B "\-n"
do not perform various optimizations. do not perform various optimizations.
.TP .TP
...@@ -129,7 +133,7 @@ shape = constructor_name [ '(' params ') ] [ print ] ...@@ -129,7 +133,7 @@ shape = constructor_name [ '(' params ') ] [ print ]
.br .br
params = param list( ',' param) params = param list( ',' param)
.br .br
param = type_name param_name param = ['-'] type_name param_name
.br .br
print = list(element) print = list(element)
.br .br
...@@ -139,7 +143,7 @@ element = number | string_literal ...@@ -139,7 +143,7 @@ element = number | string_literal
.PP .PP
Note that each data type is terminated by a semicolon, 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' 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 If a particular shape has parameters, they are separated from each other
by commas. by commas.
Each type name is simply an identifier. 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"))) ...@@ -186,11 +190,77 @@ node( l=leaf("hello"), r=node(l=leaf("there"),r=leaf("how are you")))
.SH SEE ALSO .SH SEE ALSO
.nf .nf
LALR, REX, Miranda Language Definition. LALR, REX, Haskell Language Definition.
.fi
.SH FREE FUNCTIONS (EXPERIMENTAL)
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).
.PP
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.
.PP
So, for instance, given the type:
.nf
TYPE {
strlist = nil
or cons( string h, strlist t )
}
.fi
the corresponding free_strlist() function will attempt to
.nf
free_string( head_of_list );
.fi .fi
.PP
(assuming that in the GLOBAL section you will then provide
a function or macro to implement free_string(), as in:
.nf
#define free_string(s) free(s)
.fi
.PP
But if you prepend a '-' to the "string h" part of the type, i.e.:
.nf
TYPE {
strlist = nil
or cons( -string h, strlist t )
}
.fi
.PP
then no call to free_string( head_of_list ) will be made.
.PP
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.
.SH MISSING FEATURES .SH MISSING FEATURES
I must implement the missing free_TYPE functions sometime.
.PP .PP
A cool extra would be a sprint_TYPE function to print into a string. 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, 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 ...@@ -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 parameter names in the print routines, leading to syntax errors when you
compile the files generated by datadec. compile the files generated by datadec.
.PP .PP
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 :-)
.SH "AUTHOR" .SH "AUTHOR"
Duncan C. White, D.White@imperial.ac.uk. Duncan C. White, D.White@imperial.ac.uk.
Markdown is supported
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