-
Notifications
You must be signed in to change notification settings - Fork 25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
TOSCA 2.0 custom function usage and definition #123
Comments
Custom function definition syntax and semantics: Specification of the functions is a YAML map under the functions keyname:
Specification of a <function_def> is a list of signature definitions for each function name:
Each <signature_def> is a map of following keywords definitions (where only the result is mandatory):
|
Examples
The next sqrt is similar to above, but uses a simplified type notation (no constraints check can be expressed):
Same as the above, but in compact notation:
Polymorphism allows a function to accept parameters and return results of different kinds:
Defining a list in a map parameter:
|
I'm not in favor of adding this complex DSL for declaring function signatures. I'd prefer that we leave function validation up to the implementation. This proposal limits the usability of custom functions. Indeed, some built-in functions can't be expressed by this DSL, specifically So, if the implementation gets a bad parameter, it should emit an error. Also, if the return value does not match the type and constraints of its value site, there should also be an error. The advantages of checking types in design-time is small and limited: the values are often just as important as the types, and these cannot always be validated by TOSCA constrained (e.g. the ID for an external object). Validation happens in the way the TOSCA processor will implement these connected functions. This extra layer of syntactical validation is overly complex, limited in scope, and has limited benefits. Note that most dynamic programming languages do not require function signatures. Assuming others insist on having this complex DSL, I would insist that we make it entirely optional. So, if a function is used without a declared signature it will not be validated by parsers. Call it a "signature-less" function if you will. Since we are requiring the Also, a fix for the initial post. I think the proposed syntax is imprecise. Here's my proposal: For TOSCA values, for any YAML map at any nested depth, the following parsing rules apply to its keys:
Note that these rules do not apply to string values that are not map keys. Thus there is no need to escape a properties:
prop1: $myid # valid as is, no need to escape
prop2: my_value But here we do need to escape: properties:
$$prop1: myid # if we don't escape we will get a "malformed function" syntax error
prop2: my_value |
|
"Certainty" is a very big word. :) Note that we have not established (and I don't think we should) the mechanism for calling that "implementation" artifact, whatever it is (is it a TOSCA artifact?). Khutulun, for example, uses gRPC for all delegates/plugins. At best you have certainty that other parsers would just check parameter and return types (without constraints). And also I fail to see how this complex signature DSL really helps Ericsson. I think all you need here is a map connecting function names to the implementation "artifacts". When the implementation is called the function will be fully validated, including actual values (and not just types) with constraints. This proposed DSL adds a lot of complexity for not much tangible benefits in my view -- some limited Day 0 syntax validation for a subset of functions.
Maybe "dynamic"? That's what it's called in programming languages.
"dynamic" functions should also have an unknown-typed return value. That's probably the more important differentiator.
Of course. But we already such dynamic functions in TOSCA, actually the most important functions:
This might be our disconnect. You are thinking of functions like Though even many textual functions are "dynamic". For example, a |
In this definition of custom functions I was meaning only the
Agree, this was the idea with the |
See discussion in issue #68 |
How do we deal with optional parameters in custom function definitions? Let's use the current functions:
get_artifact:
- parameters:
- type: string
- type: string
- parameters:
- type: string
- type: string
- type: string
- parameters:
- type: string
- type: string
- type: string
- type: boolean That seems a bit cumbersome. Could we instead add support for the functions:
get_artifact:
- parameters:
- type: string
- type: string
- type: string
required: False
- type: boolean
required: False The validator would of course have to make sure that no |
Even when a function defines multiple signatures, I find that in most cases I want to use the same |
We currently support |
Regarding the optional parameters for a function part, all parameters after the first optional parameter must be optional, and if optional parameter on position x is used, then all the optional parameters on positions before x must be be used too (exactly like in the multi signature I propose to use one signature-level parameter functions:
get_artifact:
- parameters: [string, string, string, boolean]
optional_from: 2
unbounded: false
result: string
implementation: scripts/get_artifact.py |
Regarding the implementation, I think it's useful to have the possibility to give it also per signature, i.e. don't want to touch the implementation later, but extend the signature. Several signatures can still share the same artifact in the implementation specification. Allowing the description, metadata, and implementation on the function level, then we would need to gather all the signatures under a keyname: e.g. get_artifact:
signatures:
- parameters: [string, string, string, boolean]
optional_from: 2
unbounded: false
result: string
implementation: scripts/get_artifact.py
description: "function level description" |
The proposed function definition syntax has been approved and is documented in https://docs.oasis-open.org/tosca/TOSCA/v2.0/csd05/TOSCA-v2.0-csd05.html#_Toc125468802. Issue #140 has been created to track discussions about |
Custom function usage syntax and semantics:
$function_a1: [arg1, arg2, …]
$function_a2: []
$function_a3: [{$func_a1: […]}, arg2, …]
properties:
prop1: $$myid
prop2: my_value
The text was updated successfully, but these errors were encountered: