Section 5: Declarations

5.0 Evaluated declarations

Evaluated declarations are actually inline expressions, which can be created using the following grammar:

= expr

Not only that, the value of the evaluated expressions will also be shown on STDOUT. However, evaluated declarations will only be evaluated if they are written in the entry file, except for module imports.

For example, if we interpret the following Keli program,we shall see 120 on STDOUT.

=5.factorial

5.1 Constant declarations

Constant declarations are useful for defining common constants such as the value of pi, e, etc. They can be declared using the following grammar:

constId = expr

For example,

pi = 3.141592653

Once a constant is declared, it can be accessible anywhere within the same module (or those which imported it).

Constants cannot be reassign new values, thus the following is erroneous:

pi = 3.142
pi = 3.142
// Error: Duplicated constant identifier `pi`

5.2 Function declarations

There are two kinds of function in Keli, namely unifunc and polyfunc.

5.2.1 Unifunc declarations

Unifunc can be created using the following grammar:

unifuncSignature =expr

where:

unifuncSignature = ( paramId **typeAnnotation ) **. funcId [ | returnTypeAnnotation ]

For example,

(this Int).square | Int = this.*(this)

In the code above, the first this is the parameter for the function square , where this should be type of Int. The body of this function is this.*(this) , while the return type of this function is also Int.

Return type annotation for functions are optional (since it can be inferred), so the square function can be rewritten as :

(this Int).square = this.*(this)

5.2.2 Polyfunc declarations

Polyfunc can be created using the following grammar:

polyfuncSignature = expr

where

polyfuncSignature =( paramId typeAnnotation **) . { funcId **( paramId typeAnnotation **) } [| returnTypeAnnotation ] =

For examples:

// 2-param polyfunc
(this Int).plus(that Int) = undefined

// 3-param polyfunc
(this String).replace(sub String) with(new String) = undefined

// 4-param polyfunc
(this List.of(Int)).replace(startIndex Int) to(endIndex Int) with(new Int) = undefined

Same as unifunc, the return type annotation of polyfunc declaration is also optional.

5.2.3 Multiple dispatch

Keli supports multiple dispatch (a.k.a function overloading), thus it is possible to declare multiple function that have the same set of identifiers as long as their parameters type does not fully match.

For example, the following Keli code is valid:

(x Int).+(y Int) = undefined
(x Float).+(y Float) = undefined
(x Int).+(y Float) = undefined

Moreover, functions with overlapping identifiers are also permitted:

(x String).replace(y String) = undefined
(x String).replace(y String) with(z String) = undefined

The following code is invalid, although the parameters name are different:

(x Int).plus(y Int) = undefined
(a Int).plus(b Int) = undefined
// Error: Duplicated functions

Also, Keli does not supports multiple dispatch based on return types, so the following code is invalid despite different return types:

(x Int).plus(y Int) | String = undefined
(x Int).plus(y Int) | Int = undefined
// Error: Duplicated functions

5.2.4 Generic functions

Generic functions are functions whose parameters type are generic. We can declare generic functions using the following grammar:

{ { typeVarId typeConstraint } } ( unifuncDecl | polyfuncDecl )

typeVarId is any valid identifiers, while typeConstraint is any valid constraint expressions.

For example, the identity function can be defined as such:

{T Any}
(this T).identity | T = this

In the code above, T is the type variable identifier, while Any is the constraint on T , Any also means no constraint.

The type variable T is inferred using some sort of Hindley-Milner type inference system.

For example,

x = 123.identity // the type of `x` is inferred as `Int`
y = "Hello".identity // the type of `y` is inferred as `String`

Generic function by itself is not too useful unless incorporated with generic types such as generic objects or generic tagged union.

5.2.5 Function specialization

Function specialization is a phenomenon where multiple dispatch and generic functions are used in synergy. This feature allows a function to be specialized when specified, and generic when unspecified.

Although normal user will rarely utilize this feature, it is crucial for library author to write generic modules.

A common example is the toString function. It is a generic function, however, it may be specialized, as such:

// generic version
{A Type}
(this A).toString =
    ffi.javascript("k$this.toString()").as(String)

// specialized for integer
(this Int).toString = 
    "I'm an integer"

// usage
= "Hello".toString // "Hello"
= 123.toString // "I'm an integer"
= 1.0.toString // "1.0"

5.2.6 Docstring

Documentation for functions can be created using string expressions instead of comments. They can optionally appear:

• before the function declaration

• after each parameter

• after return type annotation

For example,

"Slices list from startIndex until including endIndex"
(this List.of(A))        "The list to be sliced."
    .
    from(startIndex Int) "Zero-based index."
    to(endIndex Int)     "Zero-based index. Inclusive."
    | List.of(A) "Return a new list." 
    = undefined

5.3 Object type alias

Object type alias (a.k.a struct types) can be created using the following grammar:

typeAliasId = objectTypeAnnotation

For example,

People = $.name(String) age(Int)

Object type alias can be used as type annotations, for example,

(this People).isOld = this.age.>(50)

Moreover, it can also be used as object constructor, as follows:

me = People.name("Keli") age(20)

5.4 Tagged unions declaration

Tagged unions (a.k.a discriminated unions OR sum types) is consists of one or more tags connected together by the .or function.

5.4.1 Tag

There are two kinds of tag, namely carryless tag and carryful tag.

5.4.1.1 Carryless Tag

Carryless tag are tags that does not carry any payload with them (like enums in C or Java). They can be created using the following grammar:

tagId

tagId are constant identifiers that follows the the PascalCase naming convention.

Example of carryless tags (note that the following piece of code is invalid, it's just for demonstration purpose):

Circle
Square
Rectangle

5.4.1.2 Carryful tag

Carryful tag are tags that carry some specific payload. They can be created using the following grammar:

tagId ( typeAnnotation )

Example of carryful tags:

Circle(Float)
Square(Float)
Rectangle($.height(Float) width(Float))

5.4.2 Unions

Tag by themselves are not useful unless they are associated with a union. A union can be created using the following grammar:

unionId = choice { . tagDecl }

unionId should follow the PascalCase convention. tagDecl is either a carryless tag or a carryful tag.

For example,

Shape = choice
    .Circle($.radius(Float))
    .Square($.side(Float))
    .Rectangle($.height(Float) width(Float))
    .None

unionId can be used as tag constructor prefix or type annotation.

5.4.3 Union name as tag constructor prefix

For example, we can use the identifier Shape to create carryless tag and carryful tag.

x = Shape.None
y = Shape.Circle($.radius(3.2))

The type of x and y are both Shape .

5.4.4 Union name as type annotation

For example, we can use the identifier Color as function parameter type annotation.

(this Shape).area | Float = undefined

5.5 Type constructor declarations

Type constructors (a.k.a generic types) are actually function that takes one or more types and return a new type. In Keli, there are 2 kinds of type constructor, namely object type constructor and tagged union type constructor.

5.5.1 Object type constructor

Object type constructor can be declared using the following grammar:

typeConstructorId . { id ( typeVarId typeConstraint ) **} = objectTypeAnnotation

For example, we can encode the tuple type as object type constructor as follows:

Tuple.fst(A Type) snd(B Type) = $.fst(A) snd(B)

In the code above, Tuple is the type constructor identifier, and it serves two purpose:

1. For constructing new Tuple

2. To be used as type annotation.

To construct a new Tuple :

myTuple = Tuple.fst("Hello") snd(123)

myTuple will be inferred to have the type Tuple.fst(String) snd(Int) .

To used Tuple as type annotation:

{A Any} {B Any}
(this Tuple.fst(A) snd(B)).swap | Tuple.fst(A) snd(B) = 
    Tuple.fst(this.snd) snd(this.fst)

5.5.2 Tagged union type constructor

Tagged union type constructor (a.k.a generic tagged union can be constructed using the following grammar:

constId . { constId ( typeVarId typeConstraint ) **} = choice {** . tagDecl ) }

For example, singly linked list can be defined as such:

List.of(A Type) = choice.
    .Nil
    .Cons($.current(A) next(List.of(A))

The identifier List can be used as:

1. Tag constructor prefix

2. Type annotation

Using List as tag constructor prefix:

x = List.Nil 
y = List.Cons($.current(1) next(List.Nil))

The type of x is List.of(A) where the type of y is List.of(Int). Due to the type inference, the following expression is invalid:

= List.Cons($.
    current(1) 
    next(List.Cons($.
        current("2") // <-- Error: Expected `Int` but got `String`
        next(List.Nil))))

Using List as type annotation:

{A Type}
(this List.of(A)).length | Int = undefined

5.6 Interface declarations

Interface are a kind of type constraint that allow user to define a set of functions on a specific type.

To define an interface in Keli, there are 3 steps required:

1. Define the name of the interface.

2. Define a set of functions required by the interface.

3. Define a set of default functions for the interface.

5.6.1 Defining interface

Interface can be defined using the following grammar:

interfaceId = **interface

Note that interface identifier should follow PascalCase convention.

For example,

Comparable = interface

5.6.2 Defining required functions

Required function can be defined using the following grammar:

{ { typeVarId interfaceId } funcSignature = required **}

where funcSignature is either a unifuncSignature or _[_polyfuncSignature](section-5-declarations.md#5-2-2-polyfunc-declarations).

Alert

To defined required function, the return type annotation cannot be omitted like usual functions do.

For example, the code below is saying that if a data type is Comparable , then it must have the == function and > function defined.

{A Type.extends(Comparable)}
(this A).==(that A) | Boolean = required

{A Type.extends(Comparable)}
(this A).>(that A) | Boolean = required

Note

The set of required functions can only be defined within the module where the interface name is defined.

5.6.3 Interface usage

Unlike object-oriented languages, where interface identifiers can be used as type annotation, interface identifier can only be used as type constraint annotations. Thus, they can only appear in generic functions or generic types.

For example,

{A Type.extends(Comparable)}
(this BinaryTree.of(A)).insert(element A) 
    | BinaryTree.of(A)
    = this.
        if(.Leaf):
            (BinaryTree.Node($.value(element) left(BinaryTree.leaf) right(BinaryTree.leaf)

        if(.Node(n)):
            (element.>(n.value).
                if(.True):
                    (n.right(.insert(element)))

                if(.False):
                    (n.left(.insert(element)))

5.6.4 Interface implementation

No special construct is needed to implement an interface, we just need to declare the required function by the interface for the specified data type.