On Tue, Feb 17, 2015 at 7:06 AM, Dmitri Zimine <dzim...@stackstorm.com> wrote:
> 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]): > A really long time ago I posted this patch for Heat: https://review.openstack.org/#/c/41858/2/doc/source/template_guide/functions.rst (adds a jinja2 function to Heat http://jinja.pocoo.org/docs/dev/) I also used <% %>, it seems to be what people use when using jinja2 on yaml. This was rejected because of security concerns of Jinja2. > > 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” } > You *could* have the expression as a list, like this (but might not work in all cases): { yaql: [1, +, 1, $.my.var, <, 100] } Generally in Heat we make the functions and args a natural part of the yaml so it's not one big string that gets parsed separately. Tho' it would be nice to have a common approach to this, so I am partial to the one you have here. -Angus > > 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev