SUMMARY:
----------------
We are changing the syntax for inlining YAQL expressions in Mistral YAML from
{1+$.my.var} (or “{1+$.my.var}”) to <% 1+$.my.var %>
Below I explain the rationale and the criteria for the choice. Comments and
suggestions welcome.
DETAILS:
-------------
We faced a number of problems with using YAQL expressions in Mistral DSL: [1]
must handle any YAQL, not only the ones started with $; [2] must preserve types
and [3] must comply with YAML. We fixed these problems by applying Ansible
style syntax, requiring quotes around delimiters (e.g. “{1+$.my.yaql.var}”).
However, it lead to unbearable confusion in DSL readability, in regards to
types:
publish:
intvalue1: "{1+1}” # Confusing: you expect quotes to be string.
intvalue2: "{int(1+1)}” # Even this doestn’ clean the confusion
whatisthis:"{$.x + $.y}” # What type would this return?
We got a very strong push back from users in the filed on this syntax.
The crux of the problem is using { } as delimiters YAML. It is plain wrong to
use the reserved character. The clean solution is to find a delimiter that
won’t conflict with YAML.
Criteria for selecting best alternative are:
1) Consistently applies to to all cases of using YAML in DSL
2) Complies with YAML
3) Familiar to target user audience - openstack and devops
We prefer using two-char delimiters to avoid requiring extra escaping within
the expressions.
The current winner is <% %>. It fits YAML well. It is familiar to
openstack/devops as this is used for embedding Ruby expressions in Puppet and
Chef (for instance, [4]). It plays relatively well across all cases of using
expressions in Mistral (see examples in [5]):
ALTERNATIVES considered:
--------------------------------------------------
1) Use Ansible-like syntax: http://docs.ansible.com/YAMLSyntax.html#gotchas
Rejected for confusion around types. See above.
2) Use functions, like Heat HOT or TOSCA:
HOT templates and TOSCA doesn’t seem to have a concept of typed variables to
borrow from (please correct me if I missed it). But they have functions:
function: { function_name: {foo: [parameter1, parameter 2], bar:"xxx”}}.
Applied to Mistral, it would look like:
publish:
- bool_var: { yaql: “1+1+$.my.var < 100” }
Not bad, but currently rejected as it reads worse than delimiter-based syntax,
especially in simplified one-line action invocation.
3) < > paired with other symbols: php-styoe <? ..?>
REFERENCES:
----------------------
[1] Allow arbitrary YAQL expressions, not just ones started with $ :
https://github.com/stackforge/mistral/commit/5c10fb4b773cd60d81ed93aec33345c0bf8f58fd
[2] Use Ansible-like syntax to make YAQL expressions YAML complient
https://github.com/stackforge/mistral/commit/d9517333b1fc9697d4847df33d3b774f881a111b
[3] Preserving types in YAQL
https://github.com/stackforge/mistral/blob/d9517333b1fc9697d4847df33d3b774f881a111b/mistral/tests/unit/test_expressions.py#L152-L184
[4]Using <% %> in Puppet
https://docs.puppetlabs.com/guides/templating.html#erb-is-plain-text-with-embedded-ruby
[5] Etherpad with discussion
https://etherpad.openstack.org/p/mistral-YAQL-delimiters
[6] Blueprint https://blueprints.launchpad.net/mistral/+spec/yaql-delimiters
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
