3.1 General
A Buoy program consists of one or more source files compiled as a single program or library.
A source file contains declarations that define the program’s types, variables, constants, callable routines, and other program elements. Depending upon the declaration, executable statements may also appear within the source file.
The organization of declarations determines the visibility and lifetime of the entities they introduce.
3.2 Compilation Units
A compilation unit is the basic unit of source code accepted by the compiler.
Each source file forms a compilation unit.
During compilation, all compilation units participating in a build are parsed, analysed, and combined according to the language’s name-resolution rules.
The order in which source files are presented to the compiler shall not affect the meaning of a valid program.
3.3 Program Organization
Programs are organized through declarations.
Typical declarations include:
- constants
- variables
- functions
- subroutines
- user-defined types
- structures
- classes
- interfaces
- enumerations
- modules
Each declaration introduces one or more names into a scope.
The precise syntax of each declaration is defined in the corresponding chapter.
3.4 Scope
A scope is the region of source code within which a declared name is visible.
Every declaration introduces its name into exactly one scope.
Nested declarations create nested scopes.
When multiple declarations use the same identifier, the declaration in the innermost enclosing scope is selected.
Rules governing shadowing and name hiding are described in Chapter 5.
3.5 Declarations
A declaration introduces a program entity.
Depending upon the declaration kind, it may specify:
- a name
- a type
- modifiers
- an initializer
- attributes
- generic parameters
- visibility
Some declarations introduce executable code.
Others exist solely to define program structure.
3.6 Executable Statements
Executable statements describe actions performed when a program runs.
Statements may:
- evaluate expressions
- modify variables
- invoke functions
- control execution flow
- create objects
- terminate execution
- handle exceptional conditions
Statements appear only where permitted by the grammar.
3.7 Blocks
A block is a sequence of declarations and statements treated as a single grammatical unit.
Blocks establish nested scopes.
Variables declared within a block cease to exist when execution leaves that block.
Control-flow constructs such as conditional statements and loops typically introduce blocks.
3.8 Name Resolution
Whenever an identifier appears within a program, the compiler attempts to resolve that identifier to a declaration.
Name resolution considers:
- local declarations
- parameters
- enclosing scopes
- imported modules
- member declarations
- built-in language entities
If more than one declaration is applicable, overload resolution or ambiguity rules are applied as appropriate.
Failure to resolve an identifier results in a compile-time error.
3.9 Program Entry
Executable programs begin execution at the language-defined entry point.
The exact form of the entry point and its permitted signatures are specified in Chapter 22.
Library projects are not required to define an entry point.
3.10 Separate Compilation
Implementations may compile source files independently.
Regardless of compilation strategy, a conforming implementation shall produce the same observable behaviour as if the entire program had been analysed as a single translation.
3.11 Attributes
Declarations may be annotated with attributes that provide additional information to the compiler or to external tools.
Attributes do not alter the syntax of the language.
The semantics of individual attributes are implementation-defined unless otherwise specified.
3.12 Conditional Compilation
Buoy supports conditional compilation to enable source code to be included or excluded according to compile-time conditions.
Conditional compilation directives are processed before syntactic analysis.
The syntax and semantics of these directives are described in Chapter 25.
3.13 Summary
The structure of a Buoy program is determined entirely by its declarations.
Subsequent chapters define each declaration kind and the rules governing its visibility, lifetime, and behaviour.