sql writer
This commit is contained in:
274
vscode-extension/relspec-template-editor/README.md
Normal file
274
vscode-extension/relspec-template-editor/README.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# RelSpec Template Editor for VS Code
|
||||
|
||||
Visual editor and tooling for RelSpec PostgreSQL migration templates.
|
||||
|
||||
## Features
|
||||
|
||||
### 1. Template Preview
|
||||
- **Command**: `RelSpec: Preview Template`
|
||||
- **Shortcut**: Click the preview icon in the editor title bar
|
||||
- Preview your templates with sample data
|
||||
- Side-by-side view of template, data, and rendered SQL
|
||||
|
||||
### 2. Syntax Validation
|
||||
- **Command**: `RelSpec: Validate Template`
|
||||
- Automatic validation on save (configurable)
|
||||
- Highlights syntax errors inline
|
||||
- Checks for unclosed template tags
|
||||
|
||||
### 3. IntelliSense
|
||||
- Auto-completion for template functions
|
||||
- Function signatures and documentation on hover
|
||||
- Keyword completions (`if`, `range`, `template`, etc.)
|
||||
|
||||
### 4. Template Scaffolding
|
||||
- **Command**: `RelSpec: New Template`
|
||||
- Quick scaffolding for common template types:
|
||||
- DDL operations
|
||||
- Constraints
|
||||
- Indexes
|
||||
- Audit trails
|
||||
- Reusable fragments
|
||||
|
||||
### 5. Function Library
|
||||
- **Command**: `RelSpec: List Available Functions`
|
||||
- Browse all available template functions
|
||||
- See examples and documentation
|
||||
- Quick reference for template development
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
1. Clone the RelSpec repository
|
||||
2. Navigate to the extension directory:
|
||||
```bash
|
||||
cd vscode-extension
|
||||
```
|
||||
3. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
4. Compile the extension:
|
||||
```bash
|
||||
npm run compile
|
||||
```
|
||||
5. Open in VS Code:
|
||||
```bash
|
||||
code .
|
||||
```
|
||||
6. Press `F5` to launch the extension in a new window
|
||||
|
||||
### From VSIX (when published)
|
||||
|
||||
```bash
|
||||
code --install-extension relspec-template-editor-0.1.0.vsix
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Opening Templates
|
||||
|
||||
1. Open your RelSpec project in VS Code
|
||||
2. Navigate to `pkg/writers/pgsql/templates/`
|
||||
3. Open any `.tmpl` file
|
||||
4. The extension will automatically activate
|
||||
|
||||
### Previewing Templates
|
||||
|
||||
1. Open a template file
|
||||
2. Click the preview icon in the editor title bar OR
|
||||
3. Run command: `RelSpec: Preview Template` (Ctrl+Shift+P)
|
||||
4. The preview pane will show:
|
||||
- Your template source
|
||||
- Sample data (configurable)
|
||||
- Rendered SQL output
|
||||
|
||||
### Configuring Sample Data
|
||||
|
||||
Set custom sample data for preview in settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"relspec.previewSampleData": {
|
||||
"SchemaName": "public",
|
||||
"TableName": "users",
|
||||
"ColumnName": "email",
|
||||
"Columns": [
|
||||
{"Name": "id", "Type": "integer", "NotNull": true},
|
||||
{"Name": "email", "Type": "text"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Creating New Templates
|
||||
|
||||
1. Run command: `RelSpec: New Template`
|
||||
2. Select template type
|
||||
3. Enter template name
|
||||
4. The extension creates a scaffolded template
|
||||
5. Edit and customize
|
||||
|
||||
### Using IntelliSense
|
||||
|
||||
Type `{{` to trigger auto-completion:
|
||||
|
||||
```gotmpl
|
||||
{{upper // Shows function signature and documentation
|
||||
{{. // Shows available fields from data structure
|
||||
```
|
||||
|
||||
Hover over function names to see:
|
||||
- Function signature
|
||||
- Description
|
||||
- Usage examples
|
||||
|
||||
## Configuration
|
||||
|
||||
Available settings:
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `relspec.templatePath` | string | `pkg/writers/pgsql/templates` | Path to template directory |
|
||||
| `relspec.autoValidate` | boolean | `true` | Validate templates on save |
|
||||
| `relspec.showDataStructures` | boolean | `true` | Show data structure hints in preview |
|
||||
| `relspec.previewSampleData` | object | `{}` | Sample JSON data for preview |
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Command | Shortcut | Description |
|
||||
|---------|----------|-------------|
|
||||
| Preview Template | N/A | Click preview icon in title bar |
|
||||
| Validate Template | N/A | Use command palette |
|
||||
| New Template | N/A | Use command palette |
|
||||
|
||||
## Template Functions Reference
|
||||
|
||||
The extension provides IntelliSense for all RelSpec template functions:
|
||||
|
||||
### String Manipulation
|
||||
- `upper` - Convert to uppercase
|
||||
- `lower` - Convert to lowercase
|
||||
- `title` - Title case
|
||||
- `snake_case` - Convert to snake_case
|
||||
- `camelCase` - Convert to camelCase
|
||||
|
||||
### SQL Formatting
|
||||
- `indent` - Indent text
|
||||
- `quote` - Quote for SQL
|
||||
- `escape` - Escape special characters
|
||||
- `safe_identifier` - Make safe SQL identifier
|
||||
|
||||
### Type Conversion
|
||||
- `goTypeToSQL` - Go type → SQL type
|
||||
- `sqlTypeToGo` - SQL type → Go type
|
||||
- `isNumeric` - Check if numeric type
|
||||
- `isText` - Check if text type
|
||||
|
||||
### Collection Helpers
|
||||
- `first` - First element
|
||||
- `last` - Last element
|
||||
- `filter` - Filter elements
|
||||
- `mapFunc` - Map function
|
||||
- `join_with` - Join with separator
|
||||
- `join` - Join strings
|
||||
|
||||
See full documentation: [Template Functions](../pkg/writers/pgsql/TEMPLATE_FUNCTIONS.md)
|
||||
|
||||
## Code Snippets
|
||||
|
||||
The extension includes snippets for common patterns:
|
||||
|
||||
| Prefix | Description |
|
||||
|--------|-------------|
|
||||
| `tmpl-define` | Define a new template |
|
||||
| `tmpl-template` | Use a template |
|
||||
| `tmpl-block` | Define a block |
|
||||
| `tmpl-if` | If statement |
|
||||
| `tmpl-range` | Range loop |
|
||||
| `tmpl-with` | With statement |
|
||||
|
||||
## Development
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
npm run compile
|
||||
```
|
||||
|
||||
### Watching
|
||||
|
||||
```bash
|
||||
npm run watch
|
||||
```
|
||||
|
||||
### Linting
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Extension Not Activating
|
||||
|
||||
**Problem**: Extension doesn't activate when opening .tmpl files
|
||||
|
||||
**Solution**:
|
||||
1. Check that file has `.tmpl` extension
|
||||
2. Reload VS Code window (Ctrl+Shift+P → "Reload Window")
|
||||
3. Check extension is enabled in Extensions panel
|
||||
|
||||
### Preview Not Working
|
||||
|
||||
**Problem**: Preview shows error or doesn't update
|
||||
|
||||
**Solution**:
|
||||
1. Ensure RelSpec binary is in PATH
|
||||
2. Check template syntax is valid
|
||||
3. Verify sample data is valid JSON
|
||||
|
||||
### IntelliSense Not Working
|
||||
|
||||
**Problem**: Auto-completion doesn't trigger
|
||||
|
||||
**Solution**:
|
||||
1. Type `{{` to trigger
|
||||
2. Check language mode is set to "Go Template"
|
||||
3. Reload window
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Please:
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
Same as RelSpec project license.
|
||||
|
||||
## Links
|
||||
|
||||
- [RelSpec Documentation](../README.md)
|
||||
- [Template Documentation](../pkg/writers/pgsql/TEMPLATES.md)
|
||||
- [Template Inheritance](../pkg/writers/pgsql/TEMPLATE_INHERITANCE.md)
|
||||
- [Issue Tracker](https://github.com/yourorg/relspec/issues)
|
||||
|
||||
## Changelog
|
||||
|
||||
### 0.1.0 (Initial Release)
|
||||
- Template preview with sample data
|
||||
- Syntax validation
|
||||
- IntelliSense for functions
|
||||
- Template scaffolding
|
||||
- Function library browser
|
||||
Reference in New Issue
Block a user