Break keyword.control into semantic scopes. Use kebab_break. Readability

michaelblyons · michaelblyons · commit 1cddc0b631ce · 2020-02-04T15:44:23.000-05:00
diff --git a/PowerShell.sublime-syntax b/PowerShell.sublime-syntax
@@ -20,9 +20,18 @@ variables:
   float_suffix: (?i:[fdm](?!b))
   integer_suffix: (?i:ul?|lu?)
   bytes_unit: (?i:[kmgtp]b)
+  kebab_break: (?![\w-])
 
 contexts:
 
+  pop-before-newline:
+    - match: (?=\n|$)
+      pop: true
+
+  pop-at-newline:
+    - match: \n|$
+      pop: true
+
   main:
     - include: comments
     - include: redirection
@@ -61,75 +70,128 @@ contexts:
         - include: main
     - match: \b[\w.-]+\.(?i:exe|com|cmd|bat)\b
       scope: variable.function.powershell
-    - match: \b(?:(?i:begin|break|catch|continue|data|default|define|do|dynamicparam|else|elseif|end|exit|finally|for|foreach(?!-object)|from|if|in|inlinescript|parallel|param|process|return|switch|throw|trap|try|until|var|where(?!-object)|while)|%|\?)(?!\w)
+    # Exceptions
+    - match: \b(?i:throw){{kebab_break}}
+      scope: keyword.control.exception.raise.powershell
+    - match: \b(?i:try){{kebab_break}}
+      scope: keyword.control.exception.try.powershell
+    - match: \b(?i:catch|trap){{kebab_break}}
+      scope: keyword.control.exception.catch.powershell
+    - match: \b(?i:finally){{kebab_break}}
+      scope: keyword.control.exception.finally.powershell
+    # Conditionals
+    - match: \b(?i:if){{kebab_break}}
+      scope: keyword.control.conditional.if.powershell
+    - match: \b(?i:elseif){{kebab_break}}
+      scope: keyword.control.conditional.elseif.powershell
+    - match: \b(?i:else){{kebab_break}}
+      scope: keyword.control.conditional.else.powershell
+    - match: \b(?i:switch){{kebab_break}}
+      scope: keyword.control.conditional.switch.powershell
+    - match: \?
+      scope: keyword.control.conditional.select.powershell
+    - match: \b(?i:where(?!-object)){{kebab_break}}
+      scope: keyword.control.conditional.select.powershell
+    # Begin/End
+    - match: \b(?i:begin){{kebab_break}}
+      scope: keyword.context.block.begin.powershell
+    - match: \b(?i:end){{kebab_break}}
+      scope: keyword.context.block.end.powershell
+    # Loops
+    - match: \b(?i:for|foreach(?!-object)){{kebab_break}}
+      scope: keyword.control.loop.for.powershell
+    - match: \b(?i:do){{kebab_break}}
+      scope: keyword.control.loop.do-while.powershell
+    - match: \b(?i:while){{kebab_break}}
+      scope: keyword.control.loop.while.powershell
+    - match: \b(?i:until){{kebab_break}}
+      scope: keyword.control.loop.repeat-until.powershell
+    # Flow
+    - match: \b(?i:break){{kebab_break}}
+      scope: keyword.control.flow.break.powershell
+    - match: \b(?i:continue){{kebab_break}}
+      scope: keyword.control.flow.continue.powershell
+    - match: \b(?i:exit){{kebab_break}}
+      scope: keyword.control.flow.exit.powershell
+    - match: \b(?i:return){{kebab_break}}
+      scope: keyword.control.flow.return.powershell
+    # Declaration
+    - match: \b(?i:var){{kebab_break}}
+      # scope: storage.type.variable.powershell
+      scope: keyword.declaration.variable.powershell
+    - match: \b(?i:(?:dynamic)?param){{kebab_break}}
+      scope: keyword.declaration.parameter.powershell  # This scope is not standard
+    # Uncategorized keywords
+    - match: \b(?i:data|default|define|from|in|inlinescript|parallel|process){{kebab_break}}
       scope: keyword.control.powershell
     - match: \B--%\B
       scope: keyword.control.powershell
       push:
         - meta_content_scope: string.unquoted.powershell
-        - match: (?=\n|$)
-          pop: true
+        - include: pop-before-newline
     - match: \b(?i:hidden|static)\b
       # This should only be relevant inside a class but will require a rework of how classes are matched. This is a temp fix.
       scope: storage.modifier.powershell
-    - match: \b((?i:class)|%|\?)(?:\s)+([\w-]+)\b
+    - match: \b((?i:class))\s+([\w-]+)\b
       captures:
         1: storage.type.class.powershell
         2: meta.class.powershell entity.name.class.powershell
     # Operators...
-    - match: \B(-)(?i:as)\b
+    - match: \B(-)(?i:as){{kebab_break}}
       scope: keyword.operator.cast.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:[ic]?(?:eq|ne|[gl][te]))\b
+    - match: \B(-)(?i:[ic]?(?:eq|ne|[gl][te])){{kebab_break}}
       scope: keyword.operator.comparison.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:[ic]?(?:not)?(?:like|match|contains|in))\b
+    - match: \B(-)(?i:[ic]?(?:not)?(?:like|match|contains|in)){{kebab_break}}
       scope: keyword.operator.logical.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:join|split|replace)\b
+    - match: \B(-)(?i:join|split|replace){{kebab_break}}
       scope: keyword.operator.string.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:is(?:not)?)\b
+    - match: \B(-)(?i:is(?:not)?){{kebab_break}}
       scope: keyword.operator.logical.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:and|or|not|xor)\b|!
+    - match: \B(-)(?i:and|or|not|xor){{kebab_break}}|!   # <-- note `!`
       scope: keyword.operator.logical.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:band|bor|bnot|bxor|sh[lr])\b
+    - match: \B(-)(?i:band|bor|bnot|bxor|sh[lr]){{kebab_break}}
       scope: keyword.operator.bitwise.powershell
       captures:
         1: punctuation.definition.keyword.powershell
-    - match: \B(-)(?i:f)\b
+    - match: \B(-)(?i:f){{kebab_break}}
       scope: keyword.operator.string-format.powershell
       captures:
         1: punctuation.definition.keyword.powershell
     # Flags/Options/Parameters
-    - match: \B([-/])[\p{L}](?:[\w-]*\w)?
+    - match: \B([-/])\p{L}(?:[\w-]*\w)?
       scope: variable.parameter.option.powershell
       captures:
         1: punctuation.definition.parameter.powershell
-    # operators continue...
+    # Operators continue...
     - match: '[+/*%-]?='
       scope: keyword.operator.assignment.powershell
     - match: (?:\+\+|--)(?![ \t]*\d)
       scope: keyword.operator.assignment.powershell
-    - match: '[+-](?=\.?\d)'
+    - match: '[+-](?=\.?\d)'  # This is sort of heuristic
       scope: keyword.operator.unary.powershell
-    - match: '[+/*%-]'
+    - match: '[+/*-]'
+      scope: keyword.operator.arithmetic.powershell
+    - match: '%(?!\s*\{)'
       scope: keyword.operator.arithmetic.powershell
     - match: \|\||&&
       scope: keyword.operator.logical.powershell
     - match: \|
       scope: keyword.operator.logical.pipe.powershell
     - match: ;
       scope: punctuation.terminator.statement.powershell
-    - match: \`
+    - match: \`(?=\n|$)
       scope: punctuation.separator.continuation.line.powershell
     - match: ','
       scope: punctuation.separator.sequence.powershell
@@ -167,8 +229,7 @@ contexts:
         2: keyword.control.import.require.powershell
       push:
         - meta_scope: meta.requires.powershell
-        - match: \n|$
-          pop: true
+        - include: pop-at-newline
         - include: hashtable
         - match: (-)(?i:Modules|PSSnapin|RunAsAdministrator|ShellId|Version)
           scope: variable.parameter.option.powershell
@@ -185,7 +246,14 @@ contexts:
         3: variable.parameter.powershell
 
   attribute:
-    - match: (\[)\s*\b(?i)(cmdletbinding|alias|outputtype|parameter|validatenotnull|validatenotnullorempty|validatecount|validateset|allownull|allowemptycollection|allowemptystring|validatescript|validaterange|validatepattern|validatelength)\b
+    - match: |-
+        (?xi:
+          (\[)\s*
+          (CmdletBinding|Alias|OutputType|Parameter
+            |Validate(?:Count|NotNull(?:OrEmpty)?|Range|Pattern|Length|Set|Script)
+            |Allow(?:Null|Empty(?:Collection|String))
+          )\b
+        )
       captures:
         1: punctuation.section.bracket.begin.powershell
         2: support.function.attribute.powershell
@@ -209,7 +277,14 @@ contexts:
             - include: type
             - include: numeric-constant
             - include: main
-            - match: (?i)\b(mandatory|valuefrompipeline|valuefrompipelinebypropertyname|valuefromremainingarguments|position|parametersetname|defaultparametersetname|supportsshouldprocess|positionalbinding|helpuri|confirmimpact|helpmessage)\b(?:\s+)?(=)
+            - match: |-
+                (?xi:
+                  \b(Mandatory|ValueFromPipeline(?:ByPropertyName)?
+                    |ValueFromRemainingArguments|Position
+                    |(?:Default)?ParameterSetName|SupportsShouldProcess
+                    |PositionalBinding|HelpUri|ConfirmImpact|HelpMessage)
+                  \s*(=)
+                )
               captures:
                 1: variable.parameter.attribute.powershell
                 2: keyword.operator.assignment.powershell
@@ -224,11 +299,28 @@ contexts:
                   pop: true
 
   commands:
-    - match: (?:[\w\\:-]*\\)?\b(?i:Add|Approve|Assert|Backup|Block|Build|Checkpoint|Clear|Close|Compare|Complete|Compress|Confirm|Connect|Convert|ConvertFrom|ConvertTo|Copy|Debug|Deny|Deploy|Disable|Disconnect|Dismount|Edit|Enable|Enter|Exit|Expand|Export|Find|Format|Get|Grant|Group|Hide|Import|Initialize|Install|Invoke|Join|Limit|Lock|Measure|Merge|Mount|Move|New|Open|Optimize|Out|Ping|Pop|Protect|Publish|Push|Read|Receive|Redo|Register|Remove|Rename|Repair|Request|Reset|Resize|Resolve|Restart|Restore|Resume|Revoke|Save|Search|Select|Send|Set|Show|Skip|Split|Start|Step|Stop|Submit|Suspend|Switch|Sync|Test|Trace|Unblock|Undo|Uninstall|Unlock|Unprotect|Unpublish|Unregister|Update|Use|Wait|Watch|Write)\-.+?(?:\.(?i:exe|cmd|bat|ps1))?\b
-      # "Verb-Noun pattern:"
+    # "Verb-Noun pattern:"
+    - match: |-
+        (?x:
+          (?:[\w\\:-]*\\)?                                                     # Path stuff
+          \b(?i:Add|Approve|Assert|Backup|Block|Build|Checkpoint|Clear|Close   # "Official" Verbs
+            |Compare|Complete|Compress|Confirm|Connect|Convert|ConvertFrom
+            |ConvertTo|Copy|Debug|Deny|Deploy|Disable|Disconnect|Dismount|Edit
+            |Enable|Enter|Exit|Expand|Export|Find|Format|Get|Grant|Group|Hide
+            |Import|Initialize|Install|Invoke|Join|Limit|Lock|Measure|Merge
+            |Mount|Move|New|Open|Optimize|Out|Ping|Pop|Protect|Publish|Push
+            |Read|Receive|Redo|Register|Remove|Rename|Repair|Request|Reset
+            |Resize|Resolve|Restart|Restore|Resume|Revoke|Save|Search|Select
+            |Send|Set|Show|Skip|Split|Start|Step|Stop|Submit|Suspend|Switch
+            |Sync|Test|Trace|Unblock|Undo|Uninstall|Unlock|Unprotect|Unpublish
+            |Unregister|Update|Use|Wait|Watch|Write
+          )
+          \-\w+?                                                               # Any "noun"
+          (?:\.(?i:exe|cmd|bat|ps1))?\b                                        # More path stuff
+        )
       scope: support.function.powershell
+    # Builtin cmdlets with reserved verbs
     - match: \b(?i:(?:foreach|where|sort|tee)-object)\b
-      # Builtin cmdlets with reserved verbs
       scope: support.function.powershell
 
   comment-block:
@@ -242,18 +334,25 @@ contexts:
         - include: comment-embedded-docs
 
   comment-embedded-docs:
-    - match: ^\s*(\.)(?i:(COMPONENT|DESCRIPTION|EXAMPLE|EXTERNALHELP|FORWARDHELPCATEGORY|FORWARDHELPTARGETNAME|FUNCTIONALITY|INPUTS|LINK|NOTES|OUTPUTS|REMOTEHELPRUNSPACE|ROLE|SYNOPSIS))
+    # TODO
+    # https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help
+    - match: |-
+        (?xi:
+          ^\s*(\.)
+          (Component|Description|Example|ForwardHelpTargetName|Functionality
+            |Inputs|Notes|Outputs|RemoteHelpRunSpace|Role|Synopsis)
+        )
       scope: comment.documentation.embedded.powershell
       captures:
         1: punctuation.definition.keyword.documentation.powershell
         2: keyword.other.documentation.powershell
-    - match: ^\s*(\.)(?i:(PARAMETER)\s+([a-z0-9-_]+))
+    - match: ^\s*(\.)(?i:(Parameter)\s+([a-z0-9-_]+))
       scope: comment.documentation.embedded.powershell
       captures:
         1: punctuation.definition.keyword.documentation.powershell
         2: keyword.other.documentation.param.powershell
         3: variable.parameter.powershell
-    - match: ^\s*(\.)(?i:(FORWARDHELPTARGETNAME|FORWARDHELPCATEGORY|REMOTEHELPRUNSPACE|EXTERNALHELP)\s+([a-z0-9-_]+))
+    - match: ^\s*(\.)(?i:(ForwardHelpTargetName|ForwardHelpCategory|ExternalHelp|Link)\s+([a-z0-9-_]+))
       scope: comment.documentation.embedded.powershell
       captures:
         1: punctuation.definition.keyword.documentation.powershell
@@ -266,8 +365,7 @@ contexts:
       scope: punctuation.definition.comment.powershell
       push:
         - meta_scope: comment.line.powershell
-        - match: \n|$
-          pop: true
+        - include: pop-at-newline
         - include: comment-embedded-docs
 
   strings:
@@ -431,16 +529,19 @@ contexts:
         3: keyword.other.unit.powershell
 
   script-block:
-    - match: \{
-      scope: punctuation.section.braces.begin.powershell
+    - match: (%)?(\{)
+      captures:
+        1: keyword.control.loop.for.powershell
+        2: punctuation.section.braces.begin.powershell
       push:
-        - meta_scope: meta.scriptblock.powershell
+        - meta_scope: meta.block.powershell
         - match: \}
           scope: punctuation.section.braces.end.powershell
           pop: true
         - include: main
 
   type:
+    # TODO: push a maybe-static-members context
     - match: \[
       scope: punctuation.section.bracket.begin.powershell
       push:
@@ -585,14 +686,13 @@ contexts:
         1: punctuation.definition.variable.powershell
         2: storage.modifier.scope.powershell
         3: variable.other.readwrite.powershell
-        4: entity.name.function.invocation.powershell
     - match: (?i:(\$)(\{)(global|local|private|script|using|workflow):([^}]*[^}`])(\}))
       captures:
         1: punctuation.definition.variable.powershell
-        2: storage.modifier.scope.powershell
-        3: variable.other.readwrite.powershell
-        4: keyword.other.powershell
-        5: entity.name.function.invocation.powershell
+        2: punctuation.section.braces.begin
+        3: storage.modifier.scope.powershell
+        4: variable.other.readwrite.powershell
+        5: punctuation.section.braces.end
     - match: (?i:(\$)(\w+:)?\w+)
       scope: variable.other.readwrite.powershell
       captures:
diff --git a/Tests/syntax_test_Function.ps1 b/Tests/syntax_test_Function.ps1
@@ -98,7 +98,7 @@ function Verb-Noun {
     #                   ^ meta.attribute punctuation.section.group.end
     #                    ^ meta.attribute punctuation.section.bracket.end
     Param
-    # <- keyword.control
+   #^^^^^ keyword.declaration.parameter
     (
     # <- punctuation.section.group.begin
         # Param1 help description
@@ -322,11 +322,11 @@ function Verb-Noun {
         # <- meta.attribute punctuation.section.bracket.begin
         # ^ meta.attribute support.function.attribute
         #              ^ meta.attribute punctuation.section.group.begin
-        #               ^ meta.attribute meta.scriptblock
-        #                ^^^^^^^^^ meta.scriptblock support.function
-        #                          ^ meta.scriptblock punctuation.definition.variable
-        #                           ^ meta.scriptblock variable.language
-        #                            ^ meta.attribute meta.scriptblock
+        #               ^ meta.attribute meta.block
+        #                ^^^^^^^^^ meta.block support.function
+        #                          ^ meta.block punctuation.definition.variable
+        #                           ^ meta.block variable.language
+        #                            ^ meta.attribute meta.block
         #                             ^ meta.attribute punctuation.section.group.end
         #                              ^ meta.attribute punctuation.section.bracket.end
         [string]
@@ -370,7 +370,7 @@ function Verb-Noun {
         # <- punctuation.section.group.end
 
     Begin
-    # <- keyword.control
+   #^^^^^ keyword.context.block.begin
     {
     }
     Process {
@@ -387,7 +387,7 @@ function Verb-Noun {
         }
     }
     End {
-    # <- keyword.control
+   #^^^ keyword.context.block.end
 
     }
 }
diff --git a/Tests/syntax_test_PowerShell.ps1 b/Tests/syntax_test_PowerShell.ps1

Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,7 @@ function Verb-Noun {`
`98`	`98`	`# ^ meta.attribute punctuation.section.group.end`
`99`	`99`	`# ^ meta.attribute punctuation.section.bracket.end`
`100`	`100`	`Param`
`101`		`- # <- keyword.control`
	`101`	`+ #^^^^^ keyword.declaration.parameter`
`102`	`102`	`(`
`103`	`103`	`# <- punctuation.section.group.begin`
`104`	`104`	`# Param1 help description`
`@@ -322,11 +322,11 @@ function Verb-Noun {`
`322`	`322`	`# <- meta.attribute punctuation.section.bracket.begin`
`323`	`323`	`# ^ meta.attribute support.function.attribute`
`324`	`324`	`# ^ meta.attribute punctuation.section.group.begin`
`325`		`- # ^ meta.attribute meta.scriptblock`
`326`		`- # ^^^^^^^^^ meta.scriptblock support.function`
`327`		`- # ^ meta.scriptblock punctuation.definition.variable`
`328`		`- # ^ meta.scriptblock variable.language`
`329`		`- # ^ meta.attribute meta.scriptblock`
	`325`	`+ # ^ meta.attribute meta.block`
	`326`	`+ # ^^^^^^^^^ meta.block support.function`
	`327`	`+ # ^ meta.block punctuation.definition.variable`
	`328`	`+ # ^ meta.block variable.language`
	`329`	`+ # ^ meta.attribute meta.block`
`330`	`330`	`# ^ meta.attribute punctuation.section.group.end`
`331`	`331`	`# ^ meta.attribute punctuation.section.bracket.end`
`332`	`332`	`[string]`
`@@ -370,7 +370,7 @@ function Verb-Noun {`
`370`	`370`	`# <- punctuation.section.group.end`
`371`	`371`
`372`	`372`	`Begin`
`373`		`- # <- keyword.control`
	`373`	`+ #^^^^^ keyword.context.block.begin`
`374`	`374`	`{`
`375`	`375`	`}`
`376`	`376`	`Process {`
`@@ -387,7 +387,7 @@ function Verb-Noun {`
`387`	`387`	`}`
`388`	`388`	`}`
`389`	`389`	`End {`
`390`		`- # <- keyword.control`
	`390`	`+ #^^^ keyword.context.block.end`
`391`	`391`
`392`	`392`	`}`
`393`	`393`	`}`