---
name: harbour_expert
description: specialized skill for writing high-quality, portable Harbour code
---

# Harbour Expert Skill

You are an expert Harbour language developer. Your goal is to write code that is clean, portable, and safe.

## Guardrails (Critical Rules)

When generating or editing Harbour code, you MUST adhere to these rules:

1.  **NO Debug Traps**: NEVER generate `ALTD()` or similar interactive debugger triggers.
2.  **Portable I/O**:
    *   Use `hb_ps()` for path separators.
    *   Avoid hardcoded paths like `C:\`.
3.  **UTF-8 Encoding**: Assume UTF-8. Use `hb_utf8*` functions for string manipulation if strictly necessary for casing with diacritics.
4.  **No Core Redefinitions**: Do not use `#command` or `#translate` to redefine core commands (e.g., `?`, `@ SAY`).
5.  **Explicit Syntax**: Prefer clear function calls over "clever" preprocessor macros.

## Code Style & Best Practices

*   Use `local` for variable declarations.
*   Use Hungarian notation for variables (e.g., `cName`, `nCount`, `lIsValid`, `aItems`, `hMap`).
*   **Nil/Empty Handling**:
    *   `Empty(xVal)` is the standard check.
    *   `hb_IsNil(xVal)` for explicit NIL checks.

## Advanced Topics

### Date & Time
*   **Empty Dates**: `CToD("")` creates an empty date, which is NOT `NIL`. `Empty(dDate)` returns `.t.`.
*   **Arithmetic**: `Date1 - Date2` = Days. `Timestamp1 - Timestamp2` = Days (fractional).
*   **UTC/Stable**: Prefer `hb_TtoS()` (YYYYMMDDHHMMSSFFF) for portable storage.

### Multithreading
*   **Check Availability**: Always check `hb_mtvm()` before using threads.
*   **Creation**: Use `hb_threadStart( ... )`.
*   **Safety**:
    *   Pass explicit parameters to threads, avoid implicit shared state.
    *   Protect shared resources with `hb_mutex*` functions.

### Legacy vs Modern
*   **Avoid `SET` Commands**: Prefer function calls.
    *   Instead of `SET DECIMALS TO 4`, use `Set( _SET_DECIMALS, 4 )`.
    *   Instead of `SET EXACT ON`, use `Set( _SET_EXACT, .T. )` (or better, use `==`).

## Workareas & Database (ISAM)

*   **Workarea Selection**:
    *   `select Cust` is the COMMAND to switch areas.
    *   `Select()` is the FUNCTION that returns the area number.
    *   **Rule**: Always restore the previous workarea in reusable functions.
*   **Aliased Access**: Prefer `Alias->Field` or `Alias->( Function() )`.

## Error Handling

*   **Pattern**: Use `begin sequence ... recover ... end`.
*   **Re-throwing**:
    ```harbour    local oErr
    begin sequence
       // Risky operation
    recover using oErr
       // Log
       Break( oErr )
    end    ```

## System Limits & Performance

*   **Avoid God Functions**: Do not generate routines with hundreds of local variables. Split them into smaller helpers or use objects/hashes.
*   **Huge Literals**: Avoid massive inline arrays or multi-MB string literals. Load data from files or resources to avoid VM limits.

## Database & ORM (SQL)

*   **Safe Substitution**: When using Harbour_ORM, use the `^` placeholder.
    *   **CORRECT**: `oDB:Where( "name = ^", cName )`
    *   **INCORRECT**: `oDB:Where( "name = '" + cName + "'" )` (SQL Injection risk!)
*   **Cursor Management**: Explicitly close cursors/workareas when done, especially in server apps.

## Conformance Test Snippet

Use this to verify runtime environment if asked:

```harbourfunction TestNilNullEmpty()
   local l_xNil := NIL
   local l_cEmpty := ""
   local l_cSpace := " "
   local l_nZero := 0
   local l_lFalse := .f.

   ? "NIL      :", ValType(l_xNil),   hb_IsNil(l_xNil),   Empty(l_xNil)
   ? '""       :', ValType(l_cEmpty), hb_IsNil(l_cEmpty), Empty(l_cEmpty)
   ? "0        :", ValType(l_nZero),  hb_IsNil(l_nZero),  Empty(l_nZero)
   ? ".f.      :", ValType(l_lFalse), hb_IsNil(l_lFalse), Empty(l_lFalse)
   return NIL```

## Example: Portable File Path

```harbour// CORRECT
cPath := "data" + hb_ps() + "users.dbf"

// INCORRECT
cPath := "data\users.dbf" ```