.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GENCLS 1" .TH GENCLS 1 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" gencls \- class interface compiler for Prima core modules .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& gencls \-\-h \-\-inc \-\-tml \-O \-I \-\-depend \-\-sayparent filename.cls .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Creates headers with C macros and structures for Prima core module object definitions. .SH "ARGUMENTS" .IX Header "ARGUMENTS" gencls accepts the following arguments: .IP "\-\-h" 4 .IX Item "--h" Generates .h file ( with declarations to be included in one or more files ) .IP "\-\-inc" 4 .IX Item "--inc" Generates .inc file ( with declarations to be included in only file ) .IP "\-O" 4 .IX Item "-O" Turns optimizing algorithm for .inc files on. Algorithm is based on an assumption, that some functions are declared identically, therefore the code piece that handles the parameter and result conversion can be shared. With \f(CW\*(C`\-O\*(C'\fR flag on, a thunk body is replaced to a call to a function, which name is made up from all method parameters plus result. Actual function is not written in .inc file, but in .tml file. All duplicate declarations from a set of .tml files can be removed and the reminder written to one file by tmlink utility. .IP "\-\-tml" 4 .IX Item "--tml" Generates .tml file. Turns \f(CW\*(C`\-O\*(C'\fR automatically on. .IP "\-Idirname" 4 .IX Item "-Idirname" Adds a directory to a search path, where the utility searches for \&.cls files. Can be specified several times. .IP "\-\-depend" 4 .IX Item "--depend" Prints out dependencies for a given file. .IP "\-\-sayparent" 4 .IX Item "--sayparent" Prints out the immediate parent of a class inside given file. .SH "SYNTAX" .IX Header "SYNTAX" In short, the syntax of a .cls file can be described by the following scheme: .PP .Vb 2 \& [ zero or more type declarations ] \& [ zero or one class declaration ] .Ve .PP Gencls produces .h, .inc or .tml files, with a base name of the .cls file, if no object or package name given, or with a name of the object or the package otherwise. .SS "Basic scalar data types" .IX Subsection "Basic scalar data types" Gencls has several built-in scalar data types, that it knows how to deal with. To 'deal' means that it can generate a code that transfers data of these types between C and perl, using \s-1XS \s0( see perlguts ) library interface. .PP The types are: .PP .Vb 8 \& int \& Bool \& Handle \& double \& SV* \& HV* \& char * \& string ( C declaration is char[256] ) .Ve .PP There are also some derived built-in types, which are .PP .Vb 5 \& long \& short \& char \& Color \& U8 .Ve .PP that are mapped to int. The data undergo no conversion to int in transfer process, but it is stored instead to perl scalar using \fInewSViv()\fR function, which, in turn, may lose bits or a sign. .SS "Derived data types" .IX Subsection "Derived data types" The syntax for a new data types definition is as follows: .PP .Vb 1 \& .Ve .PP A scope can be one of two pragmas, \f(CW\*(C`global\*(C'\fR or \f(CW\*(C`local\*(C'\fR. They hint the usage of a new data type, whether the type will be used only for one or more objects. Usage of \&\f(CW\*(C`local\*(C'\fR is somewhat resembles C pragma static. Currently the only difference is that a function using a complex local type in the parameter list or as the result is not a subject for \f(CW\*(C`\-O\*(C'\fR optimization. .SS "Scalar types" .IX Subsection "Scalar types" New scalar types may only be aliased to the existing ones, primarily for C coding convenience. A scalar type can be defined in two ways: .IP "Direct aliasing" 4 .IX Item "Direct aliasing" Syntax: .Sp .Vb 1 \& $id => ; .Ve .Sp Example: .Sp .Vb 1 \& global $Handle => int; .Ve .Sp The new type id will not be visible in C files, but the type will be substituted over all .cls files that include this definition. .IP "C macro" 4 .IX Item "C macro" Syntax: .Sp .Vb 1 \& id1 id2 .Ve .Sp Example: .Sp .Vb 1 \& global API_HANDLE UV .Ve .Sp Such code creates a C macro definition in \&.h header file in form .Sp .Vb 1 \& #define id1 id2 .Ve .Sp C macros with parameters are not allowed. id1 and id2 are not required to be present in .cls name space, and no substitution during .cls file processing is made. This pragma usage is very limited. .SS "Complex types" .IX Subsection "Complex types" Complex data types can be arrays, structs and hashes. They can be a combination or a vector of scalar ( but not complex) data types. .PP Gencls allows several combinations of complex data types that C language does not recognize. These will be described below. .PP Complex data types do not get imported into perl code. A perl programmer must conform to the data type used when passing parameters to a function. .IP "Arrays" 4 .IX Item "Arrays" Syntax: .Sp .Vb 1 \& @id [dimension]; .Ve .Sp Example: .Sp .Vb 1 \& global @FillPattern U8[8]; .Ve .Sp Example of functions using arrays: .Sp .Vb 1 \& Array * func( Array a1, Array * a2); .Ve .Sp Perl code: .Sp .Vb 1 \& @ret = func( @array1, @array2); .Ve .Sp Note that array references are not used, and the number of items in all array parameters must be exactly as the dimensions of the arrays. .Sp Note: the following declaration will not compile with C compiler, as C cannot return arrays. However it is not treated as an error by gencls: .Sp .Vb 1 \& Array func(); .Ve .IP "Structs" 4 .IX Item "Structs" Syntax: .Sp .Vb 5 \& @id { \& ; \& ... \& ; \& }; .Ve .Sp Example: .Sp .Vb 4 \& global @Struc { \& int number; \& string id; \& } .Ve .Sp Example of functions using structs: .Sp .Vb 2 \& Struc * func1( Struc a1, Struc * a2); \& Struc func2( Struc a1, Struc * a2); .Ve .Sp Perl code: .Sp .Vb 2 \& @ret = func1( @struc1, @struc2); \& @ret = func2( @struc1, @struc2); .Ve .Sp Note that array references are not used, and both number and order of items in all array parameters must be set exactly as dimensions and order of the structs. Struct field names are not used in perl code as well. .IP "Hashes" 4 .IX Item "Hashes" Syntax: .Sp .Vb 5 \& %id { \& ; \& ... \& ; \& }; .Ve .Sp Example: .Sp .Vb 4 \& global %Hash { \& int number; \& string id; \& } .Ve .Sp Example of functions using hashes: .Sp .Vb 2 \& Hash * func1( Hash a1, Hash * a2); \& Hash func2( Hash a1, Hash * a2); .Ve .Sp Perl code: .Sp .Vb 2 \& %ret = %{func1( \e%hash1, \e%hash2)}; \& %ret = %{func2( \e%hash1, \e%hash2)}; .Ve .Sp Note that only hash references are used and returned. When a hash is passed from perl code it might have some or all fields unset. The C structure is filled and passed to a C function, and the fields that were unset are assigned to a corresponding C_TYPE_UNDEF value, where \s-1TYPE\s0 is one of \s-1NUMERIC, STRING\s0 and \s-1POINTER\s0 literals. .Sp Back conversion does not count on these values and always returns all hash keys with a corresponding pair. .SS "Namespace section" .IX Subsection "Namespace section" Syntax: .PP .Vb 5 \& { \& \& ... \& \& } .Ve .PP A .cls file can have zero or one namespace sections, filled with function descriptions. Functions described here will be exported to the given \s-1ID\s0 during initialization code. A namespace can be either \f(CW\*(C`object\*(C'\fR or \f(CW\*(C`package\*(C'\fR. .PP The package namespace syntax allows only declaration of functions inside a \f(CW\*(C`package\*(C'\fR block. .PP .Vb 4 \& package { \& \& ... \& } .Ve .PP The object namespace syntax includes variables and properties as well as functions ( called methods in the object syntax ). The general object namespace syntax is .PP .Vb 5 \& object [(Parent class ID)] { \& \& \& \& } .Ve .PP Within an object namespace the inheritance syntax can be used: .PP .Vb 1 \& object ( ) { ... } .Ve .PP or a bare root object description ( with no ancestor ) .PP .Vb 1 \& object { ... } .Ve .PP for the object class declaration. .SS "Functions" .IX Subsection "Functions" Syntax: .PP .Vb 1 \& [] () [ => ]; .Ve .PP Examples: .PP .Vb 3 \& int package_func1( int a, int b = 1) => c_func_2; \& Point package_func2( Struc * x, ...); \& method void object_func3( HV * profile); .Ve .PP A prefix is used with object functions ( methods ) only. More on the prefix in Methods section. .PP A function can return nothing ( void ), a scalar ( int, string, etc ) or a complex ( array, hash ) type. It can as well accept scalar and complex parameters, with type conversion that corresponds to the rules described above in \*(L"Basic scalar data types\*(R" section. .PP If a function has parameters and/or result of a type that cannot be converted automatically between C and perl, it gets declared but not exposed to perl namespace. The corresponding warning is issued. It is not possible using gencls syntax to declare a function with custom parameters or result data. For such a purpose the explicit C declaration of code along with \f(CW\*(C`newXS\*(C'\fR call must be made. .PP Example: ellipsis (...) cannot be converted by gencls, however it is a legal C construction. .PP .Vb 1 \& Point package_func2( Struc * x, ...); .Ve .PP The function syntax has several convenience additions: .IP "Default parameter values" 4 .IX Item "Default parameter values" Example: .Sp .Vb 1 \& void func( int a = 15); .Ve .Sp A function declared in such way can be called both with 0 or 1 parameters. If it is called with 0 parameters, an integer value of 15 will be automatically used. The syntax allows default parameters for types int, pointer and string and their scalar aliases. .Sp Default parameters can be as many as possible, but they have to be in the end of the function parameter list. Declaration \f(CW\*(C`func( int a = 1, int b)\*(C'\fR is incorrect. .IP "Aliasing" 4 .IX Item "Aliasing" In the generated C code, a C function has to be called after the parameters have been parsed. Gencls expects a conformant function to be present in C code, with fixed name and parameter list. However, if the task of such function is a wrapper to an identical function published under another name, aliasing can be preformed to save both code and speed. .Sp Example: .Sp .Vb 3 \& package Package { \& void func( int x) => internal; \& } .Ve .Sp A function declared in that way will not call \fIPackage_func()\fR C function, but \fIinternal()\fR function instead. The only request is that \fIinternal()\fR function must have identical parameter and result declaration to a \fIfunc()\fR. .IP "Inline hash" 4 .IX Item "Inline hash" A handy way to call a function with a hash as a parameter from perl was devised. If a function is declared with the last parameter or type \f(CW\*(C`HV*\*(C'\fR, then parameter translation from perl to C is performed as if all the parameters passed were a hash. This hash is passed to a C function and it's content returned then back to perl as a hash again. The hash content can be modified inside the C function. .Sp This declaration is used heavily in constructors, which perl code is typical .Sp .Vb 6 \& sub init \& { \& my %ret = shift\-> SUPER::init( @_); \& ... \& return %ret; \& } .Ve .Sp and C code is usually .Sp .Vb 4 \& void Obj_init ( HV * profile) { \& inherited init( profile); \& ... [ modify profile content ] ... \& } .Ve .SS "Methods" .IX Subsection "Methods" Methods are functions called in a context of an object. Virtually all methods need to have an access to an object they are dealing with. Prima objects are visible in C as Handle data type. Such Handle is actually a pointer to an object instance, which in turn contains a pointer to the object virtual methods table ( \s-1VMT \s0). To facilitate an OO-like syntax, this Handle parameter is almost never mentioned in all methods of an object description in a cls file, although being implicit counted, so every cls method declaration .PP .Vb 1 \& method void a( int x) .Ve .PP for an object class Object is reflected in C as .PP .Vb 1 \& void Object_a( Handle self, int x) .Ve .PP function declaration. Contrary to package functions, that gencls is unable to publish if it is unable to deal with the unsupported on unconvertible parameters, there is a way to issue such a declaration with a method. The primary use for that is the method name gets reserved in the object's \s-1VMT.\s0 .PP Methods are accessible in C code by the direct name dereferencing of a \f(CW\*(C`Handle self\*(C'\fR as a corresponding structure: .PP .Vb 1 \& ((( PSampleObject) self)\-> self)\-> sample_method( self, ...); .Ve .PP A method can have one of six prefixes that govern C code generation: .IP "method" 4 .IX Item "method" This is the first and the most basic method type. It's prefix name, \f(CW\*(C`method\*(C'\fR is therefore was chosen as the most descriptive name. Methods are expected to be coded in C, the object handle is implicit and is not included into a .cls description. .Sp .Vb 1 \& method void a() .Ve .Sp results in .Sp .Vb 1 \& void Object_a( Handle self) .Ve .Sp C declaration. A published method automatically converts its parameters and a result between C and perl. .IP "public" 4 .IX Item "public" When the methods that have parameters and/or result that cannot be automatically converted between C and perl need to be declared, or the function declaration does not fit into C syntax, a \f(CW\*(C`public\*(C'\fR prefix is used. The methods declared with \f(CW\*(C`public\*(C'\fR is expected to communicate with perl by means of \s-1XS \s0( see perlxs ) interface. It is also expected that a \f(CW\*(C`public\*(C'\fR method creates both \&\s-1REDEFINED\s0 and \s-1FROMPERL\s0 functions ( see Prima::internals for details). Examples are many throughout Prima source, and will not be shown here. \f(CW\*(C`public\*(C'\fR methods usually have void result and no parameters, but that does not matter much, since gencls produces no conversion for such methods. .IP "import" 4 .IX Item "import" For the methods that are unreasonable to code in C but in perl instead, gencls can be told to produce the corresponding wrappers using \f(CW\*(C`import\*(C'\fR prefix. This kind of a method can be seen as \f(CW\*(C`method\*(C'\fR inside-out. \f(CW\*(C`import\*(C'\fR function does not need a C counterpart, except the auto-generated code. .IP "static" 4 .IX Item "static" If a method has to be able to work both with and without an object instance, it needs to be prepended with \f(CW\*(C`static\*(C'\fR prefix. \&\f(CW\*(C`static\*(C'\fR methods are all alike \f(CW\*(C`method\*(C'\fR ones, except that \&\f(CW\*(C`Handle self\*(C'\fR first parameter is not implicitly declared. If a \f(CW\*(C`static\*(C'\fR method is called without an object ( but with a class ), like .Sp .Vb 1 \& Class::Object\-> static_method(); .Ve .Sp its first parameter is not a object but a \*(L"Class::Object\*(R" string. If a method never deals with an object, it is enough to use its declaration as .Sp .Vb 1 \& static a( char * className = ""); .Ve .Sp but is if does, a .Sp .Vb 1 \& static a( SV * class_or_object = nil); .Ve .Sp declaration is needed. In latter case C code itself has to determine what exactly has been passed, if ever. Note the default parameter here: a \f(CW\*(C`static\*(C'\fR method is usually legible to call as .Sp .Vb 1 \& Class::Object::static_method(); .Ve .Sp where no parameters are passed to it. Without the default parameter such a call generates an 'insufficient parameters passed' runtime error. .IP "weird" 4 .IX Item "weird" We couldn't find a better name for it. \f(CW\*(C`weird\*(C'\fR prefix denotes a method that combined properties both from \f(CW\*(C`static\*(C'\fR and \f(CW\*(C`public\*(C'\fR. In other words, gencls generates no conversion code and expects no \f(CW\*(C`Handle self\*(C'\fR as a first parameter for such a method. As an example Prima::Image::load can be depicted, which can be called using a wide spectrum of calling semantics ( see Prima::image\-load for details). .IP "c_only" 4 .IX Item "c_only" As its name states, \f(CW\*(C`c_only\*(C'\fR is a method that is present on a \s-1VMT\s0 but is not accessible from perl. It can be overloaded from C only. Moreover, it is allowed to register a perl function with a name of a \f(CW\*(C`c_only\*(C'\fR method, and still these entities will be wholly independent from each other \- the overloading will not take place. .Sp \&\s-1NB:\s0 methods that have result and/or parameters data types that can not be converted automatically, change their prefix to \f(CW\*(C`c_only\*(C'\fR. Probably this is the wrong behavior, and such condition have to signal an error. .SS "Properties" .IX Subsection "Properties" Prima toolkit introduces an entity named property, that is expected to replace method pairs whose function is to acquire and assign some internal object variable, for example, an object name, color etc. Instead of having pair of methods like Object::set_color and Object::get_color, a property Object::color is devised. A property is a method with the special considerations, in particular, when it is called without parameters, a 'get' mode is implied. In contrary, if it is called with one parameter, a 'set' mode is triggered. Note that on both 'set' and 'get' invocations \f(CW\*(C`Handle self\*(C'\fR first implicit parameter is always present. .PP Properties can operate with different, but fixed amount of parameters, and perform a 'set' and 'get' functions only for one. By default the only parameter is the implicit \&\f(CW\*(C`Handle self\*(C'\fR: .PP .Vb 1 \& property char * name .Ve .PP has C counterpart .PP .Vb 1 \& char * Object_name( Handle self, Bool set, char * name) .Ve .PP Depending on a mode, \f(CW\*(C`Bool set\*(C'\fR is either \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR. In 'set' mode a C code result is discarded, in 'get' mode the parameter value is undefined. .PP The syntax for multi-parameter property is .PP .Vb 1 \& property long pixel( int x, int y); .Ve .PP and C code .PP .Vb 1 \& long Object_pixel( Handle self, Bool set, int x, int y, long pixel) .Ve .PP Note that in the multi-parameter case the parameters declared after property name are always initialized, in both 'set' and 'get' modes. .SS "Instance variables" .IX Subsection "Instance variables" Every object is characterized by its unique internal state. Gencls syntax allows a variable declaration, for variables that are allocated for every object instance. Although data type validation is not performed for variables, and their declarations just get copied 'as is', complex C declarations involving array, struct and function pointers are not recognized. As a workaround, pointers to typedef'd entities are used. Example: .PP .Vb 5 \& object SampleObject { \& int x; \& List list; \& struct { int x } s; # illegal declaration \& } .Ve .PP Variables are accessible in C code by direct name dereferencing of a \f(CW\*(C`Handle self\*(C'\fR as a corresponding structure: .PP .Vb 1 \& (( PSampleObject) self)\-> x; .Ve .SH "AUTHORS" .IX Header "AUTHORS" Dmitry Karasik, . Anton Berezin, . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima::internals, tmlink .SH "COPYRIGHT" .IX Header "COPYRIGHT" This program is distributed under the \s-1BSD\s0 License.