Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 206 lines (120 sloc) 5.083 kb
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
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
30765f8 @particle [PDD17]: rename pmc definition modifier 'noinit' to 'no_init' for con…
particle authored
33 If the C<no_init> flag was used, then no init function is generated.
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
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
30765f8 @particle [PDD17]: rename pmc definition modifier 'noinit' to 'no_init' for con…
particle authored
70 =item C<no_init>
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
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<need_ext>
80
81 The class needs a C<PMC_EXT> structure. For instance, any class using
82 C<PMC_data> will have C<need_ext>.
83
84 =item C<does interface>
85
86 The class 'does' the given interfaces (the collection of methods
87 which the class implements).
88
89 The default is "scalar". Other currently used interfaces are:
90
91 array : container PMC with numerically-keyed elements
92 event : PMC that can be used with event queue
93 hash : container PMC with string-keyed elements
94 library : PMC that corresponds to a dynamic library
95 ref : PMC that references another PMC
96 string : PMC that behaves similarly to the base string type
97 boolean : PMC that does true/false only.
98 integer : PMC that behaves similarly to the base int type
99 float : PMC that behaves similarly to the base number type
100 scalar : (only used by the sample src/dynpmc/foo.pmc)
101
102 This is not a canonical list, but merely a snapshot of what's in use.
103
104 =item C<dynpmc>
105
106 The class is a dynamic class. These have a special C<class_init>
107 routine suitable for dynamic loading at runtime. See the F<src/dynpmc>
108 directory for an example.
109
110 =item C<group GROUP>
111
112 The class is part of a group of interrelated PMCs that should be
113 compiled together into a single shared library of the given name. Only
114 valid for dynamic PMCs.
115
116 =item C<lib LIB>
117
118 The class needs an external library.
119
120 =item C<hll HLL>
121
122 The High level language this PMC corresponds to.
123
124 =item C<maps Type>
125
126 The basic parrot PMC type that this PMC correspond to for C<.HLL>
127 usage. For example:
128
b6641b0 @coke Resolve ticket #38168 ([TODO] - Tcl - :slurpy HLL mappings)
coke authored
129 pmclass TclInt hll Tcl maps Integer
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
130
131 allows this PMC to automatically be used when autoboxing C<I> registers to PMCs.
132
b6641b0 @coke Resolve ticket #38168 ([TODO] - Tcl - :slurpy HLL mappings)
coke authored
133 Requires the C<hll> flag. Note that multiple mappings can be specified:
134
135 pmclass myOrderedHash hll frob maps Hash maps Array
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
136
137 =back
138
139 =item 3.
140
141 A list of vtable method implementations
142
143 =item 4.
144
145 The final close C<}>
146
147 =back
148
149 =head2 Method Body Substitutions
150
151 The vtable method bodies can use the following substitutions:
152
153 =over 4
154
155 =item C<SELF>
156
157 Converted to the current PMC object of type C<PMC *>.
158
159 =item C<INTERP>
160
161 Converted to the interpreter object.
162
163 =item C<OtherClass.SELF.method(a,b,c)>
164
165 Calls the static vtable method 'method' in C<OtherClass>.
166
167 =item C<SELF.method(a,b,c)>
168
169 Calls the vtable method 'method' using the dynamic type of C<SELF>.
170
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
171 =item C<SELF(a,b,c)>
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
172
173 Same as above, but calls the current method.
174
59661f1 @allisonrandal [pdd17pmc] Merging the pdd17pmc branch into trunk (r24435 to r26307).
allisonrandal authored
175 =item C<STATICSELF.method(a,b,c)>
176
177 Calls the vtable method 'method' using the static type of C<SELF> (in
178 other words, calls another method defined in the same file).
179
59359ca @tewk [Pmc2c] Continued cleanup and reorg
tewk authored
180 =item C<OtherClass.SUPER(a,b,c)>
181
182 Calls the overridden implementation of the current method in
183 C<OtherClass>.
184
185 =item C<SUPER(a,b,c)>
186
187 Calls the overridden implementation of the current method in the nearest
188 superclass, using the static type of C<SELF>.
189
190 =item C<DYNSUPER(a,b,c)>
191
192 As above, but uses the actual dynamic type of C<SELF>.
193
194 =back
195
196 =head1 AUTHOR
197
198 Leopold Toetsch.
199
200 Cleaned up by Matt Diephouse.
201
202 Many thanks to the author of F<pmc2c.pl>, many useful code pieces got
203 reused.
204
205 =cut
Something went wrong with that request. Please try again.