Imported from Ganbin/4d-development-skill (SKILL.md). Install upstream with npx skills add Ganbin/4d-development-skill. Copyright stays with the author.

4D Development Expert (v21)

Skill Version

• 4D Version: v21
• Skill Version: 1.0
• Docs: Full official 4D v21 documentation embedded in docs/ (3,387 files)

This skill targets 4D v21 specifically. Do not assume features from other versions exist unless verified in the embedded documentation.

How to Use This Skill

CRITICAL: For any 4D task, ALWAYS prefer reading the embedded documentation files (docs/) over relying on training data. The docs/ folder contains the authoritative 4D v21 reference.

Workflow:

1. Check this file for critical rules and routing
2. Read the relevant references/ file for curated knowledge and patterns
3. If more detail is needed, read the specific docs/ file pointed to by the reference
4. For edge cases, use grep to search across docs/
5. Only fall back to training data if docs/ doesn't cover the topic

Priority reading: Always check references/manual-insights.md — it contains real-world corrections from code reviews that override documentation.

Local Conventions

Before providing 4D guidance, check if a local/ directory exists in this skill folder with project-specific conventions:

ls local/*.md 2>/dev/null

If files exist, read them first. The local/ directory (gitignored) can contain:

• Company-specific naming conventions and documentation standards
• Project-specific database schemas
• Version overrides (e.g., if project uses 4D v19.2 instead of v21)

Critical Syntax Rules

These are the most common sources of bugs in 4D code. Know them by heart.

1. Assignment vs Comparison

// WRONG: = is comparison, returns True/False
$name = Request("Enter name")        // Compares, doesn't assign!
If ($input = Request("Name"))        // WRONG: compares, doesn't assign

// CORRECT: := is assignment
$name:=Request("Enter name")        // Assigns
$input:=Request("Name")
If ($input # "")                     // Then compare separately

Rule: := assigns. = compares. Never mix them.

2. Object Properties Are Case-Sensitive

// Variables: case-INSENSITIVE
$MyVar:="test"
$myvar:="changed"            // Same variable!

// Object properties: case-SENSITIVE
$obj.Name:="John"
$obj.name:="Jane"            // Different properties!

3. Collection vs Array Indexing

// Collections: 0-based
$col:=New collection("A"; "B"; "C")
$first:=$col[0]              // "A"

// Arrays: 1-based with special element zero
ARRAY TEXT($arr; 3)
$arr{1}:="A"                 // First element
$arr{0}:="default"           // Special element zero

4. Null Queries Require Literal Syntax

// WRONG: Null as placeholder doesn't work
$result:=ds.Users.query("email = :1"; Null)

// CORRECT: literal null in query string
$result:=ds.Users.query("email = null")
$active:=ds.Users.query("email != null")

5. Linked Collection Queries

// WRONG: conditions can match DIFFERENT collection elements
ds.Users.query("projects[].status = 'active' AND projects[].budget > 1000")

// CORRECT: [a] links conditions to the SAME element
ds.Users.query("projects[a].status = 'active' AND projects[a].budget > 1000")

6. Numeric Object Properties Are Always Real

$obj:=New object("count"; 5)
Value type($obj.count)  // Returns Is real, NEVER Is longint

7. Decimal Separator Is Always Period

$price:=19.99    // CORRECT — always period
$price:=19,99    // WRONG — two separate numbers!

8. 4D has a strict left-to-right precedence

if ($length > 1+$i) // Runtime error: $length>1 -> true -> true+$i -> error
if ($length > (1+$i)) // No error

$result:=3+4*5 // 35
$result:=3+(4*5) // 23

Quick Decision Router

By Task

By Error / Symptom

Docs Navigator

The docs/ folder contains the full official 4D v21 documentation (3,387 files, 48MB). Use this section to find the right file.

Category Quick Lookup

Search Patterns

When you need to find something specific across docs/:

# Find a command by name
grep -rl "title: CommandName" docs/commands/ docs/commands-legacy/

# Find a class method
grep -rl "\.methodName" docs/API/

# Find usage of a specific function
grep -rl "functionName" docs/ --include="*.md"

# Find a form event
ls docs/Events/on*.md

# Find a form object type
ls docs/FormObjects/*_overview.md

# Find a REST endpoint
ls docs/REST/\$*.md

# Find settings for a topic
grep -rl "keyword" docs/settings/

# Find a legacy command by theme
grep -rl "CommandName" docs/commands/theme/

Index Files

For structured navigation of large categories, read these generated indexes:

Reference Files Guide

Curated Knowledge (hand-written, with code examples)

Common Workflows

New Feature Development:

1. orda-modern.md for architecture patterns
2. query-patterns.md for database operations
3. error-handling.md for robust error management
4. Specific docs/API/ files for class method details

Legacy Code Maintenance:

1. classic-patterns.md for understanding legacy code
2. orda-modern.md for modernization options
3. language-syntax.md for syntax questions

Debugging:

1. Check Critical Syntax Rules above first
2. language-syntax.md for syntax errors
3. data-types.md for type errors
4. query-patterns.md for query issues
5. manual-insights.md for known gotchas

Web/REST Development:

1. web-and-rest.md for server and REST patterns
2. orda-modern.md for exposed functions
3. rest-index.md for specific endpoint docs

External Resources

When the embedded docs don't cover your case:

• Official docs: https://developer.4d.com/docs/
• Community forum: https://discuss.4d.com/
• Blog (feature deep-dives): https://blog.4d.com/
• GitHub depot (code examples): https://github.com/4d-depot