1pod::prima-gencls(3)  User Contributed Perl Documentation pod::prima-gencls(3)
2
3
4

NAME

6       gencls - class interface compiler for Prima core modules
7

SYNOPSIS

9         gencls --h --inc --tml -O -I<name> --depend --sayparent filename.cls
10

DESCRIPTION

12       Creates headers with C macros and structures for Prima core module
13       object definitions.
14

ARGUMENTS

16       gencls accepts the following arguments:
17
18       --h Generates .h file ( with declarations to be included in one or more
19           files )
20
21       --inc
22           Generates .inc file ( with declarations to be included in only file
23           )
24
25       -O  Turns optimizing algorithm for .inc files on. Algorithm is based on
26           an assumption, that some functions are declared identically,
27           therefore the code piece that handles the parameter and result
28           conversion can be shared. With "-O" flag on, a thunk body is
29           replaced to a call to a function, which name is made up from all
30           method parameters plus result.  Actual function is not written in
31           .inc file, but in .tml file.  All duplicate declarations from a set
32           of .tml files can be removed and the reminder written to one file
33           by tmlink utility.
34
35       --tml
36           Generates .tml file. Turns "-O" automatically on.
37
38       -Idirname
39           Adds a directory to a search path, where the utility searches for
40           .cls files. Can be specified several times.
41
42       --depend
43           Prints out dependencies for a given file.
44
45       --sayparent
46           Prints out the immediate parent of a class inside given file.
47

SYNTAX

49       In short, the syntax of a .cls file can be described by the following
50       scheme:
51
52         [ zero or more type declarations ]
53         [ zero or one class declaration ]
54
55       Gencls produces .h, .inc or .tml files, with a base name of the .cls
56       file, if no object or package name given, or with a name of the object
57       or the package otherwise.
58
59   Basic scalar data types
60       Gencls has several built-in scalar data types, that it knows how to
61       deal with. To 'deal' means that it can generate a code that transfers
62       data of these types between C and perl, using XS ( see perlguts )
63       library interface.
64
65       The types are:
66
67          int
68          Bool
69          Handle
70          double
71          SV*
72          HV*
73          char *
74          string ( C declaration is char[256] )
75
76       There are also some derived built-in types, which are
77
78          long
79          short
80          char
81          Color
82          U8
83
84       that are mapped to int. The data undergo no conversion to int in
85       transfer process, but it is stored instead to perl scalar using
86       newSViv() function, which, in turn, may lose bits or a sign.
87
88   Derived data types
89       The syntax for a new data types definition is as follows:
90
91          <scope> <prefix> <id> <definition>
92
93       A scope can be one of two pragmas, "global" or "local".  They hint the
94       usage of a new data type, whether the type will be used only for one or
95       more objects. Usage of "local" is somewhat resembles C pragma static.
96       Currently the only difference is that a function using a complex local
97       type in the parameter list or as the result is not a subject for "-O"
98       optimization.
99
100   Scalar types
101       New scalar types may only be aliased to the existing ones, primarily
102       for C coding convenience.  A scalar type can be defined in two ways:
103
104       Direct aliasing
105           Syntax:
106
107             <scope> $id => <basic_scalar_type>;
108
109           Example:
110
111             global $Handle => int;
112
113           The new type id will not be visible in C files, but the type will
114           be substituted over all .cls files that include this definition.
115
116       C macro
117           Syntax:
118
119             <scope> id1 id2
120
121           Example:
122
123             global API_HANDLE UV
124
125           Such code creates a C macro definition in .h header file in form
126
127             #define id1 id2
128
129           C macros with parameters are not allowed. id1 and id2 are not
130           required to be present in .cls name space, and no substitution
131           during .cls file processing is made.  This pragma usage is very
132           limited.
133
134   Complex types
135       Complex data types can be arrays, structs and hashes.  They can be a
136       combination or a vector of scalar ( but not complex) data types.
137
138       Gencls allows several combinations of complex data types that C
139       language does not recognize. These will be described below.
140
141       Complex data types do not get imported into perl code.  A perl
142       programmer must conform to the data type used when passing parameters
143       to a function.
144
145       Arrays
146           Syntax:
147
148             <scope> @id <basic_scalar_type>[dimension];
149
150           Example:
151
152             global @FillPattern U8[8];
153
154           Example of functions using arrays:
155
156             Array * func( Array a1, Array * a2);
157
158           Perl code:
159
160             @ret = func( @array1, @array2);
161
162           Note that array references are not used, and the number of items in
163           all array parameters must be exactly as the dimensions of the
164           arrays.
165
166           Note: the following declaration will not compile with C compiler,
167           as C cannot return arrays. However it is not treated as an error by
168           gencls:
169
170             Array func();
171
172       Structs
173           Syntax:
174
175             <scope> @id {
176                <basic_scalar_type> <id>;
177                ...
178                <basic_scalar_type> <id>;
179             };
180
181           Example:
182
183             global @Struc {
184                int    number;
185                string id;
186             }
187
188           Example of functions using structs:
189
190             Struc * func1( Struc a1, Struc * a2);
191             Struc   func2( Struc a1, Struc * a2);
192
193           Perl code:
194
195             @ret = func1( @struc1, @struc2);
196             @ret = func2( @struc1, @struc2);
197
198           Note that array references are not used, and both number and order
199           of items in all array parameters must be set exactly as dimensions
200           and order of the structs. Struct field names are not used in perl
201           code as well.
202
203       Hashes
204           Syntax:
205
206             <scope> %id {
207                <basic_scalar_type> <id>;
208                ...
209                <basic_scalar_type> <id>;
210             };
211
212           Example:
213
214             global %Hash {
215                int    number;
216                string id;
217             }
218
219           Example of functions using hashes:
220
221             Hash * func1( Hash a1, Hash * a2);
222             Hash   func2( Hash a1, Hash * a2);
223
224           Perl code:
225
226             %ret = %{func1( \%hash1, \%hash2)};
227             %ret = %{func2( \%hash1, \%hash2)};
228
229           Note that only hash references are used and returned.  When a hash
230           is passed from perl code it might have some or all fields unset.
231           The C structure is filled and passed to a C function, and the
232           fields that were unset are assigned to a corresponding C_TYPE_UNDEF
233           value, where TYPE is one of NUMERIC, STRING and POINTER literals.
234
235           Back conversion does not count on these values and always returns
236           all hash keys with a corresponding pair.
237
238   Namespace section
239       Syntax:
240
241          <namespace> <ID> {
242             <declaration>
243             ...
244             <declaration>
245          }
246
247       A .cls file can have zero or one namespace sections, filled with
248       function descriptions. Functions described here will be exported to the
249       given ID during initialization code. A namespace can be either "object"
250       or "package".
251
252       The package namespace syntax allows only declaration of functions
253       inside a "package" block.
254
255           package <Package ID> {
256               <function description>
257               ...
258           }
259
260       The object namespace syntax includes variables and properties as well
261       as functions ( called methods in the object syntax ).  The general
262       object namespace syntax is
263
264           object <Class ID> [(Parent class ID)] {
265              <variables>
266              <methods>
267              <properties>
268           }
269
270       Within an object namespace the inheritance syntax can be used:
271
272           object <Class ID> ( <Parent class ID>)  { ... }
273
274       or a bare root object description ( with no ancestor )
275
276           object <Class ID> { ... }
277
278       for the object class declaration.
279
280   Functions
281       Syntax:
282
283           [<prefix>] <type> <function_name> (<parameter list>) [ => <alias>];
284
285       Examples:
286
287               int   package_func1( int a, int b = 1) => c_func_2;
288               Point package_func2( Struc * x, ...);
289        method void  object_func3( HV * profile);
290
291       A prefix is used with object functions ( methods ) only.  More on the
292       prefix in Methods section.
293
294       A function can return nothing ( void ), a scalar ( int, string, etc )
295       or a complex ( array, hash ) type. It can as well accept scalar and
296       complex parameters, with type conversion that corresponds to the rules
297       described above in "Basic scalar data types" section.
298
299       If a function has parameters and/or result of a type that cannot be
300       converted automatically between C and perl, it gets declared but not
301       exposed to perl namespace.  The corresponding warning is issued.  It is
302       not possible using gencls syntax to declare a function with custom
303       parameters or result data.  For such a purpose the explicit C
304       declaration of code along with "newXS" call must be made.
305
306       Example: ellipsis (...) cannot be converted by gencls, however it is a
307       legal C construction.
308
309         Point package_func2( Struc * x, ...);
310
311       The function syntax has several convenience additions:
312
313       Default parameter values
314           Example:
315
316             void func( int a = 15);
317
318           A function declared in such way can be called both with 0 or 1
319           parameters. If it is called with 0 parameters, an integer value of
320           15 will be automatically used.  The syntax allows default
321           parameters for types int, pointer and string and their scalar
322           aliases.
323
324           Default parameters can be as many as possible, but they have to be
325           in the end of the function parameter list.  Declaration "func( int
326           a = 1, int b)" is incorrect.
327
328       Aliasing
329           In the generated C code, a C function has to be called after the
330           parameters have been parsed. Gencls expects a conformant function
331           to be present in C code, with fixed name and parameter list.
332           However, if the task of such function is a wrapper to an identical
333           function published under another name, aliasing can be preformed to
334           save both code and speed.
335
336           Example:
337
338              package Package {
339                 void func( int x) => internal;
340              }
341
342           A function declared in that way will not call Package_func() C
343           function, but internal() function instead. The only request is that
344           internal() function must have identical parameter and result
345           declaration to a func().
346
347       Inline hash
348           A handy way to call a function with a hash as a parameter from perl
349           was devised. If a function is declared with the last parameter or
350           type "HV*", then parameter translation from perl to C is performed
351           as if all the parameters passed were a hash. This hash is passed to
352           a C function and it's content returned then back to perl as a hash
353           again.  The hash content can be modified inside the C function.
354
355           This declaration is used heavily in constructors, which perl code
356           is typical
357
358              sub init
359              {
360                 my %ret = shift-> SUPER::init( @_);
361                 ...
362                 return %ret;
363              }
364
365           and C code is usually
366
367              void Obj_init ( HV * profile) {
368                  inherited init( profile);
369                  ... [ modify profile content ] ...
370              }
371
372   Methods
373       Methods are functions called in a context of an object.  Virtually all
374       methods need to have an access to an object they are dealing with.
375       Prima objects are visible in C as Handle data type. Such Handle is
376       actually a pointer to an object instance, which in turn contains a
377       pointer to the object virtual methods table ( VMT ).  To facilitate an
378       OO-like syntax, this Handle parameter is almost never mentioned in all
379       methods of an object description in a cls file, although being implicit
380       counted, so every cls method declaration
381
382          method void a( int x)
383
384       for an object class Object is reflected in C as
385
386          void Object_a( Handle self, int x)
387
388       function declaration. Contrary to package functions, that gencls is
389       unable to publish if it is unable to deal with the unsupported on
390       unconvertible parameters, there is a way to issue such a declaration
391       with a method. The primary use for that is the method name gets
392       reserved in the object's VMT.
393
394       Methods are accessible in C code by the direct name dereferencing of a
395       "Handle self" as a corresponding structure:
396
397           ((( PSampleObject) self)-> self)-> sample_method( self, ...);
398
399       A method can have one of six prefixes that govern C code generation:
400
401       method
402           This is the first and the most basic method type.  It's prefix
403           name, "method" is therefore was chosen as the most descriptive
404           name. Methods are expected to be coded in C, the object handle is
405           implicit and is not included into a .cls description.
406
407              method void a()
408
409           results in
410
411              void Object_a( Handle self)
412
413           C declaration. A published method automatically converts its
414           parameters and a result between C and perl.
415
416       public
417           When the methods that have parameters and/or result that cannot be
418           automatically converted between C and perl need to be declared, or
419           the function declaration does not fit into C syntax, a "public"
420           prefix is used. The methods declared with "public" is expected to
421           communicate with perl by means of XS ( see perlxs ) interface. It
422           is also expected that a "public" method creates both REDEFINED and
423           FROMPERL functions ( see Prima::internals  for details). Examples
424           are many throughout Prima source, and will not be shown here.
425           "public" methods usually have void result and no parameters, but
426           that does not matter much, since gencls produces no conversion for
427           such methods.
428
429       import
430           For the methods that are unreasonable to code in C but in perl
431           instead, gencls can be told to produce the corresponding wrappers
432           using "import" prefix. This kind of a method can be seen as
433           "method" inside-out. "import" function does not need a C
434           counterpart, except the auto-generated code.
435
436       static
437           If a method has to be able to work both with and without an object
438           instance, it needs to be prepended with "static" prefix.  "static"
439           methods are all alike "method" ones, except that "Handle self"
440           first parameter is not implicitly declared.  If a "static" method
441           is called without an object ( but with a class ), like
442
443              Class::Object-> static_method();
444
445           its first parameter is not a object but a "Class::Object" string.
446           If a method never deals with an object, it is enough to use its
447           declaration as
448
449              static a( char * className = "");
450
451           but is if does, a
452
453              static a( SV * class_or_object = nil);
454
455           declaration is needed. In latter case C code itself has to
456           determine what exactly has been passed, if ever. Note the default
457           parameter here: a "static" method is usually legible to call as
458
459             Class::Object::static_method();
460
461           where no parameters are passed to it. Without the default parameter
462           such a call generates an 'insufficient parameters passed' runtime
463           error.
464
465       weird
466           We couldn't find a better name for it. "weird" prefix denotes a
467           method that combined properties both from "static" and "public". In
468           other words, gencls generates no conversion code and expects no
469           "Handle self" as a first parameter for such a method. As an example
470           Prima::Image::load can be depicted, which can be called using a
471           wide spectrum of calling semantics ( see Prima::image-load for
472           details).
473
474       c_only
475           As its name states, "c_only" is a method that is present on a VMT
476           but is not accessible from perl. It can be overloaded from C only.
477           Moreover, it is allowed to register a perl function with a name of
478           a "c_only" method, and still these entities will be wholly
479           independent from each other - the overloading will not take place.
480
481           NB: methods that have result and/or parameters data types that can
482           not be converted automatically, change their prefix to "c_only".
483           Probably this is the wrong behavior, and such condition have to
484           signal an error.
485
486   Properties
487       Prima toolkit introduces an entity named property, that is expected to
488       replace method pairs whose function is to acquire and assign some
489       internal object variable, for example, an object name, color etc.
490       Instead of having pair of methods like Object::set_color and
491       Object::get_color, a property Object::color is devised. A property is a
492       method with the special considerations, in particular, when it is
493       called without parameters, a 'get' mode is implied. In contrary, if it
494       is called with one parameter, a 'set' mode is triggered. Note that on
495       both 'set' and 'get' invocations "Handle self" first implicit parameter
496       is always present.
497
498       Properties can operate with different, but fixed amount of parameters,
499       and perform a 'set' and 'get' functions only for one. By default the
500       only parameter is the implicit "Handle self":
501
502          property char * name
503
504       has C counterpart
505
506          char * Object_name( Handle self, Bool set, char * name)
507
508       Depending on a mode, "Bool set" is either "true" or "false".  In 'set'
509       mode a C code result is discarded, in 'get' mode the parameter value is
510       undefined.
511
512       The syntax for multi-parameter property is
513
514          property long pixel( int x, int y);
515
516       and C code
517
518          long Object_pixel( Handle self, Bool set, int x, int y, long pixel)
519
520       Note that in the multi-parameter case the parameters declared after
521       property name are always initialized, in both 'set' and 'get' modes.
522
523   Instance variables
524       Every object is characterized by its unique internal state.  Gencls
525       syntax allows a variable declaration, for variables that are allocated
526       for every object instance. Although data type validation is not
527       performed for variables, and their declarations just get copied 'as
528       is', complex C declarations involving array, struct and function
529       pointers are not recognized.  As a workaround, pointers to typedef'd
530       entities are used.  Example:
531
532          object SampleObject {
533             int x;
534             List list;
535             struct { int x } s; # illegal declaration
536          }
537
538       Variables are accessible in C code by direct name dereferencing of a
539       "Handle self" as a corresponding structure:
540
541           (( PSampleObject) self)-> x;
542

AUTHORS

544       Dmitry Karasik, <dmitry@karasik.eu.org>.  Anton Berezin,
545       <tobez@tobez.org>.
546

SEE ALSO

548       Prima::internals, tmlink
549
551       This program is distributed under the BSD License.
552
553
554
555perl v5.28.0                      2017-02-28              pod::prima-gencls(3)
Impressum