user_guide:extend:cpp_type_binding

This is an old revision of the document!


Property Type Bindings to C++ Classes

This page contains the complete list of attributes of property type declarations controlling the details of the interplay between the property type being visible on the perl side and the hidden C++ class.

Glue code generation

name => "class_name"

Specifies the name of the C++ class. The class_name must be a valid C++ type expression, fully qualified with namespace names if needed. As an exception, the namespace polymake (for types from the Polymake Template Library) and the namespace of the current application polymake::APPNAME can be omitted.

If this attribute is omitted, the C++ class name is supposed to be identical to the name of the property type being defined and to be defined in the polymake namespace.

If the property type is defined as a parameterized type, the corresponding C++ type is supposed to a class template as well, having a congruent list of type parameters.

name => "class_name<type, ...>"

Specifies the C++ type expression involving class templates, with the number or order of type parameters not exactly matching the property type definition. type can be either a constant type expression or a placeholder %N referring to the parameters of the property type, with N starting with 1.

name => \&sub

Specifies a subroutine synthesizing the C++ type expression. This form is used in especially complicated cases of parameterized type mapping. The subroutine is called with a list of C++ type names corresponding to the type parameters of the concrete instance; if the subroutine is declared as method, it will also get the property type descriptor as a leading argument.

builtin => "type_name"

Tells that the values of this property type are kept as plain perl entities (numbers, strings, anonymous references, …) without C++ objects lurking in the magic storage, but when such a value is passed to a C++ function, the glue code must be generated as to accept the specified C++ type. There is a very limited list of property types declared with this attribute, all of them residing in apps/common/rules/basic_types.

builtin => enum { name, ... }

Introduces an enumeration type and named constants.

builtin => \&sub

Specifies a subroutine deciding for the given instance of a parameterized property type whether the values should be stored as plain perl entities or as C++ objects in the magic storage. The subroutine is called at the first occurrence of a concrete instance with the property type descriptor as a single argument.

special => "class_name"

Tells that this property type is of limited use and should not be equipped with constructors, overloaded operators, and other comforts. This attribute is used, for example, for pure type tags like Undirected or Symmetric.

include => [ "header_file", ... ]

Lists the header files to be included into the auto-generated glue code. For built-in types like int this list can be empty, otherwise it should contain at least the header file where the C++ class is defined. Further headers may be added automatically to the glue code for class templates depending on the parameters occurring in concrete instantiations.

Method generation

default_constructor => 0

Suppresses automatic creation of standard constructors. Usually, all property types not declared with builtin or special attributes are automatically equipped with the following standard constructors:

  • default constructor: new Type()
  • parsing constructor: new Type("printable representation")
  • bulk constructor for containers: new Type([ value, … ])
  • structure constructor for composite types: new Type(init1, init2, …)

If the C++ class bound to it does not support the corresponding operation, for example, it is lacking the default constructor or the input operator >>, you should suppress the standard constructors and provide appropriate specializations of method construct in the type definition scope.

fields => [ "name", ... ]

For a composite type, creates methods with given names accessing the members (aka fields of a structure). The order of the names must correspond to the order of type declarations in the specialization of pm::spec_object_traits<Type>::elements .

operators => "overloaded operators"

Defines overloaded operators and primitive functions for the property type as C++ function wrappers. The string value of this attribute is a white-space separated list of tokens of the following form:

op_symbol

A lone symbol of an operation like +, *=, bool, or "" (cf. the perl documentation `man overload` for the complete list) means that the corresponding operator is overloaded for the C++ class as well. The generated glue code will just contain the same operation symbol. Conversion to a boolean value is implemented via an explicit cast, conversion to a string via standard stream output operator << .

op_symbol:modifier

Modifies the argument passing to the operator. wary and int are allowed here.

@group
@group:modifier

A shortcut for a group of related operators. The groups are defined in the list %op_groups in the core perl module CPlusPlus.pm, the most important are @arith with four arithmetic operations and @compare with all possible comparison operations. Modifier, if any, applies to all operations in the group.

op_symbol( function header )

Maps the operator to a C++ function with given name and signature. Trailing attributes method, wary, lvalue can be specified if the function is implemented as a method of the C++ class.

  • user_guide/extend/cpp_type_binding.1333186022.txt.gz
  • Last modified: 2014/01/03 15:45
  • (external edit)