Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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