Annotations

Annotations attach extra information to a declaration. They are written with an @ prefix immediately above the declaration they apply to.

Annotations come in two kinds:

• Built-in attributes — recognized by the compiler and given dedicated meaning, such as @Extern for foreign-function bindings.
• Trait annotations — semantic tags such as @Override, @Implementation, and @Deprecated. User-defined traits use the same syntax.

Compile-time queries of a type or value (the maximum value of an integer, the length of a string, etc.) are written with the :: operator and the metakeyword names rather than as annotations. See Operators.

@Extern

@Extern declares that a method’s body is supplied by an external symbol — typically a C function — rather than by Cloth source. The C symbol name is given as a string argument.

@Extern("puts")
public static func $puts(string s) : void;

@Extern("strlen")
private static func $strlen(string s) : i64;

@Extern methods have no body. The signature ends with a semicolon. Calls to the method are lowered to direct calls to the named C symbol; the compiler does not generate any wrapper.

By convention, @Extern methods are named with a leading $ to make their foreign-function nature visible at every call site.

@Extern is the foundation of Cloth’s interaction with the C runtime. The standard library uses it to bind to puts, printf, strlen, calloc, and strcat, as seen in cloth.io.stream.OutputStream and cloth.lang.String.

Trait annotations

A trait annotation tags a declaration with a semantic role. The compiler reads the tag and may use it to perform additional checks or change how the declaration is processed.

Three trait annotations are built in.

@Override

@Override marks a method as overriding a member of a base class. The compiler verifies that a member with the same name and signature actually exists in the base class hierarchy. If no such member exists, the declaration is rejected.

@Override
public func toString() : string {
    return "Error: " + getMessage();
}

@Override is the recommended way to spell I am replacing the inherited implementation — the compiler catches misspellings and signature drift that would otherwise silently produce a new method instead of overriding the old one.

@Implementation

@Implementation marks a member as the implementation of an interface requirement. The compiler verifies that the named interface declares a matching member; the declaration is rejected if it does not.

@Implementation is the interface counterpart to @Override. Use it when implementing a member that an interface requires but a base class does not already provide.

@Deprecated

@Deprecated marks a declaration as deprecated. The compiler may emit a warning at every use site of the deprecated member.

@Deprecated
public func oldName() : void { ... }

@Deprecated does not change the declaration’s behavior; it merely flags it for tools and human readers.

User-defined trait annotations are introduced with the trait keyword and applied the same way. See Interfaces, Traits, and Enums for the declaration syntax.