-
Notifications
You must be signed in to change notification settings - Fork 736
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
Make the language "less" newline sensitive #146
Comments
Not sure if this is the right place for this comment, feel free to point me to a better Issue. If this means I can add newline on long lines for readability this would be great! Long if-statements, these can be hard to read. For example:
This would be much more readable over several lines:
Same thing goes for conditional deploys when they are implemented:
vs
|
Also adding #1760 as a related issue |
I noticed a dirty hack to split functions over multiple lines, using block comments: var multilineFunction = resourceGroup(/*
*/ mySubscription, /*
*/ myResourceGroup) Same thing works for ternary, and probably generally for all expressions: var test2 = thisIsAVeryLongTernary && iWouldLikeToSplitIt ?/*
*/ acrossMultiple :/*
*/ lines I don't recommend anyone actually use this 😄 |
Can the team document these under limitations? Same as multiple line arrays? |
@masters3d - We have a known limitations section in our README. Did you see this there? Where else would you want/expect to see this? |
I don’t see documentation that the language is white space sensitive in certain scenarios. It would be great to see all of these listed. |
I did some experimenting on a branch, and wanted to write up some notes / get some feedback. If you'd like to try this out and give feedback, install the VSCode extension I built here. Main things I wanted to solve
Assumptions
Initial idea// Single-line declarations use commas to separate elements
var myObject = { abc: 'def', ghi: 'jkl' }
var myArray = [ 'abc', 'def' ]
var myFunc = concat('abc', 'def')
// Multi-line declarations do not use commas to separate elements
var myObject = {
abc: 'def'
ghi: 'jkl'
}
var myArray = [
'abc'
'def'
]
var myFunc = concat(
'abc'
'def'
)
// Also allow mixing and matching
var mixedArray = [
'abc', 'def'
'ghi', 'jkl'
] Thoughts
Alternatives
FeedbackI'd love to get some feedback on the above - feel free to respond with your preference on either:
|
@anthony-c-martin ...
resource interactiveQueryRequestsFailAlert 'Microsoft.Insights/scheduledQueryRules@2021-08-01' = {
name: empty(hdInsightMonitoring.alertRules.interactiveQueryRequestsFail.id) ?
alertRules.interactiveQueryRequestsFail.id :
hdInsightMonitoring.alertRules.interactiveQueryRequestsFail.id
location: location
kind: 'LogAlert'
properties: {
overrideQueryTimeRange: hdInsightMonitoring.alertRules.interactiveQueryRequestsFail.overrideQueryTimeRange == 0 ?
null :
'PT${hdInsightMonitoring.alertRules.interactiveQueryRequestsFail.overrideQueryTimeRange}M'
.... and this ...
resource resourceGroupsRes 'Microsoft.Resources/resourceGroups@2021-04-01' existing =
if (!empty(hdInsightMonitoring.alertsScope.resourceGroup)) {
name: hdInsightMonitoring.alertsScope.resourceGroup
scope: subscription(hdInsightMonitoring.alertsScope.subscriptionId)
}
... As reading becomes hard when when you have conditions with long names for parameters/variables or you have 2 or more conditions nested or you have conditions on resources that are long. |
@slavizh - I should have started by saying it's not one or the other 😄. Here I was just focusing on functions & objects/arrays - I think the overall issue has been ignored as it's quite nebulous, and wanted to break it down into targeted areas to improve. Totally agree that the ternary operator EDIT: Raised #5829 for this |
I think Go largely gets this right. Semicolons (their separator) are legal to use as a separator in addition to newlines, but are removed by autoformatting. https://go.dev/ref/spec#Semicolons You could also choose to make commas required for functions and not for the other usages. For example go uses commas (never optional) in expressions, and semicolons in declarations (optional). |
At first, I prefer Alternative 1, which is what F# has implemented: https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/lists#creating-and-initializing-lists (the difference is that F# uses semicolons as a separators). However, when switching from single line to multiline array/objects, users would have to remove commas, which makes think that the initial idea is better. I also like @rynowak's idea to let the formatter remove commas in multiline declarations. |
As requested in the 2022-01-27 community call. If you want to embed that in your bicep, you'd have to inline a significant piece of xml (not a full xml doc, but a snippet) When this is not support and the xml needs to remain in an external file, there is already support via the loadTextContent('my-xml-file.xml'). To me that's fine, inline would be maybe a bit more intuitive since it's explicit and maybe would open the road to do parameter substitution in the text content. |
@CarloKuip - the good news is you can actually already do this today, using Bicep's multi-line strings 😄 For example: resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2021-01-01-preview' = {
parent: api
name: 'policy'
properties: {
format: 'rawxml'
value: '''
<policies>
<inbound>
<cors>
<allowed-origins>
<origin>__ORIGIN__</origin>
</allowed-origins>
<allowed-methods>
<method>*</method>
</allowed-methods>
<allowed-headers>
<header>*</header>
</allowed-headers>
<expose-headers>
<header>*</header>
</expose-headers>
</cors>
</inbound>
<backend>
<forward-request />
</backend>
<outbound />
<on-error />
</policies>
'''
}
} Docs here. |
I will add a comment on this one. I don't want to stop other people having options for what they want and personal preference for code style or configuration management style. One thing that I have come to appreciate over time when you have large configuration documents, having a single configuration item on each line, ensures that it's easier to maintain in version control and also helps to avoid merge conflicts. I do appreciate how json formatter takes arrays and puts them on new lines by default, unless you minify the json. I didn't appreciate this at first, however auto format in a deterministic fashion (along with the linting rules) is extremely helpful for not committing errors.
To summarize: I am not against a new feature, however it would be my preference if having an auto format + linting, would be available as part of the implementation. In saying this I am also guilty of the following, ... which @anthony-c-martin mentioned further up in this issue #146 (comment) networkSecurityGroup: !(contains(sn, 'NSG') && bool(sn.NSG)) ? null : /*
*/ {
id: contains(sn, 'NSGID') ? sn.NSGID : NSG[index].id
} |
And the feedback from today's community call with a demo of an MVP implementation Link to demo: https://youtu.be/R6SyuRhTmmc?t=1145s 🤔🤔🤔 |
"With functions, we keep the command and can now split over multiple lines" ✅ var func = resourceGroup(
mySub
myRGName
) I wrote this, just this week, so this feature would avoid the targetResourceId: ep.eptype != 'azure' ? null : resourceId( EPs[index].subname, /* subscription
*/ EPs[index].rgname, /* resourcegroup
*/ EPs[index].restype, /* resourcetype e.g. publicip
resource name */ '${EPs[index].resnameprefix}${ep.prefix}-${EPs[index].org}-${EPs[index].app}-${EPs[index].env}-${ep.name}') Array and Objects e.g. I would expect below var arr = [
'abc',
'def'
]
var arr = [ 'abc', 'def' ]
var arr = [
'abc', //<--- this is nice to have, since i just temporarily commented 'def'
//'def'
]
var arr = [
'abc'
'def' // updating comment to say that I will always be a fan of no commas here.
]
After rewatching the video, my brain caught up and I think all of this is good ✅ I didn't vote on the call, however I would say yes now. |
Would trailing commas be permitted on function calls, as in: resourceId(
'Microsoft.Rp/widgets',
'myWidget',
) Not sure if any language other than Python permits that syntax, but it can help generate more useful diffs when adding or removing arguments. |
@brwilkinson I second that. Actually, I think it is a requirement to update the formatter to support alternative layouts, because currently the formatter uses hard-coded rules and always puts an array/object item on a new line. I'd volunteer to update the formatter (time to implement the second part of https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf 🙂). |
Part 2, pretty print with alternate patterns, would be so nice, I think the optimal/ideal solution. The setting for grouping based on chosen width, seems to be the best of both worlds. to align with the single/multiline capability flexibility language additions in this issue. When work was being done on ARM template JSON, the capability was implemented to allow expressions to be placed over multiple lines. After that addition, the formatter was then disabled around these function (so formatting became manual). @StephenWeatherford did some work with a UI 'toolstip' feature to show the following. No formatter was implemented, however the preview was available, which shows the nested/grouped format. (slightly different grouping/flattening than in that doc, however similar concept). I am already thinking of a decorator to override the default width/grouping for the next line expression 😀 Adding one extra comment, with the discussions on Bicep language Param Files, it seems whatever if available in the bicep Modules will also be even more significant in the end-user interface, which are the param files formats. e.g. arrays/objects format specifically related to user configuration, which are more dynamic than the Bicep Modules themselves, so this will be most significant there. |
Closing this issue out - going forwards, please create separate issues for the specific syntax that you would like relaxed line break support for: |
0.2 pending discussion with anders
The text was updated successfully, but these errors were encountered: