Harbour Language Plugin for PyCharm

A comprehensive plugin for PyCharm that provides advanced support for the Harbour/Clipper programming language.

This plugin was implemented as vibe-coding project using OpenAI O1 and Claude. For detailed development insights and experiences, see the MAKING-OF.

Table of Contents

• Installation
• Features
• Settings
• Roadmap
• Known Issues
• VS Code Users
• Building Plugin
• License

Installation

1. Download the latest plugin from the releases page
2. In PyCharm: Settings → Plugins → ⚙️ → Install Plugin from Disk...
3. Select the downloaded plugin file and restart PyCharm

Important: File Size Limits Configuration

By default, PyCharm/IntelliJ has file size limits that may be too small for large Harbour projects. To work with files larger than 2.5 MB, you need to manually configure these limits:

1. Go to Help → Edit Custom Properties
2. Add the following lines to the file:

   idea.max.intellisense.filesize=102400
   idea.max.content.load.filesize=204800
   

   These values set the limits to 100 MB for code assistance and 200 MB for file opening.
3. Save the file and restart the IDE

Note: These are IDE-level settings that must be configured manually and cannot be changed by plugins at runtime.

Features

• Syntax Highlighting - Complete color coding for Harbour/Clipper keywords, functions, and syntax
• Code Completion - Intelligent auto-completion for functions, methods, and variables
• Function Navigation - Go-to-declaration and reference resolution
• Rename Refactoring - Safe renaming of functions and variables across projects
• Structure View - Tree view of functions, procedures, and classes
• Code Formatting - Automatic code indentation and formatting
• Linting - Real-time code analysis and error detection
• Debugging - Full breakpoint debugging for console and GUI applications with database inspection
• Automatic Error Monitoring - Clickable stack traces for runtime errors
• Code Helpers - Quick actions to improve code quality and reduce typing

Syntax Highlighting

Full color coding support for Harbour/Clipper syntax with customizable color schemes. Keywords, functions, comments, strings, and operators are distinctly highlighted for better code readability.

Enhanced syntax highlighting with customizable color schemes

Code Completion

Intelligent auto-completion suggests functions, methods, variables, and Harbour commands as you type. Supports both built-in Harbour functions and user-defined functions from your project.

Smart auto-completion for Harbour functions and variables

Function Navigation

Quickly navigate to function definitions with Ctrl+Click or Ctrl+B. The plugin resolves references across files for custom defined and built-in functions, variables, etc. For external harbour functions an external documentation link (configurable in the settings) will be opend.

Function navigation with external documentation links for built-in functions

Same applies for procedures, classes, methods and variables. Newly added function, procedures, etc. are added to the index once the file is saved.

Rename Refactoring

Safely rename functions, procedures, and variables across your entire project with Shift+F6. All references are automatically updated while preserving code functionality.

Safe project-wide rename refactoring for functions and variables

Structure View

The structure view panel (Alt+7) shows a tree overview of functions, procedures, classes, and variables in the current file for easy navigation.

Structure view showing project organization

Code Formatting

Automatic code indentation and formatting follows Harbour conventions. Customize indentation, line breaks, and statement positioning in settings.

Customizable code formatting options

Linting

Real-time code analysis provides instant feedback on syntax errors, undefined variables, and potential issues as you type. The linting engine integrates seamlessly with PyCharm's inspection framework.

Real-time linting highlights syntax errors and undefined variables

Configure linting settings in Settings → Tools → Harbour → Linting:

Customizable linting rules and severity levels

Note: For proper linting functionality, ensure all include paths are correctly configured in your project settings. Missing include files or incorrect paths may prevent the linter from detecting syntax errors and unused variables.

Debugging

The plugin provides full debugging support for both console and GUI applications with PyCharm debugger integration featuring conditional breakpoints, variable inspection, step debugging, and watches.

Variable Types Supported

• Local Variables: Function/procedure local variables (LOCAL nVar)
• Private Variables: Private memory variables (PRIVATE m_nVar)
• Public Variables: Public memory variables (PUBLIC g_nVar)
• Static Variables: Currently not supported due to Harbour VM limitations

Setup

1. Create Debug Configuration - Use Harbour Application type in PyCharm run configurations

   
   Harbour Application debug configuration settings

   Note: Debug flags (-b -D__HARBOUR_DEBUG__) are automatically added when using PyCharm debug configurations.

2.Set Breakpoints - Click in the gutter next to line numbers

Console debugging with breakpoints and variable inspection

3. Start Debugging - Use Debug button or Shift+F9

GUI debugging with PyCharm debugger and variable inspection

Database View

During debugging, the plugin provides a Database View tool window that shows all currently open database workareas in your Harbour application. This allows you to inspect database state while stepping through code.

Database workarea browser showing open databases during debugging

Features:

• View all open database workareas (Area 1, Area 2, etc.)
• Inspect current record data and field values
• See field structure (name, type, size)
• Navigate between records using Previous/Next buttons
• Jump to specific record numbers
• View indexes and schema information
• Refresh data to see updates

The Database View automatically updates when you step through code that opens, closes, or modifies database records.

Limitations

• Static Variables: Static variables are not visible in the debugger due to Harbour VM compilation-unit scoping

Automatic Error Monitoring

The plugin automatically provides clickable stack traces for runtime errors in the PyCharm console.

Clickable stack traces for quick navigation to error locations

Custom ErrorBlock Integration

If your project uses a custom ErrorBlock handler, you can still get clickable stack traces by calling printDebugStackTrace() from your error handler:

// Your custom error handling
ErrorBlock({|oError| MyCustomHandler(oError)})

FUNCTION MyCustomHandler(oError)
   // Your custom error logic here
   LogToMyDatabase(oError)
   SaveToLogFile(oError)
   
   // Generate PyCharm-compatible stack trace
   printDebugStackTrace()
   
   // Continue with your error handling
   QUIT
RETURN NIL

Key points:

• Add printDebugStackTrace() to your custom error handler
• This generates clickable stack traces in PyCharm console
• Works alongside your existing error handling logic

Code Helpers

The plugin provides quick actions to improve code quality and reduce repetitive typing:

Declare Local Variable (Alt+L)

Quickly declare undefined variables as LOCAL with proper placement and indentation.

How to use:

1. Place cursor on any undefined variable in your code
2. Press Alt+L
3. The plugin automatically:
   • Detects the variable name under cursor
   • Finds the containing function or procedure
   • Adds LOCAL variableName declaration at the proper position
   • Respects your LOCAL indentation settings

Example:

FUNCTION TestFunction()
   LOCAL existingVar
   
   myNewVar := 10  // Place cursor on 'myNewVar' and press Alt+L
   // Plugin will add: LOCAL myNewVar

Features:

• Smart placement after existing LOCAL declarations
• Validates variable names (prevents declaring keywords)
• Checks for duplicate declarations
• Uses indentation from code style settings
• Shows helpful notifications for errors or success

Settings

Access Harbour plugin settings: Settings → Tools → Harbour

Configure Harbour tools, paths, and debugging options

Configuration Options

• Documentation URL - Base URL for external Harbour documentation
• Debug Log Directory - Location for debug logs (empty to disable)
• Build Output Directory - Default .hbmk for build artifacts
• Auto-completion - Enable while typing (default: Ctrl+Space only)
• Include Paths - Add directories for #include file resolution
• Excluded Files - Files to exclude from navigation and indexing
• Commands - Customize code completion command list

Code Style Settings

Customize code formatting: Settings → Editor → Code Style → Harbour

Configure indentation, spacing, and formatting rules

Color Scheme Settings

Customize syntax highlighting: Settings → Editor → Color Scheme → Harbour

Customize syntax highlighting colors and themes

Roadmap / TODOs

• Official JetBrains Plugin - Submit to JetBrains Marketplace for easier installation
• Process Coupling - When the debugging process in PyCharm is stopped the running harbour GUI should be terminated as well.
• Tests - write tests.

Known Issues

• Ctrl+hover should not show tooltip
• Ctrl-click: Internal function navigation may jump to function definition instead of showing a declaration dialog if the file w/ the function definition misses some include file or if the list of usages is very long. Subsequent click on function declaration itself work.
• most function/procedure features do not work yet for truncated keywords func/proce.

VS Code Users

For Visual Studio Code users, there's an excellent Harbour Code Extension available. This VS Code plugin was a great help and inspiration during the development of our PyCharm plugin, providing valuable insights into Harbour language support implementation.

Building Plugin

Prerequisites

1. Java Development Kit 11+ - Download from Oracle or OpenJDK
2. IntelliJ Platform Plugin SDK - Automatically downloaded by Gradle

Build Steps

1. Clone the repository:

   git clone https://github.com/jo47011/intellij-harbour.git
   cd intellij-harbour

2. Verify Java version:

   java -version  # Should show Java 11 or higher

3. Build the plugin:

   ./gradlew buildPlugin  # Linux/macOS
   gradlew.bat buildPlugin  # Windows

   Note: The gradlew (Gradle Wrapper) script is included in the repository and automatically downloads the correct Gradle version.

4. Find the built plugin:

   build/distributions/harbour-language-plugin-x.x.x.zip
   

Development Setup

For plugin development, you can also run a development instance:

./gradlew runIde

This launches PyCharm with the plugin pre-installed for testing.

License

This project is licensed under the MIT License.