Skip to content

Annotations

Annotations in Blossom provide metadata that instructs the compiler to perform specific actions or apply certain rules during compilation. They offer a powerful way to control the compilation process and add extra context to your code.

%module

The %module annotation declares the module to which the current file belongs. Each file in a Blossom project must belong to a module. Modules provide namespacing and control the visibility of entities (functions, types, etc.).

Syntax

blossom
%module ModuleName

Where ModuleName is a literal representing the name of the module.

INFO

Module names should follow PascalCase (e.g., MyModule, DataProcessing, UserAuthentication).

%import

The %import annotation imports a module, making all its public entities (functions, types and constants) available for use in the current module through qualified access (ModuleName.entity).

Syntax

blossom
%import ModuleName           // Import the module
%import ModuleName as Alias  // Import the module with an alias

Example

blossom
%module MainApp

%import Math              // Import Math module
%import DataUtils as Data // Import with alias

Main -> {
    // Only public members can be accessed
    result1: Integer = Math.Add(5, 3)
    result2: Integer = Math.Subtract(10, 4)
    result3: String = Data.FormatData("test")

    "{result1}, {result2}, {result3}"
}

The compiler will perform dead code elimination to remove any unused entities during compilation, ensuring that only the necessary code is included in the final output.

WARNING

The visibility of module members is controlled by their declarations within the module.

Private members cannot be accessed from outside the module, regardless of how the module is imported.

%using

The %using annotation makes specific public functions or entire modules available in the current scope without requiring module name prefixes. Only public functions and types can be imported - private module members cannot be accessed through %using.

Syntax

To use a single entity from a module:

blossom
%using Math.SquareRoot

To use multiple entities from a module:

blossom
%using Math.[Sine, Cosine]

Example

blossom
%module Calculator

%using Math.[Sine, Cosine]

Add :: (x: Integer, y: Integer) : Integer -> {
    Sine(x) + Cosine(y)
}

WARNING

Attempting to use private module members will result in a compile-time error.

%public

The %public annotation marks all entities (functions, types, constants) in the current module as public. This is useful for modules that are designed to be entirely public-facing, avoiding the need to prefix each declaration with +.

Example

Instead of:

blossom
%module Math

+PI := 3.14159
+E := 2.71828

+Add :: (x: Float, y: Float) : Float -> x + y
+Subtract :: (x: Float, y: Float) : Float -> x - y
+Multiply :: (x: Float, y: Float) : Float -> x * y
+Divide :: (x: Float, y: Float) : Float ! @DivisionByZero -> {
    match y -> {
        0 -> throw @DivisionByZero
        _ -> x / y
    }
}

+Point := (Float, Float)
+Vector := (Float, Float, Float)

You can write:

blossom
%module Math
%public

PI := 3.14159
E := 2.71828

Add :: (x: Float, y: Float) : Float -> x + y
Subtract :: (x: Float, y: Float) : Float -> x - y
Multiply :: (x: Float, y: Float) : Float -> x * y
Divide :: (x: Float, y: Float) : Float ! @DivisionByZero -> {
    match y -> {
        0 -> throw @DivisionByZero
        _ -> x / y
    }
}

Point := (Float, Float)
Vector := (Float, Float, Float)

-InternalHelper :: (x: Float) : Float -> x * 2  // Still private despite %public

Note: You can mark specific entities as private by prefixing them with - in a public module.