Cobalt Language Reference

@C(extern)
fn puts(str: *u8);

type MyType = (i32, f32) :: {
    @getter
    @inline
    fn x(s: &self_t): i32 = {
        s.__base(0)
    };
};

fn main(): i32 = {
    let my_type = (3i32, 9.9f32) :? MyType;
    if (my_type.x == 3i32) {  # Note we don't use () to call a getter.
        puts("Success");
    } else {
        puts("Failure");
    };

    0
};

A destructor is called when (after) an instance goes out of scope, and is responsible for cleaning up memory and closing resources associated with the instance. For basic types and their derivatives, you do not need to worry about implementing this yourself.

Destructors are implemented as methods annotated with @op(drop) and accepting single &mut self_t parameter. The return type is null.

type <NAME> = <VAL> :: {
  @op(drop)
  fn my_custom_destructor(s: &mut self) = {
      # Clean up here.
  };
};

Variables are defined with the let keyword. Types are deduced, but can also be manually specified:

let x = 3i32;       # deduced type
let y: i32 = 4i32;  # explicit type

Mutable variables are marked by the mut keyword:

let mut x = 3i32;
x = 5i32;

Variables which are known at compile time can be specified using the const keyword:

const x = 5i32;

Blocks ({}) and groupings (()) can sometimes be used interchangeably, but differ in subtle ways.

Blocks contain statements and evaluate to a value (of some type). They are delimited by braces ({}). Blocks are themselves expressions. In particular, you may find that Cobalt requires semicolons after blocks where other languages do not.

# This is a block:
{
  let x = 1;

  # This is a block within a block:
  {
      let y = 2;    
  };

  let z = 3;
};  # semicolon!

Blocks are expressions with the same value as the last statement contained within them. In the above example, the last statement in the outermost block is let z = 3;. This is a non-expression statement. Recall that non-expression statements have value null and type null. On the other hand, if the last statement in the block is an expression, then the block is also an expression. In that case, the value of the block will be the value of the last expression contained within it (and the type of the value will be the type of the value of the last expression contained within it).

# x has type/value null
let x = {
  let y = 1;
};

# z has type i32 and value 5 
let z = {
  2i32 + 3i32 # uses i32 literal syntax 
};

An important property of blocks is that they introduce a new scope. This is similar to the scoping behavior in other languages.

let x = 1;

let y = {
  let z = 2;

  # x is accessible in the inner scope
  z + x
};

# z is not accessible in the outer scope

Groupings contain expressions, and are themselves expressions. Recall that every expression is a statement, but not every statement is an expression. In particular, groupings cannot contain non-expression statements.

Groupings are delimited by parenthesis (()).

# x has type i32 and value 2
let x = (
  2i32
);

# a has type/value null
let a = (
  1 + 1;
);

# y has type i32 and value 2
let y = (
  (
      2i32
  )
);

# b has type/value null
let b = (
  # the value of an expression ending with a semicolon is null
  (
      2i32
  );
);

This, however, is not valid (compare with blocks):

# Compiler error!
let x = (
  let y = 1;
);

In some cases, though, groupings and blocks can be used interchangeably.

# x has type i32 and value 2 
let x = {
  2i32  
};

# y has type i32 and value 2 
let y = (
  2i32
);

If a grouping contains no expressions, then it is an expression which evalutes to null.

# x has type/value null
let x = ();

Functions are defined as

fn <NAME>(<PARAM>*): <TYPE> = <EXPR>

where

• <NAME> is the name of the function.
• <PARAM> is a function parameter. These are described in more detail below. By <PARAM>* we mean that a function may have zero or more parameters. Each parameter must be separated by a comma.
• <TYPE> is the return type of the function. If none is specified, don't include the colon : and the return type will be assumed to be null.
• <EXPR> is an expression. Typically, this would be a block ({..}). If nothing is specified, this will default to null.

Each parameter has the form

[const|mut] <NAME>: <TYPE> [= <DEFAULT VAL>]

where

• [const|mut] means that, optionally, you can write const or mut before the type. const means the parameter is known at compile time. mut means the function can modify the parameter. If neither is specified, then you cannot change the value of the parameter.
• <NAME> is the name of the parameter, which can be used inside the function.
• <TYPE> is the type of the parameter.
• [= <DEFAULT VAL>] means that, optionally, you can provide a default value to the parameter.

Note that having a reference parameter marked as mut is not the same as that parameter having type &mut Ty. For instance, the paramaters mut arg: &i32 and arg: &mut i32 are not the same:

• In the first case, mut arg: &i32, you can reassign what is being referenced by arg but cannot mutate the underlying object.
• In the second case, arg: &mut i32, you cannot reassign what is being referenced, but can mutate the underlying object.

To call a function with a reference parameter, you can either provide a reference or a value. If you provide a value then it will be automatically converted into a reference.

fn foo(x: &i32);

fn bar(y: &i32) = {
  # Pass a reference parameter directly.
  foo(y);
};

fn main(): i32 = {
  let x = 3i32;

  # Even though we pass in a value, since the function expects a reference it 
  # will convert it to a reference for us.
  foo(x);

  0
}

Annotations can be placed above function definitions. The following options are available:

# Note both return type and body are inferred to be null.
@C(extern) fn puts(str: *u8); 

# Note the allowed paramaters to main().
fn main(argc: i32, argv: **u8): i32 = {
  puts("Hello, World!");
  0
};

type MyInt1 = i32;
type MyInt2 = MyInt1;

fn main() = {
  let x = 3i32 :? MyInt1;
  let y = x :? MyInt2;  # x moved here.

  # x is no longer valid.

  0
};

let s = "Hello, world!";

# length is 2
let s1 = "hi";

# length is 3
let s1 = "hi"c;

# signed integer with value 3 with size equal to 32 bits
let s1 = 3i32;

# unsigned integer of value 3 with size equal to that of a pointer
let s1 = 3usize;

module <NAME> {
  <TOP_LEVEL_DECLARATIONS>+
};

module MyModule {
  let my_constant = 3i32;

  fn my_function(): i32 = {
      6i32
  };
};

module MyModule {
  let my_constant = 3i32;
};

fn foo(): i32 = {
  MyModule.my_constant
};

module MyModule {
  let my_constant = 3i32;
  let my_other_constant = 5i32;
};

import MyModule.*;

fn foo(): i32 = {
  MyModule.my_constant
};

import MyModule.my_constant;

import MyModule.{my_constant, my_other_constant};