Skip to content

REFERENCES.md

Latest commit

 

History

History
293 lines (210 loc) · 9.82 KB

REFERENCES.md

File metadata and controls

293 lines (210 loc) · 9.82 KB

References and Resources

This document provides links and references to all the key resources needed for building the Soar VS Code extension.

Source Code Repositories

Soar Language Server

  • Repository: https://github.com/soartech/soar-language-server
  • Language: Java
  • Key Locations:
    • Main source: src/main/java/com/soartech/soar/lsp/
    • Resources: src/main/resources/
    • Build: build.gradle
  • Purpose: LSP implementation for Soar providing diagnostics, hover, completion, and navigation

Legacy Soar VS Code Extension

VisualSoar

  • Repository: https://github.com/SoarGroup/VisualSoar
  • Language: Java
  • Key Locations:
    • DataMap logic: src/main/java/edu/umich/soar/visualsoar/datamap/
    • DataMap checker: src/main/java/edu/umich/soar/visualsoar/datamap/DataMapChecker.java
    • DataMap nodes: src/main/java/edu/umich/soar/visualsoar/datamap/DataMapNode.java
    • Parser: src/main/java/edu/umich/soar/visualsoar/parser/
    • UI: src/main/java/edu/umich/soar/visualsoar/graph/
  • Purpose: Reference for DataMap data structures, validation logic, and UI patterns

Documentation Resources

VS Code Extension Development

Language Server Protocol

TextMate Grammars

TypeScript

VS Code API References

Key APIs Used

Language Features

  • vscode.languages.registerCompletionItemProvider - Code completions
  • vscode.languages.createDiagnosticCollection - Error/warning diagnostics
  • vscode.languages.registerHoverProvider - Hover information
  • vscode.languages.registerDefinitionProvider - Go to definition

UI Components

  • vscode.window.createTreeView - Tree view in sidebar
  • vscode.window.createWebviewPanel - Webview panels
  • vscode.window.showInformationMessage - Notifications
  • vscode.window.createStatusBarItem - Status bar items

File System

  • vscode.workspace.findFiles - Find files by pattern
  • vscode.workspace.createFileSystemWatcher - Watch file changes
  • vscode.workspace.getConfiguration - Get settings

Commands

  • vscode.commands.registerCommand - Register commands
  • vscode.commands.executeCommand - Execute commands

Soar-Specific Resources

Soar Documentation

Soar Community

Code Examples and Patterns

Example VS Code Extensions

LSP Examples

TreeView Examples

Tools and Libraries

Build and Package Tools

Testing

Linting

Java Tools (for Language Server)

Build Tools

Java Downloads

Key npm Packages

{
  "vscode": "^1.80.0",
  "vscode-languageclient": "^9.0.0",
  "@vscode/test-electron": "^2.3.0",
  "@vscode/vsce": "^2.19.0",
  "typescript": "^5.0.0",
  "@types/node": "^18.x",
  "@types/vscode": "^1.80.0",
  "eslint": "^8.40.0",
  "@typescript-eslint/eslint-plugin": "^6.0.0",
  "@typescript-eslint/parser": "^6.0.0",
  "mocha": "^10.0.0",
  "@types/mocha": "^10.0.0"
}

Important Code Locations

In This Project

Once built, key locations will be:

src/
├── extension.ts                 # Main entry point
├── client/
│   └── lspClient.ts            # LSP client implementation
├── server/
│   └── serverConfig.ts         # Server configuration
├── datamap/
│   ├── index.ts                # Core datamap class
│   ├── types.ts                # Type definitions
│   ├── parser.ts               # Datamap parser
│   ├── validator.ts            # Datamap validation
│   ├── diagnostics.ts          # VS Code diagnostics integration
│   ├── loader.ts               # Datamap loader
│   └── utils.ts                # Utility functions
├── providers/
│   └── completionProvider.ts  # Code completion provider
└── ui/
    ├── treeview.ts             # TreeView provider
    └── webview/
        └── datamapPanel.ts     # Webview panel

VisualSoar Key Files

For reference when porting DataMap logic:

src/main/java/edu/umich/soar/visualsoar/
├── datamap/
│   ├── DataMap.java                # Main datamap class
│   ├── DataMapNode.java            # Node representation
│   ├── SoarWorkingMemoryModel.java # WM model
│   ├── DataMapChecker.java         # Validation logic
│   └── DataMapTree.java            # Tree structure
├── parser/
│   ├── ParseException.java
│   ├── SoarParser.java             # Main parser
│   └── TokenMgrError.java
└── graph/
    └── DataMapGraph.java           # Graph visualization

Troubleshooting Resources

Common Issues

  • Extension Not Activating: Check activation events in package.json
  • LSP Not Starting: Verify Java installation and server JAR path
  • Syntax Highlighting Not Working: Validate TextMate grammar JSON
  • TypeScript Errors: Check tsconfig.json and type definitions

Debugging

  • VS Code Extension Host: Press F5 to launch debug instance
  • Developer Tools: Help > Toggle Developer Tools
  • Extension Logs: View > Output > Select "Soar Language Server"

Publishing

Marketplace

GitHub Actions

Additional Resources

Soar Papers and Publications

Community Support

  • Stack Overflow: Tag questions with vscode-extensions and soar
  • VS Code Extension Discord: Community discussions
  • Soar mailing lists: For Soar-specific questions

Version Information

This guide was created for:

  • VS Code API: 1.80.0+
  • Node.js: 16.x or later
  • TypeScript: 5.0+
  • LSP: 3.17
  • Java: 11+ (for Language Server)

License Information

Make sure to review licenses for:

  • VS Code Extension API (MIT)
  • Soar Language Server (check repository)
  • VisualSoar (check repository)
  • Any dependencies you include

Contact and Contribution