Repository navigation
Expand file tree
/
Copy pathtuNotes.xml
More file actions
203 lines (163 loc) · 5.92 KB
/
Copy pathtuNotes.xml
File metadata and controls
203 lines (163 loc) · 5.92 KB
1
2
3
4
5
6
7
8
9
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
<?xml version="1.0"?>
<article xmlns:r="http://www.r-project.org">
<section>
<title>Introduction</title>
<para>
In this article, we show how we can create the
code for the R interface to some of the routines and data structures
in the unzip.c file (and associated header file).
</para>
<ignore> <!--XXX -->
We want to do something like do_list but we want the results in R.
<r:code>
unz = unzOpen(filename)
gi = unzGetGlobalInfo(unz)
for(i in 1:gi$number_entry) {
info = unzGetCurrentFileInfo(unz)
# info should return a (reference to or copy of) the unz_file_info object
# and the name of the file. These are both output arguments.
}
</r:code>
We need to tell the code generation mechanism that
unz_file_info
unzFile
</ignore>
</section>
<section>
<title>Creating the R interface from the TU file</title>
<para>
We start by parsing the tu file
<ignore>
We note that we are only generating the bindings for a particular collection
of data structures and routines in the <file>unzip.c</file> file.
</ignore>
<r:code>
library(RGCCTranslationUnit)
p = parseTU.Perl("unzip.c.tu", "C")
</r:code>
<ignore>
Don't need to do this.
<r:code>
defs = getDataStructures(p, c("miniunz", "miniunzip", "unzip"))
</r:code>
</ignore>
<ignore>
<r:code>
routineNames = c("unzOpen", "unzClose", "unzGoToFirstFile", "unzGoToNextFile",
"unzGetGlobalInfo", "unzGetCurrentFileInfo")
</r:code>
</ignore>
<r:code>
We find all the routines in the files name miniunz, miniunzip and
unzip. Then we resolve these routines into their complete
definitions, i.e. with all the type information collected into
self-describing R objects. All the type information is now centralized
in the <r:var>types</r:var> variable (which is an environment used for
holding this information as it is gathered).
<r:code>
routines = getRoutines(p, c("miniunz", "miniunzip", "unzip"))
types = DefinitionContainer()
rdefs = lapply(routines, resolveType, p, types)
</r:code>
Now we have the information about the routines, we can
generate the code to interface from R to these routines.
<r:code>
bindings = lapply(rdefs, createMethodBinding)
</r:code>
In the case of <c:routine>unzGetGlobalInfo</c:routine>,
we want to tell the code generation mechanism
that the second parameter is in fact a pure out argument.
It is used merely to convey the result back to the caller
and so, in the R interface function, we don't want the user to see it.
<r:code>
cat(createMethodBinding(rdefs$unzGetGlobalInfo, paramStyle = c("", "out"))$native)
</r:code>
Similarly, the routine <c:routine>unzGetCurrentFileInfo</c:routine>
has only one pure in parameter (the first), one pure out parameter
(the second) and the remaining 3 are in/out parameters. So we want the
R user to be able to specify all but the out parameter.
<r:code>
cat(createMethodBinding(rdefs$unzGetCurrentFileInfo,
paramStyle = c("", "out", rep(c("inout", ""), 3)),
defaultRValues = c("szFileName" = 'paste(rep(".", 256), sep = "")',
fileNameBufferSize = "nchar(szFileName)",
extraField = "raw(0)",
extraFieldBufferSize = "length(extraField)",
szComment = "''",
commentBufferSize = "nchar(szComment)"))$r)
</r:code>
Now we want to turn our attention to the code that is needed to
support these interface routines and R functions. Specifically, we
need the code to marshall the C data structures to and from R and
similarly, we need R classes to represent these structures in R.
We start with the C code.
<r:code>
cat(createCopyStruct(types$unz_file_info))
cat(createCopyStruct(types$tm_unz)) # tm_unz or unz_tm?
</r:code>
And now the R classes.
<r:code>
#defineStructClass(types$unz_file_info)
# order is important.
invisible(sapply(defineStructClass(types$unz_file_info, types), function(x) cat(x, "\n")))
invisible(sapply(defineStructClass(types$tm_unz, types), function(x) cat(x, "\n")))
# Currently doing this by hand.
setClass("unzFile", contains = "RC++Reference",
prototype = list(classes = "unzFile"))
</r:code>
<r:code>
cat(bindings$unzOpen$native)
cat(bindings$unzClose$native)
cat(bindings$unzGoToFirstFile$native)
# Skip the 2 with the out arguments for the moment.
invisible(sapply(bindings[1:4], function(x) cat(x$r, "\n\n\n")))
</r:code>
</section>
<section>
<title>Usage Examples</title>
<r:example>
The higher-level function is getZipInfo
<r:code>
source("unzip.R")
h = unzOpen("MyZip.zip")
info = unzGetGlobalInfo(h)
ff = paste(rep(".", 256), collapse = "")
unzGetCurrentFileInfo(h, ff, nchar(ff), raw(0), 0, character(), 0)
unzGoToFirstFile(h)
els = lapply(seq(length = info[[2]]@number_entry),
function(i) {
ans = unzGetCurrentFileInfo(h, ff, nchar(ff), raw(0), 0, character(), 0)
unzGoToNextFile(h)
ans
})
# Get the file names
names(els) = sapply(els, function(x) x$szFileName)
# compression ratio
sapply(els, function(x) x[[2]]@compressed_size)/sapply(els, function(x) x[[2]]@uncompressed_size)
# Note that the month is 0-based!
els$DESCRIPTION[[2]]@tmu_date
unzClose(h)
</r:code>
</r:example>
</section>
<r:example>
Same sort of deal for untgz. We look at main and find the routines
that are in referenced in it. We can use callGraph to do this
or just examine the code itself.
For listing (or extracting) files, we see that only
gzopen and tar are used.
We will need to open the file ourselves.
And we don't want to call tar as that performs the
actions. Rather we want to see how tar access the
elements in the archive.
<r:code>
library(RGCCTranslationUnit)
p = parseTU("untgz.c.tu")
p = setLanguage(p, "C")
routines = getRoutines(p, "untgz")
types = DefinitionContainer()
rdefs = lapply(routines, resolveType, p, types)
bindings = lapply(rdefs, createMethodBinding)
</r:code>
</r:example>
</article>