CobaltC Programming Language Specification 1.0.0

1. Introduction CobaltC is a statically typed systems programming language providing: explicit ownership; deterministic destruction; compiler-checked borrowing; inferred lifetimes; explicit nullability; bounds-safe operations; structured error handling; safe concurrency; explicit unsafe operations; explicit foreign-function interfaces. The language is intended for software requiring predictable resource management, strong memory safety, native execution and controlled interaction with low-level facilities. CobaltC does not require tracing garbage collection. 2. Normative Terminology The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative. Implementation-defined means that an implementation chooses the behavior and documents that choice. Undefined behavior is behavior for which this specification imposes no requirements. Safe CobaltC operations MUST NOT introduce undefined behavior merely through ordinary use. 3. Source Files A CobaltC program consists of one or more source modules. Source text is Unicode. Identifiers are case-sensitive. Whitespace separates lexical tokens where necessary and otherwise has no semantic meaning. 4. Comments CobaltC supports line comments: // comment and block comments: /* comment */ Comments have no semantic effect. 5. Keywords The following are reserved: as break case const continue defer else enum extern false fn for if import in interface loop match move mut null return static struct true type unsafe while let is not a CobaltC 1.0 keyword. 6. Identifiers An identifier begins with a Unicode identifier-start character and may contain subsequent identifier characters and digits. Identifiers are case-sensitive. The following therefore represent distinct names: value Value VALUE 7. Literals CobaltC provides: integer literals; floating-point literals; character literals; string literals; Boolean literals; null. Numeric literals MAY use separators where supported by the implementation, provided separators do not alter their value. 8. Modules A module declaration has the form: module example; A module establishes a namespace. Modules MAY import declarations from other modules: import io; Name resolution is lexical and module-aware. An unresolved name is a compile-time error. 9. Declarations CobaltC provides: const static type struct enum interface fn Declarations are introduced into their applicable lexical or module namespace. Inner declarations MAY shadow outer declarations where permitted. 10. Variables A variable is declared using: i32 count = 0; A mutable variable is declared: mut i32 count = 0; An uninitialized declaration is permitted: i32 result; but result MUST be initialized before it is read. 11. Constants Constants use: const i32 maximum = 100; A constant initializer MUST satisfy the implementation's constant-expression requirements. A constant cannot be mutated. 12. Primitive Types CobaltC defines: bool char i8 i16 i32 i64 i128 u8 u16 u32 u64 u128 isize usize f32 f64 The fixed-width integer types have exactly their specified widths. isize and usize are pointer-sized integer types. 13. Compound Types CobaltC supports: structs enums tuples arrays function types managed references raw pointers generic types interface-constrained types Structs and enums are nominal types. Type aliases do not create new nominal types. 14. Managed References The notation: T* represents a managed non-null reference. The notation: T*? represents a nullable managed reference. Managed references participate in ownership, borrowing and lifetime checking. 15. Raw Pointers Raw pointers are represented: raw T* Raw pointers are outside the ordinary managed ownership and lifetime guarantees. Raw-pointer dereference and unrestricted pointer manipulation require an unsafe context. 16. Mutability A mutable binding permits mutation through that binding where no ownership or borrowing rule prohibits the operation. Mutability does not override aliasing rules. For example, having a mutable owner does not permit mutation while an incompatible borrow remains active. 17. Type Compatibility Assignments, function arguments and return values MUST have compatible types. Implicit conversions MUST NOT silently: remove nullability; create ownership; destroy ownership; violate mutability; invalidate a lifetime guarantee; perform unsafe reinterpretation. Explicit conversion facilities MAY be provided. 18. Type Inference CobaltC permits inference where the language grammar and context establish a unique type. Inference MUST preserve all semantic distinctions relevant to: ownership; mutability; nullability; borrowing; lifetime. Inference MUST NOT make an unsafe operation appear safe. 19. Generic Types Generic types and functions are statically checked. Example: fn identity<T>(T value) -> T { return value; } Generic constraints MUST be satisfied before a generic entity is used. 20. Interfaces Interfaces define required operations. Example: interface Printable { fn print(); } A generic constraint may require an implementation: T: Printable The compiler MUST verify that required interface operations exist. 21. Structs A struct defines a nominal aggregate: struct Point { i32 x; i32 y; } Struct fields have declared types. Owned fields participate in the enclosing value's ownership and destruction semantics. 22. Enums An enum defines a finite set of variants: enum Status { Ready, Running, Failed } Variants MAY contain associated values: enum Result<T,E> { Ok(T), Err(E) } 23. Tuples Tuples combine a fixed number of values. Tuple elements are independently typed. Tuple ownership follows the ownership rules of their elements. 24. Arrays Arrays contain a fixed number of elements: T[N] The length is part of the array type. Safe indexing MUST remain within the valid range. 25. Functions A function is declared: fn add(i32 a, i32 b) -> i32 { return a + b; } The number and types of arguments MUST match the function signature. Ownership and borrowing requirements apply to arguments and return values. 26. Expressions Expressions produce values or perform operations. The core expression categories include: names; literals; calls; construction; member access; indexing; borrowing; unary operators; binary operators; assignment. 27. Operator Precedence From highest to lowest: Level Operators 1call, indexing, member access 2!, unary +, unary -, move, borrow 3*, /, % 4+, - 5<<, >> 6<, <=, >, >= 7==, != 8& 9^ 10| 11&& 12|| 13assignment Binary operators are left-associative unless otherwise specified. Assignment is right-associative. 28. Arithmetic Integer and floating-point operations follow the semantics of their respective types. An operation that cannot safely produce the required result MUST follow the type's specified overflow or failure semantics. Safe arithmetic MUST NOT silently produce memory corruption. 29. Equality Equality requires compatible operands. Value equality compares values according to the type's equality semantics. Where pointer identity is explicitly requested, pointer equality compares identity rather than recursively comparing referents. 30. Assignment Assignment requires a valid mutable destination. Compound assignment follows the corresponding arithmetic or bitwise operation. Assignment does not implicitly transfer ownership unless the operation constitutes a move. 31. Function Calls A call is valid only if: the function is resolvable; the argument count is correct; arguments have compatible types; ownership transfers are valid; borrows remain valid; generic constraints are satisfied. 32. Conditional Execution CobaltC provides: if condition { ... } else { ... } The condition MUST satisfy the Boolean condition requirements. 33. Loops CobaltC provides: while for loop break exits the applicable loop. continue begins the next iteration. 34. Match Pattern matching is provided by match: match value { Some(x) => use(x), None => use_default() } A match over an exhaustively known variant set MUST handle every possible case. The compiler MUST reject statically non-exhaustive matches. 35. Return return transfers control from the current function. Returning an owned value transfers ownership to the caller. Returning a reference is permitted only if its lifetime remains valid after the function returns. A reference to an ordinary local variable MUST NOT be returned. 36. Defer defer schedules work for scope exit: { defer { close_resource(); } use_resource(); } Deferred blocks execute in reverse registration order. Deferred operations themselves obey ordinary ownership and lifetime rules. 37. Definite Initialization A value MUST be initialized before it is read. The compiler MUST perform control-flow-sensitive definite-initialization analysis. This is invalid: i32 value; if condition { value = 10; } print(value); unless the compiler can prove that every path reaching print initializes value. 38. Ownership Ownership is a fundamental part of CobaltC's type and runtime model. An owned value has one responsible owner unless its type explicitly implements shared ownership. The owner is responsible for eventual destruction. 39. Move Semantics A move transfers ownership. File a = open("data.txt")?; File b = move a; After the move, a MUST NOT be used as an owner of the transferred value. A moved-from binding MAY remain in scope, but its moved value is unavailable except as permitted by explicitly defined partial-move rules. 40. Copy Semantics A type may support copying. Implicit copying is permitted only when the type's semantics explicitly permit it. Copying produces an independent value according to the type's copy contract. Copying is not ownership transfer. 41. Partial Moves For aggregate values, an individual owned component MAY be moved independently when the compiler can track the resulting state. A moved component cannot subsequently be used through its original ownership path. Unaffected independent components MAY remain usable. 42. Borrowing A borrow provides access without transferring ownership.