Pragma Directives in Catnip

Catnip supports pragmas as a language keyword for fine-grained control over compilation and execution behavior.

Overview

Pragmas are runtime directives that control:

  • Tail-call optimization (TCO)
  • Caching behavior
  • Debug mode
  • Function hints (pure functions)
  • Python module imports

Syntax

pragma(directive, value)
pragma(directive, value, arg1, arg2, …)

Pragmas are statements processed during semantic analysis.

Common Pragmas

TCO (Tail-Call Optimization)

Control tail-call optimization for recursive functions.

Syntax:

# Boolean form
pragma("tco", True)       # Enable
pragma("tco", False)      # Disable

Examples:

pragma("tco", True)

# Tail-recursive factorial - no stack overflow
factorial = (n, acc=1) => {
    if n <= 1 {
        acc
    } else {
        factorial(n - 1, n * acc)
    }
}

factorial(10000)  # Works with TCO enabled

pragma("tco", False)

# For debugging - easier to trace calls
countdown = (n) => {
    if n <= 0 {
        "done"
    } else {
        countdown(n - 1)
    }
}

Feature (Import de modules)

Charger une dépendance externe dans Catnip. Fonctionne avec : - Modules Python par nom (json, math, numpy…) - Modules Python par chemin (/tmp/host.py, ./build/api.so) - Modules Catnip (.cat) via un chemin de fichier

Syntaxe :

pragma("feature", "module_name")                     # Importe un module Python du sys.path
pragma("feature", "module_name", "alias")            # Avec alias custom
pragma("feature", "/chemin/vers/module.py", "ns")    # Charge un module Python par fichier
pragma("feature", "/chemin/vers/module.cat", "ns")   # Charge un module Catnip par fichier

Exemples :

# Module Python standard (C-extension ou pur Python)
pragma("feature", "math", "m")
m.sqrt(16)

# Module Python local par chemin
pragma("feature", "/tmp/host.py", "host")
host.triple(10)

# Module Catnip local
pragma("feature", "./tools.cat", "tools")
tools.double(21)

Optimize

Control optimization level (currently minimal effect).

Syntax:

pragma("optimize", "0")  # No optimization
pragma("optimize", "1")  # Basic optimization
pragma("optimize", "2")  # Moderate optimization
pragma("optimize", "3")  # Aggressive optimization

Cache

Control caching behavior (currently minimal effect).

Syntax:

pragma("cache", True)   # Enable caching
pragma("cache", False)  # Disable caching

Debug

Control debug mode (currently minimal effect).

Syntax:

pragma("debug", True)   # Enable debug
pragma("debug", False)  # Disable debug

Examples

Full Example with Multiple Pragmas

pragma("tco", True)
pragma("feature", "json")
pragma("feature", "math", "m")

# TCO-optimized fibonacci
fib = (n, a=0, b=1) => {
    if n == 0 {
        a
    } else {
        fib(n - 1, b, a + b)
    }
}

# Use imported modules
result = dict(
    ("fibonacci", fib(100)),
    ("sqrt", m.sqrt(100)),
    ("data", json.dumps(list(1, 2, 3)))
)

result

Conditional TCO

# Enable TCO for production
pragma("tco", True)

sum_range = (n, acc=0) => {
    if n <= 0 {
        acc
    } else {
        sum_range(n - 1, acc + n)
    }
}

sum_range(100000)  # No stack overflow with TCO

Implementation Notes

  • Pragmas are implemented as a language keyword (pragma)
  • Processed during semantic analysis in semantic/analyzer.py
  • Stored in PragmaContext accessible via context.pragma_context
  • TCO pragma affects function execution in nodes_core.pyx
  • Feature pragma imports Python modules via importlib

See Also