docs/pmc2c.pod

   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
  33 If the C<no_init> flag was used, then no init function is generated.
  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
  70 =item C<no_init>
  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
 129  pmclass TclInt hll Tcl maps Integer
 130
 131 allows this PMC to automatically be used when autoboxing C<I> registers to PMCs.
 132
 133 Requires the C<hll> flag. Note that multiple mappings can be specified:
 134
 135  pmclass myOrderedHash hll frob maps Hash maps Array
 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 static type of C<SELF> (in
 170 other words, calls another method defined in the same file).
 171
 172 =item C<DYNSELF.method(a,b,c)>
 173
 174 Calls the vtable method 'method' using the dynamic type of C<SELF>.
 175
 176 =item C<DYNSELF(a,b,c)>
 177
 178 Same as above, but calls the current method.
 179
 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