-
Notifications
You must be signed in to change notification settings - Fork 742
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
Decorator syntax #64
Comments
Have we decided to go with decorators? Anders still seems hesitant on it. |
Anders is hesitant, but accepts that it may be the least bad option :) The other place we have a modifier-like syntax would be parameters. Putting a couple examples here for reference:
alternative with less @'s
|
I like the idea of decorator block to avoid too many @. Maybe support both syntax? |
Yup, I like the multi-decorator syntax too. There's also an interesting argument for combining some of the constraints into a single decorator like We might need a restriction on complex values in decorators (objects/arrays) with all the syntaxes above. Otherwise, we'll be in curly brace hell again. |
good point - allowedValues will be a challenge I think...
|
FWIW you don't need commas between multiple decorators (assuming they are called with parens). Perhaps a pipe dream but it would be great if users could compose a |
@alex-frankel Yeah good pt. @bterlson Are you thinking the comma-less group would be in that block syntax above or like this? Composing user-defined decorators could definitely be interesting once there are more opportunities for decorating things. Currently agreed upon syntax limits what you could do with them (tweak a loop, tweak a parameter and that's basically it), but I suspect the list where they fit will grow. |
Interesting - it feels like we should flag a single allowedValue as an error or warning since it should just be a variable or hardcoded value at that point, right? |
Sorry my statement was ambiguous. I meant that in an array of allowed values, a single array item can be an object. (Or another array. Or anything really.) The type checking we will do here will check that |
Ah, gotcha. I agree with the logic that it should not be an error, and I can see why we may want to hold off from the warning as well. I've also seen text in a darker/faded out color for things like "unused" params and variables, maybe that would be better. |
More supporting evidence to making this change: #293 |
FYI, the easiest way to do that in vscode is to add the vscode.DiagnosticTag.Unnecessary tag to the warning diagnostic, but if you don't want to add warnings, you could also do it via a text decorator. I'd also suggest you use tslint's model for disabling warnings. |
Another potential use-case - semantic documentation which can show up on hovers would be pretty neat (especially when working with modules) - e.g. something like the following if you just pretend my comments are actually useful: @doc 'The prefix to use for the diagnostics storage account'
param diagsAccountPrefix string
@doc 'The diagnostics storage account name'
var diagsAccountName = '${diagsAccountPrefix}${uniqueString(resourceGroup().id)}'
@doc 'The diagnostics storage account'
resource diagsAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: diagsAccountName
...
} |
Yeah, being able to add descriptions and other text that shows up in hovers would be amazing. |
Our team had a discussion and we decided to implement the multi-line decorator syntax for 0.3:
Once we make our language less new line sensitive (#146), we'll need to revise the syntax for putting multiple decorators on the same line. The @doc decorator for semantic documentation is definitely something we would like to have as well, but it's a separate feature which will come after the 0.3 release. |
@alex-frankel I liked the multi line syntax. It's readable, close to decorators concept in c#, so it will be natural to developers. |
@lr90 are you referring to referencing a keyvault secret? This decorator syntax is for the definition of a parameter, not for providing the value of it. So you will still need to reference using the parameters file. Separately, there is a gap for referencing secrets that we will take care of with #1028 (comment) I think the |
Yes I was, taken a look a #1028 and understand now. Thanks |
I also like the multi-line syntax. Seems like a good breaking change to include. |
Alex - I'd love the Array syntax to be more "standard" with commas and declarable on one line.
and
Even w/o the commas, this would help readability:
|
We are planning to make a change to make the language more newline agnostic that will unblock single-line arrays for example. Although we haven't closed yet on the separator character. |
@ChristopherGLewis - support for single line arrays is tracked with #586 and there is lots of discussion on commas vs no commas in #498 |
Personally I would have preferred to go with one of the options that allows for multiple distinct decorators on a single line (at least as an option). Bicep is all about trying to reduce the amount of boilerplate and extra yak-shaving, and it seems more elegant to me to be able to put a bunch of metadata all together than to have to have multiple lines to do it. However I'm OK with the multiline syntax as an option, and maybe as an initial step before a single-line alternative is available. |
I’ve been looking at this for a while and still can’t get use to having "decorators" prior to the thing they are decorating in a declarative language… I think the reason is that the decoration needs context, i.e. what is it decorating? Until I know that, it’s distracting from the common scenario of understanding the thing at it's most basic level. The first thing I want to know, looking at a declarative syntax, is what is being declared – only after that do the properties describing of it have complete meaning. The I wonder if one thing that may be driving our thinking is that we're calling them "decorators", which has meaning from prior art, when in practice I think they are just optional (or non-defaulted) properties of the thing being declared. IOW, the So I'm trying this:
And part of my thinking goes to a more declarative syntax for looping, e.g.
I think the above is similar to what @lwang2016 mentioned - some variation a block… And now @johndowns I have to go try to get the image of yak shaving out of my head. |
OK we discussed this today, and I think this is the last time we are going to ask for feedback on this one. Basically, we're still thinking that decorators will go above the
This also makes folding all of the decorators in vs code easy.
Presumably, when we have support for single-line objects (#586) you could also have:
Thoughts? If you made it this far, we are also not sure which character we should use after the
|
FWIW I too often like having decorators on the same line for short, e.g. zero-arg decorators like
|
Alex - I like the way this is going, but have a couple of suggestions. When I'm doing powershell parameters, I always start with the parameter: [string] $Param Then as I clean up my code, I add the validators etc. [ValidateSet(“Tom”,”Dick”,”Harriet”)]
[string] $Param With the Bicep tooling, it would be great to be able to do the same, starting with the parameter param name string = 'defaultName' Then as you make the code better, going to the line above and pressing the @ key would populate the possible decorators based of the parameter type. For Int you would be offered min/max, for string you would get minLength/maxLength (among other possibilities). |
I'd go with square |
We discussed this again with Anders, and he prefers the current multiline |
Overview
ARM copy loops support a mode (serial or parallel) as well as a batchSize parameter to control how looping is done. We seem to have agreement that we should use decorators to express a modification of the loop behavior, but we have not formally agreed on the syntax for them.
Decorators are coming up in other places as well (parameters and outputs), but I put those areas of the language aside in this proposal.
Mode
Option 1
We can set serial mode on a resource loop as follows:
Parallel mode is the default, but it could be optionally expressed using
@parallel
instead of@serial
in the example above.Option 2
Instead of two different decorators, we could use one
@mode
decorators like these:@mode('serial')
@mode('parallel')
Batch size
Similar to loop mode, batch size could be expressed with something like
@batchSize(2)
Combining decorators
Option 1
We could allow one decorator per line like this:
Option 2
We could allow combining decorators on a single line using commas:
@parallel, @batchSize(42)
The text was updated successfully, but these errors were encountered: