| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| reference:polymorphic [2018/09/08 22:02] – [Definition elements] gawrilow | user_guide:extend:polymorphic [2019/01/25 16:02] – ↷ Page moved from reference:polymorphic to user_guide:extend:polymorphic oroehrig |
|---|
| ====== Polymorphic Functions ====== | ====== Polymorphic Functions ====== |
| |
| In the rulefiles you can define polymorphic functions and methods resembling, to some extent, the features of programming languages C++ or Java. The general syntax is described [[rulefiles#functions|among other rulefile elements]], here we discuss the definition and overload resolution in deeper details. | In the rulefiles you can define polymorphic functions and methods resembling, to some extent, the features of programming languages C++ or Java. The general syntax is described [[reference:rulefiles#functions|among other rulefile elements]], here we discuss the definition and overload resolution in deeper details. |
| |
| ===== Definition elements ===== | ===== Definition elements ===== |
| category label '':'' name ''<'' type parameters > ''['' typecheck ''] ('' signature '') : '' attributes | category label '':'' name ''<'' type parameters > ''['' typecheck ''] ('' signature '') : '' attributes |
| |
| //category// can be ''method'', ''function'', etc., as described in the [[rulefiles#functions|general syntax rules]]. | //category// can be ''method'', ''function'', etc., as described in the [[reference:rulefiles#functions|general syntax rules]]. |
| |
| Name and signature are mandatory, while label, type parameters, and attributes are optional. | Name and signature are mandatory, while label, type parameters, and attributes are optional. |
| :: Denotes arbitrarily many (trailing) arguments of any types. This element must be the last one among all arguments in the signature. This is only allowed with functions implemented in perl. For C++ functions, an appropriate container type (Array, Vector, etc.) must be used. | :: Denotes arbitrarily many (trailing) arguments of any types. This element must be the last one among all arguments in the signature. This is only allowed with functions implemented in perl. For C++ functions, an appropriate container type (Array, Vector, etc.) must be used. |
| ? ''%''option_list | ? ''%''option_list |
| :: Refers to an [[rulefiles#functions|option list]] defined in the rulefiles before. Trailing argument pairs of the form ''%%keyword => value%%'' with keywords matching the keys of the option list are collected together in an anonymous hash map, which is passed to the function body by reference. | :: Refers to an [[reference:rulefiles#functions|option list]] defined in the rulefiles before. Trailing argument pairs of the form ''%%keyword => value%%'' with keywords matching the keys of the option list are collected together in an anonymous hash map, which is passed to the function body by reference. |
| .. A signature may contain more than one option list reference. The arguments passed to the function are reorganized to match the keys of each option list; each anonymous hash map is then passed to the function body per separate reference. If the option lists share some keys, the keyword arguments matching several lists are copied in all corresponding hash maps. | .. A signature may contain more than one option list reference. The arguments passed to the function are reorganized to match the keys of each option list; each anonymous hash map is then passed to the function body per separate reference. If the option lists share some keys, the keyword arguments matching several lists are copied in all corresponding hash maps. |
| .. If the argument list already contains a reference to a hash map at the position where keyword-value pairs are expected, this reference is passed unchanged and unchecked to the function body; this allows to gradually define families of polymorphic functions delegating work to each other without expensive re-checking and reordering of keyword arguments. | .. If the argument list already contains a reference to a hash map at the position where keyword-value pairs are expected, this reference is passed unchanged and unchecked to the function body; this allows to gradually define families of polymorphic functions delegating work to each other without expensive re-checking and reordering of keyword arguments. |
| :: Tells that the function returns an object which can be modified by assigning a value to it. Primarily used with methods giving access to elements of some data container like a matrix or vector. | :: Tells that the function returns an object which can be modified by assigning a value to it. Primarily used with methods giving access to elements of some data container like a matrix or vector. |
| ? ''returns('' type '')'' | ? ''returns('' type '')'' |
| :: Tells that the function returns an object of the given type. Usually the return value is automatically recognized by the auto-generated wrapper and hooked under an appropriately "blessed" perl reference. This attribute should only be used in special cases where the automatic recognition does not work or must be overridden. In particular, this attribute must be used with [[reference:cpp_type_binding#abstract_property_types|abstract property types]]. | :: Tells that the function returns an object of the given type. Usually the return value is automatically recognized by the auto-generated wrapper and hooked under an appropriately "blessed" perl reference. This attribute should only be used in special cases where the automatic recognition does not work or must be overridden. In particular, this attribute must be used with [[user_guide:extend:cpp_type_binding#abstract_property_types|abstract property types]]. |
| ? ''returns(@)'' | ? ''returns(@)'' |
| :: Tells that the function returns several values in a list context. As usual in perl, when called in scalar context, the //last// value from the list will be taken for further processing. | :: Tells that the function returns several values in a list context. As usual in perl, when called in scalar context, the //last// value from the list will be taken for further processing. |
| |
| ===== Hybrid functions ===== | ===== Hybrid functions ===== |
| Usually a function is either implemented in pure (polymake dialect of) perl or wrapped from the C++ side. In the first case the instance body with the code is directly following the header, like in a standard perl subroutine, in the second case the list of [[#attributes|attributes]] is concluded by a semicolon. | Usually a function is either implemented in pure (polymake dialect of) perl or in pure C++. In the first case the instance body with the code is directly following the header, like in a standard perl subroutine, in the second case the list of [[#attributes|attributes]] is concluded by a semicolon. |
| |
| Sometimes you might find more convenient to combine some preliminary checks or preparations on argument values with a proper call into C++ function, or even skip the latter call under certain circumstances. Although such scenarios can surely be modeled by defining two functions, outer one written in perl, and the inner one as wrapped C++ function, this also can be written more compactly (and more efficiently) as a hybrid function. Such a function has both the ''c++'' attribute //and// a body with perl code. The perl body is called first; if it returns any value with an explicit ''return'' statement or raises an exception, the C++ function is not called at all; if the perl body runs to the end without executing any ''return''s, the control is passed to the wrapped C++ function. | Sometimes you might find more convenient to combine some preliminary checks or preparations on argument values with a proper call into C++ function, or even skip the latter call under certain circumstances. Although such scenarios can surely be modeled by defining two functions, outer one written in perl, and the inner one as a wrapped C++ function, this also can be written more succinctly (and more efficiently) as a hybrid function. Such a function has both the ''c++'' attribute //and// a body with perl code. The perl body is executed first; if it returns any value with an explicit ''return'' statement or raises an exception, the C++ function is not called at all; if the perl body runs to the end without executing any ''return''s, the control is passed to the wrapped C++ function. |
| |
| Usually a hybrid function looks like this: | Usually a hybrid function looks like this: |
| |
| ===== Labels ===== | ===== Labels ===== |
| Labels allow to differentiate between several overloaded instances with identical signatures. Without labels, occurrence of functions with compatible signatures would inevitably give rise to a fatal error. (Recall that two signatures are //compatible// if they would match the same argument list shortened by all optional arguments). With labels, the instances with compatible signatures are bundled together in lists, which are consulted at the end of the overload resolution. The actual function body to be executed is taken from the head of the candidate list. If one of the labels is made preferred by executing a command ''prefer'' or ''prefer_now'', the corresponding instance is moved to the head of the list. Otherwise the order of the instances is more or less random, thus it is unpredictable which instance is called in absence of any active preferences. | Labels allow to provide several alternative implementations for the same function or for a family of functions with compatible signatures. The choice of the function to be called is governed by active preference lists (cf. user commands [[:general#preferences|prefer, prefer_now, show_preferences]]). First, all candidates with the label of the highest rank are considered according to usual overload resolution rules. If none has matched the argument list, the candidates with the label of the next lower rank are considered, and so on. |
| |
| The application can also obtain the complete candidate list, ordered according to currently active preferences, by executing ''%%$list=Overload::resolve_labeled("%%//PACKAGE//%%", "%%//NAME//%%", %%//args//%%);%%'' The package name to search within can be replaced with a special token ''%%__PACKAGE__%%'' designating the current package. | Labels are mandatory for //global methods//. The overload resolution for global methods runs slightly differently from other functions. The application first calls ''$method=Overload::Global:://NAME//(//args//%%...%%)'' to obtain the code reference pointing to the currently preferred method matching the given list of arguments. Then it creates an object of the corresponding class using something like ''%%$object=method_owner($method)->new(...);%%'' or retrieves a suitable object in whatever appropriate way, and finally calls the method, passing the obtained object as a leading argument: ''%%$method->($object, %%//args//%%...);%%'' |
| | |
| While assigning labels to functions is optional, for one category of polymorphic functions labels are mandatory, namely for //global methods//. The overload resolution for global methods runs slightly differently from the normal methods. The application code first calls ''$method=Overload::Global:://NAME//(//args//)'' to obtain the code reference pointing to the currently preferred method matching the given list of arguments. Then it creates an object of the corresponding class using something like ''%%$object=method_owner($method)->new(...);%%'' or retrieves a suitable object in whatever appropriate way, and finally calls the method, passing the obtained object as a leading argument: ''%%$method->($object, %%//args//%%);%%'' | |
| | |
| Note that the method selected in the first step is looked for in //all// packages defining global method instances with the given name. | |
| |
| | Alternatively, the application can request the full list of candidate methods from ''Overload::resolve_global(//NAME//, [ //args//%%...%% ])'' , the argument list must be passed by reference. The result will be a reference to a list of method references, ordered according to the current label ranking. |