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<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
 124  pmclass TclInt hll Tcl maps Integer
 125
 126 allows this PMC to automatically be used when autoboxing C<I> registers to PMCs.
 127
 128 Requires the C<hll> flag. Note that multiple mappings can be specified:
 129
 130  pmclass myOrderedHash hll frob maps Hash maps Array
 131
 132 =back
 133
 134 =item 3.
 135
 136 A list of vtable method implementations
 137
 138 =item 4.
 139
 140 The final close C<}>
 141
 142 =back
 143
 144 =head2 Method Body Substitutions
 145
 146 The vtable method bodies can use the following substitutions:
 147
 148 =over 4
 149
 150 =item C<SELF>
 151
 152 Converted to the current PMC object of type C<PMC *>.
 153
 154 =item C<INTERP>
 155
 156 Converted to the interpreter object.
 157
 158 =item C<OtherClass.SELF.method(a,b,c)>
 159
 160 Calls the static vtable method 'method' in C<OtherClass>.
 161
 162 =item C<SELF.method(a,b,c)>
 163
 164 Calls the vtable method 'method' using the dynamic type of C<SELF>.
 165
 166 =item C<SELF(a,b,c)>
 167
 168 Same as above, but calls the current method.
 169
 170 =item C<STATICSELF.method(a,b,c)>
 171
 172 Calls the vtable method 'method' using the static type of C<SELF> (in
 173 other words, calls another method defined in the same file).
 174
 175 =item C<OtherClass.SUPER(a,b,c)>
 176
 177 Calls the overridden implementation of the current method in
 178 C<OtherClass>.
 179
 180 =item C<SUPER(a,b,c)>
 181
 182 Calls the overridden implementation of the current method in the nearest
 183 superclass, using the type of C<SELF>.
 184
 185 =back
 186
 187 =head1 AUTHOR
 188
 189 Leopold Toetsch.
 190
 191 Cleaned up by Matt Diephouse.
 192
 193 Many thanks to the author of F<pmc2c.pl>, many useful code pieces got
 194 reused.
 195
 196 =cut