Skip to content
This repository
Newer
Older
100644 207 lines (122 sloc) 5.237 kb
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
1 =head1 NAME
2
3 tools/build/pmc2c.pl - PMC definition to C compiler
4
5 =head2 Internals
6
7 To see the internal data structures please run:
8
9 % perl tools/build/pmc2c.pl --c --debug --debug sarray.pmc | less
10
11 =head2 Compiling PMCs
12
13 First, the program determines the names of the .c and .h files from
14 the basename of the .pmc file (e.g. F<perlint.pmc> -> F<perlint.c> and
15 F<perlint.h>).
16
17 Next, the file is searched for C</pmclass \w*/> which attempts to find the
18 class being declared.
19
20 Once the class is found, all of its superclasses are scanned and their
21 methods added to the methods of the current PMC. PMCs default to
22 inheriting from 'default'. Only single inheritance is supported.
23
24 Once the superclass is determined, it is processed and its method names
25 are extracted and saved.
26
27 Next, each method body is processed with various directives (see below)
28 getting replaced by their appropriate values.
29
30 Finally, the .c and .h files are generated. The appropriate base class
31 header files are included.
32
30765f88 » particle
2007-09-19 [PDD17]: rename pmc definition modifier 'noinit' to 'no_init' for con…
33 If the C<no_init> flag was used, then no init function is generated.
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
34 Otherwise, one is generated which sets up the vtable and enters it into
35 the C<vtables> array.
36
37 The .c file is generated by appending the functions after the various
38 directives have been replaced.
39
40 =head2 PMC File Syntax
41
42 The basic syntax of a PMC file is
43
44 =over 4
45
46 =item 1.
47
48 A preamble, consisting of code to be copied directly to the .c file
49
50 =item 2.
51
52 The C<pmclass> declaration:
53
54 pmclass PMCNAME [flags] {
55
56 where C<flags> are:
57
58 =over 4
59
60 =item C<extends PMCPARENT>
61
62 All methods not defined in PMCNAME are inherited from the PMCPARENT class.
63 If no parent class is defined, methods from F<default.pmc> are used.
64
65 =item C<abstract>
66
67 This class cannot be instantiated. Abstract classes are shown with lower
68 case class names in the class tree.
69
30765f88 » particle
2007-09-19 [PDD17]: rename pmc definition modifier 'noinit' to 'no_init' for con…
70 =item C<no_init>
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
71
72 Used with C<abstract>: No C<class_init> code is generated.
73
74 =item C<const_too>
75
76 Classes with this flag get 2 vtables and 2 enums, one pair with
77 read/write set methods, and one with read-only set methods.
78
79 =item C<does interface>
80
81 The class 'does' the given interfaces (the collection of methods
82 which the class implements).
83
84 The default is "scalar". Other currently used interfaces are:
85
86 array : container PMC with numerically-keyed elements
87 event : PMC that can be used with event queue
88 hash : container PMC with string-keyed elements
89 library : PMC that corresponds to a dynamic library
90 ref : PMC that references another PMC
91 string : PMC that behaves similarly to the base string type
92 boolean : PMC that does true/false only.
93 integer : PMC that behaves similarly to the base int type
94 float : PMC that behaves similarly to the base number type
95 scalar : (only used by the sample src/dynpmc/foo.pmc)
96
97 This is not a canonical list, but merely a snapshot of what's in use.
98
99 =item C<dynpmc>
100
101 The class is a dynamic class. These have a special C<class_init>
102 routine suitable for dynamic loading at runtime. See the F<src/dynpmc>
103 directory for an example.
104
105 =item C<group GROUP>
106
107 The class is part of a group of interrelated PMCs that should be
108 compiled together into a single shared library of the given name. Only
109 valid for dynamic PMCs.
110
111 =item C<lib LIB>
112
113 The class needs an external library.
114
115 =item C<hll HLL>
116
117 The High level language this PMC corresponds to.
118
119 =item C<maps Type>
120
121 The basic parrot PMC type that this PMC correspond to for C<.HLL>
122 usage. For example:
123
b6641b08 » coke
2007-11-30 Resolve ticket #38168 ([TODO] - Tcl - :slurpy HLL mappings)
124 pmclass TclInt hll Tcl maps Integer
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
125
126 allows this PMC to automatically be used when autoboxing C<I> registers to PMCs.
127
b6641b08 » coke
2007-11-30 Resolve ticket #38168 ([TODO] - Tcl - :slurpy HLL mappings)
128 Requires the C<hll> flag. Note that multiple mappings can be specified:
129
130 pmclass myOrderedHash hll frob maps Hash maps Array
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
131
132 =back
133
134 =item 3.
135
acbed8c1 » allisonrandal
2010-03-29 [doc] Adding some documentation on ATTR declarations in C-PMCs.
136 A list of attribute declarations:
137
138 ATTR INTVAL id;
139
140 The ATTR declaration keyword is followed by the type of the attribute and the
141 name of the attribute. Any valid C type is a valid attribute type, but only
142 INTVAL, FLOATVAL, STRING *, and PMC * can be handled directly from PIR. Other
143 types are generally only used by low-level internal PMCs.
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
144
145 =item 4.
146
1df1b754 » coke
2010-03-30 Eliminate 'vtable method'. It's a vtable, or a vtable function.
147 A list of vtable function implementations
acbed8c1 » allisonrandal
2010-03-29 [doc] Adding some documentation on ATTR declarations in C-PMCs.
148
149 =item 5.
150
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
151 The final close C<}>
152
153 =back
154
155 =head2 Method Body Substitutions
156
1df1b754 » coke
2010-03-30 Eliminate 'vtable method'. It's a vtable, or a vtable function.
157 The vtable function bodies can use the following substitutions:
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
158
159 =over 4
160
161 =item C<SELF>
162
163 Converted to the current PMC object of type C<PMC *>.
164
165 =item C<INTERP>
166
167 Converted to the interpreter object.
168
169 =item C<OtherClass.SELF.method(a,b,c)>
170
1df1b754 » coke
2010-03-30 Eliminate 'vtable method'. It's a vtable, or a vtable function.
171 Calls the static vtable or method 'method' in C<OtherClass>.
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
172
173 =item C<SELF.method(a,b,c)>
174
1df1b754 » coke
2010-03-30 Eliminate 'vtable method'. It's a vtable, or a vtable function.
175 Calls the vtable or method 'method' using the dynamic type of C<SELF>.
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
176
59661f18 » allisonrandal
2008-03-11 [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
177 =item C<SELF(a,b,c)>
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
178
179 Same as above, but calls the current method.
180
59661f18 » allisonrandal
2008-03-11 [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
181 =item C<STATICSELF.method(a,b,c)>
182
1df1b754 » coke
2010-03-30 Eliminate 'vtable method'. It's a vtable, or a vtable function.
183 Calls the vtable or method 'method' using the static type of C<SELF> (in
59661f18 » allisonrandal
2008-03-11 [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
184 other words, calls another method defined in the same file).
185
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
186 =item C<OtherClass.SUPER(a,b,c)>
187
188 Calls the overridden implementation of the current method in
189 C<OtherClass>.
190
191 =item C<SUPER(a,b,c)>
192
193 Calls the overridden implementation of the current method in the nearest
ddce55ee » cotto
2009-07-28 [pmc2c] rip out DYNSUPER, which isn't needed now that it and SUPER ac…
194 superclass, using the type of C<SELF>.
59359caa » tewk
2007-05-11 [Pmc2c] Continued cleanup and reorg
195
196 =back
197
198 =head1 AUTHOR
199
200 Leopold Toetsch.
201
202 Cleaned up by Matt Diephouse.
203
204 Many thanks to the author of F<pmc2c.pl>, many useful code pieces got
205 reused.
206
207 =cut
Something went wrong with that request. Please try again.