TCL Expect Formatter

A Visual Studio Code extension that formats TCL expect files according to GDB/GNU coding standards with comprehensive syntax highlighting and intelligent formatting features.

✨ Key Features

• 🎯 Intelligent Formatting: Automatic formatting with GNU coding standards compliance
• 👁️ Live Preview: Eye button for instant formatting preview with diff view
• 🎨 Advanced Syntax Highlighting: 200+ GDB procedures with categorized highlighting
• 🔧 Smart Indentation: Handles complex TCL constructs, bracket alignment, and continuation lines
• ⚡ Performance: Fast, reliable formatting even for large files
• 🎛️ Configurable: Customizable options to match your project needs

📚 Documentation

• Testing Guide - Complete test suite documentation with 85+ test cases and examples
• Technical Details - Detailed formatting algorithm with sequence diagrams
• Development Guide - Contributing guidelines and architecture overview

🚀 Installation

Option 1: VS Code Marketplace

(Once published)

1. Open VS Code Extensions (Ctrl+Shift+X)
2. Search for "TCL Expect Formatter"
3. Click Install

Option 2: From VSIX (Development)

1. Download the latest .vsix file from Releases
2. Install in VS Code: Ctrl+Shift+P → "Extensions: Install from VSIX"

Option 3: Build from Source

See Development Guide for detailed build instructions.

💻 Usage

Supported Files

• .exp - Expect script files
• .expect - Expect script files
• .tcl - TCL files (when containing expect commands)

Quick Formatting

• Format Document: Shift+Alt+F (Windows/Linux) or Shift+Option+F (Mac)
• Format Selection: Select text + Shift+Alt+F
• Right-click Menu: "Format Document" or "Format Selection"

👁️ Live Preview (Recommended)

Click the eye button in the editor title bar to preview formatting changes before applying them!

Alternative preview methods:

• Keyboard: Ctrl+Shift+Alt+F (Windows/Linux) or Cmd+Shift+Alt+F (Mac)
• Command Palette: Ctrl+Shift+P → "Preview Formatting Changes"
• Right-click Menu: "Preview Formatting Changes"

The preview shows a side-by-side diff with your original code (left) and formatted code (right).

✨ Formatting Examples

Basic Formatting

# Before:
if{$condition}{
puts "test"
}

# After:
if {$condition} {
    puts "test"
}

Advanced Bracket Alignment

# Before:
gdb_test "command" [multi_line \
"line1" \
"line2"] \
"description"

# After:
gdb_test "command" [multi_line \
                   "line1" \
                   "line2"] \
    "description"

Expect Commands

# Before:
expect{
"pattern"{send "response\\r"}
timeout{puts "timeout"}
}

# After:
expect {
    "pattern" {
        send "response\\r"
    }
    timeout {
        puts "timeout"
    }
}

For more examples, see Testing Guide.

⚙️ Configuration

Configure the formatter through VS Code settings (File → Preferences → Settings):

Key Settings

Example Configuration

{
  "tclExpectFormatter.indentSize": 4,
  "tclExpectFormatter.maxLineLength": 79,
  "tclExpectFormatter.insertFinalNewline": true,
  "tclExpectFormatter.trimTrailingWhitespace": true
}

🎨 Syntax Highlighting

The extension provides comprehensive syntax highlighting for 200+ GDB procedures with categorized coloring:

Highlighted Elements

• GDB Core Functions: gdb_test, gdb_test_multiple, gdb_test_sequence
• Session Management: clean_restart, gdb_start, gdb_exit
• Test Assertions: pass, fail, xfail, gdb_assert
• Machine Interface: mi_gdb_test, mi_create_varobj
• TCL/Expect Commands: if, while, expect, send, spawn
• Variables and Strings: $var, "strings", comments

Custom Color Themes

Customize colors through VS Code settings (Ctrl+, → search "colorCustomizations"):

{
  "workbench.colorCustomizations": {
    "editor.tokenColorCustomizations": {
      "textMateRules": [
        {
          "scope": "support.function.gdb.core.tcl",
          "settings": { "foreground": "#4FC1FF", "fontStyle": "bold" }
        }
      ]
    }
  }
}

Test Your Highlighting

Create a test file with .exp extension to verify highlighting works:

# Test different GDB function categories
gdb_test "print var" "= 42" "core test"           # Core testing
gdb_breakpoint "main"                              # Breakpoint management  
clean_restart $binfile                             # Session management
pass "test passed"                                 # Assertions
mi_gdb_start                                       # Machine Interface

# Standard TCL/Expect
expect { "prompt" { send "cmd\r" } }              # Expect commands
if {$var == "test"} { puts "found" }              # Control structures

🧪 Testing & Quality

The extension includes 85 comprehensive tests ensuring reliable formatting:

• 71 Unit Tests: Core functionality and edge cases
• 6 Golden Master Tests: End-to-end formatting validation
• 8 Extension Tests: VS Code integration testing

See Testing Guide for detailed test documentation and examples.

🤝 Contributing

Contributions are welcome! Please see the Development Guide for:

• Development environment setup
• Code style guidelines
• Testing requirements
• Pull request process

📜 License

MIT License - see LICENSE file for details.

📋 Changelog

1.1.9

• Comprehensive Testing: Added 85 comprehensive tests with complete coverage
• Documentation: Split documentation into focused guides (Testing, Development, Formatting)
• Enhanced Test Coverage: Added edge cases, performance tests, and regression prevention
• Improved Architecture: Better organized test suites and documentation structure

1.1.6

• Infrastructure: Updated GitHub Actions workflows to fix deprecated warnings
• Maintenance: Improved CI/CD pipeline reliability and compatibility

1.1.0

• Major Feature: Added formatting preview with diff view and eye button
• Major Feature: Added hover tooltips for formatting explanations
• Bug Fix: Fixed critical single-line formatting bug (Ctrl+K+F)
• Enhancement: Improved VS Code integration

For complete changelog, see Development Guide.