Principles

The design of the Bm Language is driven by a set of principles explained in this section. The principles were not just picked from the best-practices, they were synthesized organically from the evolution of the design of the language.

import Int from bm

let a Int = 0      // OK
let b String = ""  // ERROR! `String` is not defined

let enabled = true

class Test {
  let enabled = false  // ERROR: `enabled` is already defined
}

class User {
  var id Int  // ERROR! `id` needs to be initialized
}

let count = 0;                           // type: Int
let name = "Mat";                        // type: String
let rect = Rectangle.new(0, 0, 10, 10);  // type: Rectangle
let a = null;                            // type: Any

function main(args Array<String>) {
  if args.length == 0 {
    println("Missing arguments")
  }
}

// file: user.bm
class User {
  let id Int
  constructor new(@id Int) {
    id = @id
  }
}

// file: user.delete.bm
function User.delete() { /* ... */ }

// file: main.bm
function main() {
  User.new(10).delete();
}

function test(a Int, var b Int) {
  a += 1  // ERROR: `a` cannot be reassigned
  b += 1  // OK: it was declared with `var`
}

class Human {
  var name = "Mathison"  // It can be reassigned
}

interface Dog {
  let name String        // Cannot be reassigned
}

function test() {
  let h = Human()
  let d Dog = h          // Now it is a Dog! Not a Human
  d.name = "Amy"         // ERROR: `name` cannot be reassigned 
}

class Cat {
  let name String  // OK: initialization is delegated to the constructor
  constructor new(@name) {
    name = @name   // OK: assignment must happen only in this block
  }
}

// file: entities.bm
module entities {
  share class User {
    let key String
    constructor new(@key String) {
      key = @key
    }
  }
}

// file: storage.bm
module storage {
  share interface Item<ID> {
    let key ID
  }
  share class Container<ID> {
    function save(item Item<ID>) { 
      // It only requires something with a key so it can be saved.
    }
  }
}

// file: main.bm
import Container from storage
import User from entities
function main() {
  let container = Container<String>()
  let user = User("3e3b3142")
  container.save(user)
}

// file: entities.bm
module entities {
  share class Artist {
    var firstName String
    var lastName String
  }
}

// file: main.bm
import Artist from entities

getter Artist.fullName String {
  return "${this.firstName} ${this.lastName}"
}

function main() {
  let a = Artist(firstName: "John", lastName: "Coltrane")
  assert a.fullName == "John Coltrane"
}

import Array from bm

interface Item {
  operation gt(other Item) Bool
}

interface Sortable<T Item> {
  let length Int
  
  operation get(index Int) T

  operation set(index Int, value T)

  function bubble_sort() {
    for i = 0 while i < length step i++ {
      for j = 1 while j < (length-i) step j++ {
        if this[j-1] > this[j] {
          let aux = this[j-1]
          this[j-1] = this[j]
          this[j] = aux
        }
      }  
    }  
  }
}

compose Array<T> implements Sortable<T>

function main() {
  let items = [3, 1, 2]  // Produces an Array<Int>

  items.bubble_sort()

  assert items == [1, 2, 3]
}

Structure

Bm projects, also named Suites, can be organized using two concepts: Members and Containers. Some containers are also members and some members are flat.

The definition of the members and containers of a suite depends on the directory organization and the content of the files. All files and directories are used for defining the suite.

Suites

Suite is a Bm concept for representing projects, solutions, programs or packages. This concept is important since Bm is not designed for scripting, said in other words, the design doesn't promote having stand-alone files:

• Suites are created with a folder having at least a suite file.
• Folders inside a suite create modules, for making reference to them it is required to use the member path always relative to the suite folder.
• Sibling source files have complete access to each others members, they can be considered as a single content.

Suites can be compiled to a distributable file format containing the necessary information to be imported in other suites or executed in any platform. Only suites containing an Entry Point can be executed, however, all suites can be imported in other suites.

// main.bm
function main() {
  // program logic
}

Reference System

This system defines the rules for referencing members in the code based on the relationship between containers and members. Referencing a member doesn't guarantees the access to it, the access to the members is managed by the Access System.

Since all members have a name, containers can be viewed as a list of names and each name could contain more names since some members are containers too. This structure of names is delimited by following rules:

• A member cannot be defined in a container if the container or any of its parents have already a member with the same name, this results in Shadowing Disallowance.
• In a given container, any name defined in the container or any of its parents is available to be referenced.
• A member can be referenced by using the Member Path as long as the first name of the path is available to be referenced.
• The names defined in a container without name like source files, are assumed by its parent container.
• Given two containers with name that are siblings, the members defined in each container are not available to be referenced in each other.

                                        // Member Path:
module math {                           // "math"
  let PI = 3.141592;                    // "math.PI"
  function max(a int, b int) int {      // "math.max"
    return a > b ? a : b;
  }
  module geo {                          // "math.geo"
    function tan(value double) double { // "math.geo.tan"
      // fancy maths...
    }
  }
}

let x = 0;

class Point {
  var x = 0; // ERROR: The member "x" is already defined in the parent module.
  var y = 0;

  function moveTo(@x, y) { // ERROR: The member "y" is already defined in the class "Point".
    let Point = null; // ERROR: The member "Point" is already defined in the parent module.
  }
}

Access System

This system refers to how the members are accessed through the modules. This is controlled by using a set of keywords called access modifiers which define the rules to access to some member from a certain module.

class Foo {
  protect let BAR = 1;
}

protect let BAZ = Foo().BAR + 1; // ERROR: `BAR` is not accessible

protect let QUX = BAZ + 1; // ERROR: `BAZ` is not accessible

module abc {
  let XYZ = QUX + 1; // OK! `QUX` is accessible
}

let FOO = 1;

module bar {
  let BAZ = FOO + 1; // OK! `FOO` is accessible
}
let QUX = bar.BAZ + 1; // ERROR: `BAZ` is not accessible

module debug {
  share function log(message String) { /* ... */ }
}

module foo {
  import debug.log;

  function bar() {
    log("bar..."); // OK! `log` is accessible
  }
}

export function foo() { /* ... */ }

share function bar() { /* ... */ }

import foobar.foo; // OK! `foo` is exported
import foobar.bar; // ERROR! `bar` is not exported

Modules

A module is a container for Fields, Functions, Classes, Properties, Enums, Interfaces, Extensions and more Modules. The access to the members is determined by its module access and they are always available during the runtime.

// the member is declared in the global module of the "foobar" suite
export function doSomething() { /* ... */ }

// the global module of the library "foobar" is now "foobar"
import foobar.doSomething;

export function main() {
  doSomething();
}

module math {
  // ...
}

/some/path/
|- awesome-app/              : Global module (root directory)
|  |- math/                  : Module 'math'
|  |  |- physics/            : Module 'math.physics'
|  |  |  |- mechanics.bm
|  |  |  |- fluids.bm
|  |  \- geometry/           : Module 'math.geometry'
|  |     |- topology.bm
|  |     |- trigonometry.bm
|  |- data/                  : Module 'data'
|  |  \- local-storage.bm
|  \- main.bm

Imports

Shared and exported members can be imported into another module. The imported members become also members of the module which is importing them. To avoid adding complexity, the imported members cannot be renamed. The module access rules applies as well as any other definition, this means that the import statements can be declared with a module access modifier:

• Protected imports: are useful when it is required to use a member from another module or suite that it is not going to be widely used, so in order to use it, it must be imported in every container where is required.

  protect import math.max; // this member will only be used here
  
  export function validatePort(port Int) Bool {
    return max(port, 0);
  }
  

• Default imports: are useful to create the environment of the module by importing members that will be used in the module and submodules.

  // following members will be widely used across the module
  import assert, log, inspect from debug;
  

• Shared imports: are useful for composing a module or avoiding name collisions.

  module impl {
    // need to be shared to expose them outside this module
    share import somelibrary.log;
    share import otherlibrary.timestamp;
  }
  
  function log(message String) {
    impl.log("${impl.timestamp()} - ${message}");
  }
  

• Exported imports: are useful to re-distribute a member.

  // need to be exported so `getTypeName` can be exported as well
  export import constants.Type;
  
  export function getTypeName(type Type) String { /* ... */ }
  

module AAA {
  share class Foo { let BAR = 1; }
}

module BBB { share import AAA.Foo; }

module CCC {
  function test() {
    log(AAA.Foo.BAR); // ERROR let Foo.BAR is not shared
    log(BBB.Foo.BAR); // ERROR let Foo.BAR is not shared
  }
}

// Notice the module is the same than the owner of Foo
module AAA {
  function test() {
    log(Foo.BAR); // exactly the same than the line below
    log(AAA.Foo.BAR); // OK! it has access
    log(BBB.Foo.BAR); // OK! it has access
  }
}

module A {
  share module B {
    share let X = 1;
    share let Y = 2;
    share let Z = 3;
  }
  share module C {
    share let I = 1;
    share let J = 2;
    share let K = 3;
  }
}

module example1 {
  import A.B.X, A.B.Y, A.B.Z,
         A.C.I, A.C.J, A.C.K;
}

module example2 {
  import B.X, B.Y, B.Z
         C.I, C.J, C.K from A;
}

module example3 {
  import X, Y, Z from A.B;
  import I, J, L from A.C;
}

module example4 {
  import A.B, A.C;
}

Extensions

Extensions allow to add members to existing types without modifying the existing definition or creating a new type. The way to define extensions is by prefixing the member name with the type reference followed by two colons (::), only members with logic can be used as extensions:

• Functions
• Properties
• Constructors
• Operators

The body of the extension member, just like Class Members, has access to this representing the instance and all other instance members will be available.

class User {
  var name String = null;
}

function User::delete() {
  Console.log("Deleting user ${name}"); // OK! `name` is available
}

When an extension is defined in the same module and suite than the extended type, the extension member will be treated as a member of the type, so when the type is imported it will have the extension members available.

module lib {
  share class Collection { /* ... */ }

  share function Collection::clean() { /* ... */ }
}
module app {
  import Collection from lib;

  function test() {
    Collection().clean(); // OK! `clean` is available
  }
}

If the extension member is declared in a different module than the extended type, it needs to be imported explicitly so the type can have the extension member available.

module lib {
  share class Collection { /* ... */ }

  module actions {
    share function Collection::clean() { /* ... */ }
  }
}
module app {
  import Collection from lib;
  import User::clean from actions.lib; // this line is required for the extension
  function test() {
    Collection().clean(); // OK! `clean` is available
    clean(); // ERROR: `clean` is not defined
  }
}

Templates

Generic programming is implemented by adding a template signature to Classes, Interfaces, Lambdas, Functions and Operators. The template signature can define one or more Template Types associated with another type, when the associated type is not specified it is assumed to be Any. Template Types are considered valid types in the inner implementation.

Template Members can only be used if the Template Arguments are clear, it can happen in two ways:

• Explicit Template Arguments: Types that have a Template Signature must be referenced by using this mode which includes Classes, Interfaces and Lambdas.
• Inferred Template Arguments: Functions and Operators are referenced without arguments.

interface Comparable<T> {
  operator `==` (value! T) Bool;
}

interface Entity<ID> {
  var id Comparable<ID>;
}

class User {
  var id Int;
}

class Container<ID> {
  function store(entity Entity<ID>) { /* ... */ }
}

lambda Storer<T>(item T);

function createStorer<ID>() Storer<ID> {
  let container = Container<ID>();

  return container.store;
}

function main() {
  let store Storer<Int>  // Explicit Template Arguments
    = createStorer();    // Inferred Template Arguments
  let user = User();

  store(user);
}

Overloading

Members that accepts parameters can be overloaded, this means that more than one definition can be provided with the same name as long as the parameters at the same position are not compatibles with each other. There is no restriction on the number of parameters or if they are optional.

function print(value Any) { /* ... */ }
function print(value String) { /* ... */ }
// ERROR! `String` is compatible with `Any`.

function max(a Int, b, Int) Int { /* ... */ }
function max(a Single, b Single) Single { /* ... */ }
// OK! `Int` and `Single` are not compatibles

Extended Functions

Overriding inherited functions in classes is disallowed, however the way of adding behaviour is by using before and after.

Since in Bm is not possible to override an inherited function, an alternative might be to add aspects to the class so it can be possible to execute some block of code before or after the function is called.

Aspects should be directly added only to inherited functions to avoid obscuring the logic of normal functions.

The block of code to be executed before or after the function should not have return type, the parameters for before blocks, should be exactly the same than the target function and the parameters for after blocks, should be the same than the target function plus the return type only when it applies. In this way, aspects will be able to mutate the input and output of a function, but won't be able to change the references.

Only one aspect per before and after should be allowed in one class. The aspects added to functions which the superclasses already added aspects will be chained.

class Shape {
  var x = 0;
  var y = 0;

  function moveTo(@x Int, @y Int) {
    x = @x;
    y = @y;
  }
}

class Element {
  function redraw() { /* ... */ }
}

class Oval inherits Element, Shape {

  after moveTo(@x Int, @y Int) {
    redraw();
  }

  var width = 0;
  var height = 0;

  function draw(g Graphics) {
    g.drawOval(x, y, width, height);
  }

}

Initialization

All fields must be initialized explicitly by the developer, there is no concept of implicit default value like 0, false or null. A field can be only initialized by using one of the three ways described below.

var count = 0;
let user = User.new("Mat");

class Entity {
  let id String; // initialization delegated

  constructor new(@id String) {
    id = @id; // initial value
  }
}

function test(a String, b String = "bar") {
  // do something
}

function main() {
  // the initial values will be:
  // a = "foo" and b = "bar"
  test("foo");
}

References

In Bm all values are passed by reference, this means that if a value is passed to a function, the function is able to modify the received value without creating a copy.

There is no way to indicate that the value should be passed by value instead of reference (creating a copy), however, the compiler, depending on the platform, can decide how to pass the value based on the mutability of the value.

Null Values

TODO: Values can be null only if they are optional.

In Bm all references can be null by default no matter the type of the field, the only way to avoid null values in a field is declaring it with the non-null modifier (!) after the name. When a field has a null value, it means that the field doesn't have a valid value. If a field is declared as non-null, it is guaranteed to never hold a null value. Null value assignments to non-null fields will throw an error at runtime, compilation errors only happen if the assignment can be detected by the compiler.

Type Inference

All values' types can be inferred at compiling time, but in some cases the type has to be declared explicitly to avoid generalities or specificity. The most generic value that can be assumed is Any and the most specific will depend on the initial value.

// if the type is not specified it would be Any
var name String = null;

// if the type is not specified it would be bool
var value Any = true;

Type Casting

Type casting makes possible to treat a value as if it was of other type without creating another value. Syntax:

(TargetType)sourceValue

When the type of the source value and the target type are not compatible an error is generated.

TODO: Complete adding examples and indicating if it is generated at compiling time, runtime or both.

Natives

TODO Explain that can be implemented by the compiler, list expected natives, explain how to pass values from bm.json to runtime.

Built-in Types

Bm is not oriented to a specific platform or hardware, however, in order to operate it defines a set of native classes which are assumed to exist and can be used to create more complex types.

As well as specific classes are expected to exist, some interfaces are necessary to provide complete and decoupled support of some features of the language.

Literals

Numbers:

function main() {
  let way1 = (Byte)127;
  let way2 Byte = 127;
  let way3 = (n Byte) => {};

  way3(127);
}

Class inheritance

TODO remove multi-inheritance and allow interfaces to have defined functions (but not initialized fields)

Classes can inherit from one or more classes only following these rules:

• The constructors in the base class must be chained to one constructor of each superclass.
• A class can't define a member with a name already defined in some superclass, in other words, inherited members cannot be overridden.
• If two or more superclasses have a member with the same name it will cause an inheritance collision.

NOTE: See Type System for more details.

// represents an identifiable thing
class Entity {
  export let id String;

  share constructor new(@id String) {
    id = @id;
  }
}

// represents a record with control fields
class Record {
  export let createdAt Date;

  share var $updatedAt Date = null;

  share constructor new() {
    createdAt = Date.now();
  }

  export getter updatedAt Date {
    return $updatedAt;
  }
}

// represents the user entity record
class User inherits Entity, Record {

  protect var $name String = null;

  // must be chained to the superclasses' constructors
  export constructor new(@id String)
    : Entity.new(@id), Record.new() {}

  export getter name { return $name; }

  // non-protected superclasses' members can be accessed
  export setter name(@name String) {
    $name = @name;
    $updatedAt = Date.now();
  }
}

function test() {
  let user = User.new("0001");
  console.log(user.id);          // prints 0001
  console.log(user.name);        // prints null
  console.log(user.updatedAt);   // prints null
  console.log(user.createdAt);   // prints a Date

  user.name = "Mat";

  console.log(user.name);        // prints Mat
  console.log(user.updatedAt);   // prints a Date
}

Class Extension

TODO: Keyword extends. Only one superclass allowed. Inherits everything even the constructors.

Interface implementation

Despite it is not necessary, a class can explicitly implement one or more interfaces. The compiler will verify that the class comply with the definition of the interfaces. The interfaces specified will obbey the Interface Inheritance rules. If a function specified by an interface is not implemented, the class will be trated as Incomplete Class.

interface Drawable {
  function draw(g Graphics);
}

interface Shape {
  getter origin Point;
  getter size Size;
}

class Rectangle implements Drawable, Shape {
  export var origin Point = null;
  export var size Size = null;

  export function draw(g Graphics) {
    g.drawRect(origin.x, origin.y, size.width, size.height);
  }

  export constructor new() {}
}

class Oval {
  export var origin Point = null;
  export var size Size = null;

  export function draw(g Graphics) {
    g.drawOval(origin.x, origin.y, size.width, size.height);
  }

  export constructor new() {}
}

function test() {
  let g = Graphics.new();
  let shapes = ArrayList<Shape>.new();

  shapes.add(Rectangle.new());

  // next line is correct despite it was not explicit in the class definition
  shapes.add(Oval.new());

  for shapes : shape {
    shape.draw(g);
  }
}

Incomplete Class

Since classes can inherit from other classes, the complete definition can be delegated to subclasses. Rules:

• Only functions, getters, and setters can be defined as incomplete members.
• Classes with incomplete members can't be instantiated since the complete definition is missing.
• Classes designed to be instantiated must define all incomplete members that were inherited.

Lambda Creation

There are more than one way to create a lambda:

lambda Action();
lambda Logger(message String);
lambda Operation(a int, b int) int;

function main() {
  // receives one arguments doesn't return a result
  let log Logger = (msg) -> { /* ... */ };

  // receives two arguments a returns a result
  let sum Operation = (a, b) -> a + b;
  let div Operation = (num, den) -> {
    if den == 0 { throw Error.new(); }

    return a / b;
  };

  // no arguments, no result
  let test Action = () -> {
    log(sum(1, 2)); // 1 + 2 = 3
    log(div(3, 3)); // 3 / 3 = 1
  };

  test();
}

lambda Writer(message String);

function print(message String) { /* ... */ }

class Console {
  function log(message String) { /* ... */ }
}

function main() {
  let write1 Writer = print;
  let write2 Writer = Console().log;

  write1("test 1!");
  write2("test 2!");
}

var name = null;

getter hasName Bool {
  return name != null;
}

setter hasName(value Bool) {
  if value and name == null { name = "Default"; }
  else not value and name != null { name = null; }
}

lambda Getter() Bool;
lambda Setter(value Bool);

function test() {
  let get Getter = hasName;
  let set Setter = hasName;

  console.log(name);  // null
  console.log(get()); // false
  set(true);
  console.log(get()); // true
  console.log(name);  // "Default"
}

var version = 1;

lambda Getter() Int;
lambda Setter(value Int);

function main() {
  let getVersion Getter = version;
  let setVersion Setter = version;

  console.log(getVersion()); // 1
  setVersion(2);
  console.log(getVersion()); // 2
}

class Bag {
  operator `+` (bag! Bag) Bag {
    let merged = Bag();
    // some magic to merge both bags here
    return merged;
  }
}

lambda Merger(bag! Bag) Bag;

function main() {
  let bag = Bag();
  let merge Merger = bag.`+`;

  // both lines are equivalent:
  let r1 = merge(Bag());
  let r2 = bag + Bag();
}

Closures

Inline Lambdas can capture constant fields creating a closure.

lambda Logger(message String);

function createLogger(prefix String) Logger<String> {
  return (message) -> {
    // Notice `prefix` is captured in this lambda.
    console.log("${prefix} - ${message}");
  };
}

function test() {
  let warn = createLogger("[W]");
  let info = createLogger("[I]");

  warn("Danger! Danger!");           // [W] - Danger! Danger!
  info("Don't talk to strangers.");  // [I] - Don't talk to strangers.
}

Function Parameters

Functions can receive any number of parameters which are considered as fields available only during the function execution.

In order to improve readability, the keywords var and let are optional when declaring parameters and it is defaulted to let.

Since parameters are passed by reference, reassignments only affects the reference in the function's body.

function test(name String, var index int!) {
  name = "Mat";      // ERROR: The field can't be reasigned
  index = index + 1; // OK! the field is explicitly `var`
}

Optional parameters

Optional parameters are allowed by specifying the initial value when declaring them. Any parameter can be optional no matter the order, however, when invoking the function sending a list of arguments, optional parameters can't be skipped. The only way to skip an optional parameter is by invoking the function using Named Arguments.

It doesn't matter if the optional parameter is let or var, the initial value specified in the parameter declaration is only used when there is no value specified in the function invocation.

function write(data List<byte>, offset int! = 0, length int = null) {
  // ...
}

function test() {
  let data = [1, 2, 3];     // Optional arguments received:
  write(data);              //  offset = 0, length = null
  write(data, 1);           //  offset = 1, length = null
  write(data, 1, 2);        //  offset = 1, length = 2
  write(data, length: 2);   //  offset = 0, length = 2
}

Operator Symbols

class Vector {
  export var x = 0.0;
  export var y = 0.0;
  export var magnitude = 0.0;
  export var direction = 0.0;

  export constructor new(@x float, @y float, @m float, @d float) {
    x = @x;
    y = @y;
    magnitude = @m;
    direction = @d;
  }

  export operator + (other Vector) Vector {
    let result = Vector.new();

    // do fancy math here

    return result;
  }
}

function test() {
  let vec1 = Vector.new(0, 0, 10, 0);
  let vec2 = Vector.new(0, 0, 10, -180);
  let sum = vec1 + vec2;

  Console.log(sum); // { x: 0, y: 0, magnitude: 0, direction: 0 }
}

Conditionals

if condition1 {

}
else if condition2 {

}
else {

}

switch value {
  case A {

  }
  case B or C {

  }
  else {

  }
}

Infinite (loop)

loop {
  // do things

  if condition {
    break;
  }
}

Conditional (while)

let stack = Stack<int>.new([10, 20, 30]);

while stack.length > 0 {
  let item = stack.pop();
  console.log("item = ${item}");
}

// Output:
// item = 30
// item = 20
// item = 10

Incremental (for - while - step)

for i = 0 while i < count step i++ {
  console.log("i = ${count}");
}

// Output:
// i = 0
// i = 1
// ...
// i = 9

Iterative (for - in - else)

let list = [10, 20, 30];

for item in list {
  console.log("item = ${item}");
}
else {
  console.log("No items found");
}

// Output:
// item = 10
// item = 20
// item = 30

Literals

TODO