ADVANCED.md

Advanced Use and Customization

This document provides detailed guidance and insights for the VNF Scripting Language Extension for Visual Studio Code. It is designed for users who wish to explore the extension's advanced capabilities, customize it according to their needs, and understand its technical details.

Table of Contents

• Advanced Use and Customization
  • Table of Contents
  • Understanding TextMate Grammars
    • Overview of TextMate Grammars
    • Key Components of a TextMate Grammar File
    • How Syntax Highlighting Works with TextMate Grammars
    • Customizing Syntax Highlighting
  • Creating Custom Themes
  • Modifying the Icon
  • Contributing Customizations

Understanding TextMate Grammars

TextMate grammars are crucial for providing syntax highlighting in text editors such as Visual Studio Code. They define the rules for how text is highlighted based on its syntactic structure.

Overview of TextMate Grammars

1. Scope-Based Matching: TextMate grammars assign scopes to text segments in a document, corresponding to syntactic or semantic elements like keywords, variables, or comments.

2. Regular Expressions: These grammars utilize regular expressions to detect code elements, assigning a specific scope to matched text.

3. Grammar Files: These are JSON or XML (plist) files containing patterns of regular expressions and their associated scopes.

Key Components of a TextMate Grammar File

• Patterns: Essential elements of the grammar, consisting of regular expressions and their corresponding scopes. These can range from simple keyword patterns to complex nested structures.

• Repository: A set of reusable named patterns, helping to organize and streamline complex grammars.

• Includes: Allows grammars to include other grammars, beneficial for languages that incorporate multiple languages.

• Name and ScopeName: The file begins with these elements, with ScopeName serving as the grammar's unique identifier.

How Syntax Highlighting Works with TextMate Grammars

1. Tokenization: The editor breaks down text into tokens (like keywords and strings) using the grammar's patterns.

2. Applying Scopes: Each token is assigned a scope based on its pattern match.

3. Styling: The editor styles these scopes according to the active theme, defining the visual presentation of the highlighted text.

Customizing Syntax Highlighting

To tailor syntax highlighting for your needs:

1. Modify Existing Patterns: Enhance or adjust the syntax highlighting by editing the regular expressions and scopes in the vnf.tmLanguage.json file. This file contains the rules defining how different language constructs in VNF are highlighted. The current structure includes:

   • Comments: Marked by a # sign. View Definition
   • Strings: Enclosed within double quotes " ". View Definition
     • Escape Characters: Typically denoted by \. View Definition
     • Angled Brackets Nested Variables: Bound by < >. View Definition
     • Square Brackets Nested Variables: Bound by [ ]. View Definition
     • Curly Brackets Nested Variables: Bound by { }. View Definition
   • Built-in Keywords: Such as enter, contains, jump, at, etc. View Definition
   • Capitalized Words: Examples include JUMP POINT and SECTOR. View Definition
   • Standalone Variables: Variables encased in [ ], <> and { }. View Definition
   • Functions: Formatted as function(argument: Optional). View Definition
   • Conditional Statements: Including if, else, endif. View Definition

   Feel free to adjust or expand these patterns to better align with your needs.

2. Add New Patterns: Introduce new patterns for unique syntactic elements of the VNF scripting language.

   All new patterns must be added in the following format:

   {
   "comment": "Optional. Describe what this pattern does.",
   "name": "scope.name",
   "matches": "put your regex here"
   }
   

3. Test Changes: Consistently test your modifications for accuracy, using files like complex.vnf that cover a broad spectrum of the VNF syntax.

Creating Custom Themes

Developing custom themes to complement the syntax highlighting is possible, though not covered here in detail. The official documentation provides comprehensive guidance on this topic.

Modifying the Icon

If you'd like to modify the extension icon, we have provided the .psd and .clip files here. Modifying the VNF_logo.png file will change the logo of the extension.

Contributing Customizations

Contributions of new features, bug fixes, and enhancements to the extension are highly encouraged and appreciated.

---

For additional information about VS Code's extension features and TextMate grammars, consult the official VS Code documentation and the TextMate grammars manual.

(back to top)