[Rust] Add support for shebang and frontmatter (#4217)

Resolves #4164

This commit ensures to keep first_line_match and syntax highlighting sync.

Push away from main is required for `embed_scope` to be correctly applied if Rust is embedded.

Author: deathaxe

Rust/Rust.sublime-syntax

@@ -9,10 +9,12 @@ file_extensions:
 
 first_line_match: |-
   (?xi:
-    ^ \s* // .*? -\*- .*? \brust\b .*? -\*-  # editorconfig
+    ^ \#! .* {{shebang_language}}            # shebang
+  | ^ \s* // .*? -\*- .*? \brust\b .*? -\*-  # editorconfig
   )
 
 variables:
+  shebang_language: \b(?:cargo|rust)\b
   non_raw_ident: '[[:alpha:]][_[:alnum:]]*|_[_[:alnum:]]+'
   # include a word boundary at the end to ensure all possible characters are
   # consumed, to prevent catastrophic backtracking
@@ -91,7 +93,9 @@ variables:
     )
 contexts:
   main:
-    - include: statements
+    - meta_include_prototype: false
+    - match: ''
+      push: [statements, frontmatter, shebang]
 
   prototype:
     # Macro metavariables. Ideally we would do this as a with_prototype,
@@ -101,6 +105,40 @@ contexts:
     - match: '\${{identifier}}'
       scope: variable.other.rust
 
+  shebang:
+    - meta_include_prototype: false
+    # allow extending syntaxes like Markdown to ignore indentation restrictions
+    - match: \s*(\#!)
+      captures:
+        1: punctuation.definition.comment.rust
+      set: shebang-body
+    - match: ^|(?=\S)  # Note: Ensure to highlight shebang if Rust is embedded.
+      pop: 1
+
+  shebang-body:
+    - meta_include_prototype: false
+    - meta_scope: comment.line.shebang.rust
+    - match: '{{shebang_language}}'
+      scope: constant.language.shebang.rust
+    - match: $\n?
+      pop: 1
+
+  frontmatter:
+    - meta_include_prototype: false
+    - match: \s*(---)\s*$\n?
+      captures:
+        0: meta.frontmatter.rust
+        1: punctuation.section.frontmatter.begin.rust
+      embed: scope:source.toml
+      embed_scope: meta.frontmatter.rust source.toml.embedded.rust
+      escape: ^\s*(---)\s*$\n?
+      escape_captures:
+        0: meta.frontmatter.rust
+        1: punctuation.section.frontmatter.end.rust
+      pop: 1
+    - match: ^|(?=\S)  # Note: Ensure to highlight shebang if Rust is embedded.
+      pop: 1
+
   statements:
     # This isn't really just "statements", it also includes all types,
     # expressions, items, etc.

Rust/tests/syntax_test_frontmatter.md

@@ -0,0 +1,27 @@
+#! SYNTAX TEST "Packages/Markdown/Markdown.sublime-syntax"
+
+1. shebang
+
+   ```rust
+   #!/usr/bin/env cargo
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust comment.line.shebang.rust punctuation.definition.comment.rust
+   #!^^^^^^^^^^^^^^^^^^^ markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust comment.line.shebang.rust - punctuation
+   #!             ^^^^^ constant.language.shebang.rust
+   ```
+
+2. frontmatter
+
+   ```rust
+   ---
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust meta.frontmatter.rust punctuation.section.frontmatter.begin.rust
+   [section]
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust meta.frontmatter.rust source.toml.embedded.rust source.toml meta.section.toml meta.brackets.toml punctuation.section.brackets.begin.toml
+   key = "value"
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust meta.frontmatter.rust source.toml.embedded.rust meta.mapping.key.toml meta.string.toml string.unquoted.toml
+   ---
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust meta.frontmatter.rust punctuation.section.frontmatter.end.rust
+   
+   fn main() {}
+   #! <- markup.list.numbered.markdown markup.raw.code-fence.rust.markdown-gfm source.rust meta.function.rust keyword.declaration.function.rust
+   #!^^^^^^^^^^ source.rust meta.function.rust
+   ```

Rust/tests/syntax_test_frontmatter.rs

@@ -0,0 +1,17 @@
+#! SYNTAX TEST "Rust.sublime-syntax"
+---
+#! <- meta.frontmatter.rust punctuation.section.frontmatter.begin.rust
+#!^ meta.frontmatter.rust punctuation.section.frontmatter.begin.rust
+#! ^ meta.frontmatter.rust - punctuation
+[section]
+#! <- meta.frontmatter.rust source.toml.embedded.rust source.toml meta.section.toml meta.brackets.toml punctuation.section.brackets.begin.toml
+key = "value"
+#! <- meta.frontmatter.rust source.toml.embedded.rust meta.mapping.key.toml meta.string.toml string.unquoted.toml
+---
+#! <- meta.frontmatter.rust punctuation.section.frontmatter.end.rust
+#!^ meta.frontmatter.rust punctuation.section.frontmatter.end.rust
+#! ^ meta.frontmatter.rust - punctuation
+
+fn main() {}
+#! <- meta.function.rust keyword.declaration.function.rust
+#!^^^^^^^^^^ meta.function.rust

Rust/tests/syntax_test_shebang.rs

@@ -0,0 +1,4 @@
+#! SYNTAX TEST "Rust.sublime-syntax"
+#! <- comment.line.shebang.rust punctuation.definition.comment.rust
+ #! <- comment.line.shebang.rust punctuation.definition.comment.rust
+#!^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.line.shebang.rust - punctuation