| Both sides previous revision Previous revision Next revision | Previous revision |
| reference:polymorphic [2018/09/08 22:26] – [Labels] gawrilow | user_guide:extend:polymorphic [2021/01/12 15:46] (current) – [Labels] gawrilow |
|---|
| |
| ===== Signature ===== | ===== Signature ===== |
| The signature describes the number and types of arguments expected by an overloaded instance, as well as default values for optional arguments. The syntax of the most primitive elements is borrowed from the standard perl //function prototypes//, enriched with further elements for [[reference:rulefiles#type_definitions|property types]] and "big" object types, [[reference:rulefiles#fuctions|option lists]] and other keyword arguments, etc. The "standard" elements are encoded with one-symbol codes, they can be written in traditional style glued together, or in a more legible style with commas and white spaces in between. Advanced elements must be separated with commas. | The signature describes the number and types of arguments expected by an overloaded instance, as well as default values for optional arguments. The syntax of the most primitive elements is borrowed from the standard perl //function prototypes//, enriched with further elements for [[user_guide:extend:rulefiles#type_definitions|property types]] and "big" object types, [[user_guide:extend:rulefiles#fuctions|option lists]] and other keyword arguments, etc. The "standard" elements are encoded with one-symbol codes, they can be written in traditional style glued together, or in a more legible style with commas and white spaces in between. Advanced elements must be separated with commas. |
| |
| Signatures of pure perl functions and wrapped C++ functions share many common elements, but also have few differences. Unless mentioned explicitly, the elements described below may be used in both cases. C++ functions are recognized by the ''c++'' [[#attributes|attribute]]. | Signatures of pure perl functions and wrapped C++ functions share many common elements, but also have few differences. Unless mentioned explicitly, the elements described below may be used in both cases. C++ functions are recognized by the ''c++'' [[#attributes|attribute]]. |
| |
| ==== Typechecks ==== | ==== Typechecks ==== |
| A type checking clause may be specified for functions with type parameters. It can contain an expression performing arbitrary checks on the deduced or explicitly given type parameters, e.g. by calling a [[reference:rulefiles#typechecks|type checking function]]. Default values for type parameters, if applicable, are assigned prior to evaluation of the type checking expression. The expression should return a boolean value signaling success or failure; it must not raise exceptions. In the successful case, the function body is executed; otherwise, the function is discarded from candidates and the overload resolution continues. | A type checking clause may be specified for functions with type parameters. It can contain an expression performing arbitrary checks on the deduced or explicitly given type parameters, e.g. by calling a [[user_guide:extend:rulefiles#typechecks|type checking function]]. Default values for type parameters, if applicable, are assigned prior to evaluation of the type checking expression. The expression should return a boolean value signaling success or failure; it must not raise exceptions. In the successful case, the function body is executed; otherwise, the function is discarded from candidates and the overload resolution continues. |
| |
| Besides performing pure checks, the type checking clause may upgrade the deduced parameter values by calling a meta-function ''type_upgrade<''T'','' other type''>''. This meta-function upgrades T to //other type// if it is allowed by upgrade relations and T has not been explicitly specified by the caller. Even if the upgrade is not possible, this function succeeds and simply returns the unchanged type of T. | Besides performing pure checks, the type checking clause may upgrade the deduced parameter values by calling a meta-function ''type_upgrade<''T'','' other type''>''. This meta-function upgrades T to //other type// if it is allowed by upgrade relations and T has not been explicitly specified by the caller. Even if the upgrade is not possible, this function succeeds and simply returns the unchanged type of T. |
| :: 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. |
| |
| ===== Labels ===== | ===== Labels ===== |
| 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. | 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 [[:user_guide:howto:shell_custom#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. |
| |
| 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//%%...);%%'' | 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//%%...);%%'' |
| |
| 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. | 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. |
| | |