Custom Annotations & Scope Injection

Flame empowers systems engineers to declare custom annotations using the annotation keyword. Annotations in Flame are first-class runtime and compile-time constructs: they accept typed parameters, execute initialization logic, and return data that is automatically injected directly into the decorated function’s local scope.

---

1. Defining Custom Annotations

Important Naming Convention

Custom annotations must begin with an uppercase letter (e.g., Logger, not logger). The compiler enforces this via a mandatory lint rule to ensure annotations remain easily distinguishable from standard functions.

You define custom annotations using the annotation keyword, specifying parameters and an explicit return type:

// Declare an annotation that returns a formatted logger prefix string
export annotation Logger(prefix: String) -> String {
    return $"[{prefix}] "
}

// Declare an annotation that initializes a route configuration formula
export annotation Route(method: String, path: String) -> Formula {
    return formula {
        method: method,
        path: path,
        timestamp: 1785940000
    }
}

---

2. Automatic Value Injection into Functions

When you decorate a function with a custom annotation, Flame evaluates the annotation at runtime and automatically injects the returned value directly into the function’s local scope as a mutable variable named after the annotation (accessible via lowercase or PascalCase):

@Logger("AUTH_SERVICE")
fn authenticate_user(username: String) {
    // 'logger' (or 'Logger') is automatically available in local scope from @Logger!
    print(logger + "Authenticating user: " + username)

    // The injected variable is mutable and can be dynamically modified in scope
    logger = logger + "[SECURE] "
    print(logger + "Access granted.")
}

authenticate_user("admin")

Output:

[AUTH_SERVICE] Authenticating user: admin
[AUTH_SERVICE] [SECURE] Access granted.

---

3. Mutable State & Complex Formula Injection

Custom annotations can return complex formulas, structs, or state containers, making them invaluable for middleware pipelines and contextual dependency injection:

export annotation Context(service_name: String) -> Formula {
    return formula {
        service: service_name,
        request_count: 0
    }
}

@Context("PAYMENT_GATEWAY")
fn process_transaction(amount: Float) {
    // Access formula properties directly from the injected 'context' variable
    context.request_count += 1
    print($"Service: {context.service}, Requests: {context.request_count}, Amount: ${amount}")
}

process_transaction(99.95)

Scope Variable Naming

When decorating a function with @MyAnnotation(...), the evaluated return data is immediately accessible inside the function body via myannotation, MyAnnotation, or __MyAnnotation_data__.

---

4. Metaprogramming with std.annotation & AnnotationContext

Flame provides a metaprogramming standard library module (std.annotation) enabling custom annotations to inspect targets, retrieve callable references, and dynamically transform or wrap functions.

Full Standard Library Reference

For more details, complete struct definitions, and advanced use cases, see the std.annotation Standard Library Documentation.

Accessing AnnotationContext

Inside any custom annotation body, call annotation.context() to retrieve structured context:

import std.annotation

annotation Route(path: String) {
    let ctx = annotation.context()

    // Access target declaration metadata:
    let name = ctx.target.name              // String (e.g. "get_users")
    let kind = ctx.target.kind              // String: "function", "struct", "enum", "variable"
    let params = ctx.target.parameters      // [ParameterInfo]
    let ret = ctx.target.return_type        // String
    let annos = ctx.target.annotations      // [AnnotationInfo]

    // Inspect compiler & build configuration:
    let compiler = ctx.compiler.name        // "flame"
    let platform = ctx.build.platform       // e.g. "linux", "darwin", "windows"
    let arch = ctx.build.arch               // e.g. "x86_64", "aarch64"
}

Declaration Boundary Enforcement

annotation.context() is strictly restricted to custom annotation declarations. Invoking it outside an annotation body produces a compile-time typechecker diagnostic error and panics at runtime.

Obtaining Target Function References (ctx.target.ref())

For web frameworks, dependency injection, and router dispatchers, ctx.target.ref() yields a callable reference to the annotated function:

let routes: [Formula] = []

annotation GET(path: String) {
    let ctx = annotation.context()
    let handler = ctx.target.ref()

    routes.push(formula {
        method: "GET",
        path: path,
        handler: handler
    })
}

@GET(path = "/api/v1/health")
fn health_check() -> String {
    return "ok"
}

// Router execution:
let res = routes[0].handler() // returns "ok"

Transforming Functions (ctx.target.transform())

Custom annotations can wrap, intercept, or modify the execution of the target function using ctx.target.transform:

annotation Logged {
    let ctx = annotation.context()

    // Wrap the target with an interceptor closure receiving the original ref and arguments:
    ctx.target.transform(
        (ref, text: String) {
            print($"[LOG] Calling {ctx.target.name} with: {text}")
            let result = ref(text)
            return $"[LOGGED: {result}]"
        }
    )
}

@Logged
fn greet(name: String) -> String {
    return $"Hello, {name}!"
}

greet("Flame") // Prints log and returns "[LOGGED: Hello, Flame!]"

---

5. Built-in Annotations & CLI Synthesis

Flame also comes packed with native annotations for testing (@Test, @Setup, @Cleanup, @ExpectPanic) and declarative CLI building (@Cli, @Command).

To learn how to use @Cli and @Command to assemble powerful interactive system utilities and subcommands with zero boilerplate, visit the comprehensive reference on Built-in Annotations & CLI Builder.