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
%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
%import ModuleName // Import the module
%import ModuleName as Alias // Import the module with an alias
Example
%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:
%using Math.SquareRoot
To use multiple entities from a module:
%using Math.[Sine, Cosine]
Example
%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:
%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:
%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.