1pod::prima-gencls(3) User Contributed Perl Documentation pod::prima-gencls(3)
2
6 gencls - class interface compiler for Prima core modules
7
9 gencls --h --inc --tml -O -I<name> --depend --sayparent filename.cls
10
12 Creates headers with C macros and structures for Prima core module
13 object definitions.
14
16 gencls accepts the following arguments:
17 --h Generates .h file ( with declarations to be included in one or more
19 files )
20 --inc
22 Generates .inc file ( with declarations to be included in only file
23 )
24 -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 --tml
36 Generates .tml file. Turns "-O" automatically on.
37 -Idirname
39 Adds a directory to a search path, where the utility searches for
40 .cls files. Can be specified several times.
41 --depend
43 Prints out dependencies for a given file.
44 --sayparent
46 Prints out the immediate parent of a class inside given file.
47
49 In short, the syntax of a .cls file can be described by the following
50 scheme:
51 [ zero or more type declarations ]
53 [ zero or one class declaration ]
54 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 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 The types are:
66 int
68 Bool
69 Handle
70 double
71 SV*
72 HV*
73 char *
74 string ( C declaration is char[256] )
75 There are also some derived built-in types, which are
77 long
79 short
80 char
81 Color
82 U8
83 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 Derived data types
89 The syntax for a new data types definition is as follows:
90 <scope> <prefix> <id> <definition>
92 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 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 Direct aliasing
105 Syntax:
106 <scope> $id => <basic_scalar_type>;
108 Example:
110 global $Handle => int;
112 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 C macro
117 Syntax:
118 <scope> id1 id2
120 Example:
122 global API_HANDLE UV
124 Such code creates a C macro definition in .h header file in form
126 #define id1 id2
128 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 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 Gencls allows several combinations of complex data types that C
139 language does not recognize. These will be described below.
140 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 Arrays
146 Syntax:
147 <scope> @id <basic_scalar_type>[dimension];
149 Example:
151 global @FillPattern U8[8];
153 Example of functions using arrays:
155 Array * func( Array a1, Array * a2);
157 Perl code:
159 @ret = func( @array1, @array2);
161 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 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 Array func();
171 Structs
173 Syntax:
174 <scope> @id {
176 <basic_scalar_type> <id>;
177 ...
178 <basic_scalar_type> <id>;
179 };
180 Example:
182 global @Struc {
184 int number;
185 string id;
186 }
187 Example of functions using structs:
189 Struc * func1( Struc a1, Struc * a2);
191 Struc func2( Struc a1, Struc * a2);
192 Perl code:
194 @ret = func1( @struc1, @struc2);
196 @ret = func2( @struc1, @struc2);
197 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 Hashes
204 Syntax:
205 <scope> %id {
207 <basic_scalar_type> <id>;
208 ...
209 <basic_scalar_type> <id>;
210 };
211 Example:
213 global %Hash {
215 int number;
216 string id;
217 }
218 Example of functions using hashes:
220 Hash * func1( Hash a1, Hash * a2);
222 Hash func2( Hash a1, Hash * a2);
223 Perl code:
225 %ret = %{func1( \%hash1, \%hash2)};
227 %ret = %{func2( \%hash1, \%hash2)};
228 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 Back conversion does not count on these values and always returns
236 all hash keys with a corresponding pair.
237 Namespace section
239 Syntax:
240 <namespace> <ID> {
242 <declaration>
243 ...
244 <declaration>
245 }
246 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 The package namespace syntax allows only declaration of functions
253 inside a "package" block.
254 package <Package ID> {
256 <function description>
257 ...
258 }
259 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 object <Class ID> [(Parent class ID)] {
265 <variables>
266 <methods>
267 <properties>
268 }
269 Within an object namespace the inheritance syntax can be used:
271 object <Class ID> ( <Parent class ID>) { ... }
273 or a bare root object description ( with no ancestor )
275 object <Class ID> { ... }
277 for the object class declaration.
279 Functions
281 Syntax:
282 [<prefix>] <type> <function_name> (<parameter list>) [ => <alias>];
284 Examples:
286 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 A prefix is used with object functions ( methods ) only. More on the
292 prefix in Methods section.
293 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 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 Example: ellipsis (...) cannot be converted by gencls, however it is a
307 legal C construction.
308 Point package_func2( Struc * x, ...);
310 The function syntax has several convenience additions:
312 Default parameter values
314 Example:
315 void func( int a = 15);
317 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 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 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 Example:
337 package Package {
339 void func( int x) => internal;
340 }
341 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 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 This declaration is used heavily in constructors, which perl code
356 is typical
357 sub init
359 {
360 my %ret = shift-> SUPER::init( @_);
361 ...
362 return %ret;
363 }
364 and C code is usually
366 void Obj_init ( HV * profile) {
368 inherited init( profile);
369 ... [ modify profile content ] ...
370 }
371 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 method void a( int x)
383 for an object class Object is reflected in C as
385 void Object_a( Handle self, int x)
387 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 Methods are accessible in C code by the direct name dereferencing of a
395 "Handle self" as a corresponding structure:
396 ((( PSampleObject) self)-> self)-> sample_method( self, ...);
398 A method can have one of six prefixes that govern C code generation:
400 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 method void a()
408 results in
410 void Object_a( Handle self)
412 C declaration. A published method automatically converts its
414 parameters and a result between C and perl.
415 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 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 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 Class::Object-> static_method();
444 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 static a( char * className = "");
450 but is if does, a
452 static a( SV * class_or_object = nil);
454 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 Class::Object::static_method();
460 where no parameters are passed to it. Without the default parameter
462 such a call generates an 'insufficient parameters passed' runtime
463 error.
464 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 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 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 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 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 property char * name
503 has C counterpart
505 char * Object_name( Handle self, Bool set, char * name)
507 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 The syntax for multi-parameter property is
513 property long pixel( int x, int y);
515 and C code
517 long Object_pixel( Handle self, Bool set, int x, int y, long pixel)
519 Note that in the multi-parameter case the parameters declared after
521 property name are always initialized, in both 'set' and 'get' modes.
522 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 object SampleObject {
533 int x;
534 List list;
535 struct { int x } s; # illegal declaration
536 }
537 Variables are accessible in C code by direct name dereferencing of a
539 "Handle self" as a corresponding structure:
540 (( PSampleObject) self)-> x;
542
544 Dmitry Karasik, <dmitry@karasik.eu.org>. Anton Berezin,
545 <tobez@tobez.org>.
546
548 Prima::internals, tmlink
549
551 This program is distributed under the BSD License.
552perl v5.32.1 2021-01-27 pod::prima-gencls(3)