Wafl Tutorial

Wafl is a strongly typed functional programming language with implicit type inference. It was originally designed as an experimental application of FP languages in web development. A few years later, however, Wafl became a simple and very fast scripting language, with a simple and efficient interface to databases.

The Wafl Tutorial introduces the language constructions, the use of the command line interpreter, elements of the core library and many examples.

Welcome to Wafl!

Saša Malkov

1 Introduction

This introductory chapter covers the basic elements of Wafl syntax and the use of the command line interpreter. The aim is to provide some basic information that will enable us to progress further in the following chapters.

1.1 Command Line Interpreter

For most of this tutorial, we assume that you are using the Wafl command line interpreter. The name of the command line interpreter may vary depending on the installation package version. It can be clWafl, clwafl, wafl, or simply wl. In this tutorial we assume that it is called clwafl.

To check if the interpreter is ready, open the OS command shell and type:

clwafl

If everything is set up correctly, the output should look like this:

*** Program filename missing!
*** Wafl Command Line Interpreter usage syntax:
    clwafl [<options>] <program file name> [<arguments>]
    clwafl [<options>] -code <source code> [-args <arguments>]
    clwafl -help

We assume that each program is written and saved in a file and then evaluated with the command line interpreter. To evaluate a program stored in example.wafl, enter and execute:

clwafl example.wafl

Command line interpreter options are discussed in details in Command Line Reference.

1.2 Hello World

The easiest way to display the string "Hello World!" is to write a program that consists only of this string:

"Hello World!"

Hello World!

If you write this program and save it as a new file with the name “hello.wafl”, you can evaluate it with the Wafl command line interpreter:

clwafl hello.wafl

If everything is set up correctly, the output should look like this:

Hello World!

1.3 Main Wafl Concepts

Wafl is a strongly typed and eager functional programming language with implicit type inference.

Let us discuss the first sentence in detail.

Wafl is a functional programming language. A Wafl program has the syntactic form of an expression. In imperative programming we speak of the execution of a program, but here we speak instead of the calculation or evaluation of a program. The order of program execution is not explicitly determined by the program source file, but by implicitly defined rules for the evaluation of expressions.

Wafl is not a pure functional language. There are some language features that violate the strict rules of the functional paradigm, including the command line interaction subsystem, the use of files and databases, and so on. However, the core of the language is defined in such a way that we can speak of a large pure subset. Most of the examples in this tutorial use only the pure subset of the language. Impure elements are generally limited to some elements of the core library.

There are almost no variables, assignments, iterations, procedures, or other elements common in imperative programming languages. Even if there are some types of these concepts, they are not present in the usual imperative form.

The order of evaluation is not important in most cases, but where it is important, it can be assumed that all arguments of functions and operators are evaluated from left to right.

Wafl is an eager language. This means, in short, that for most functions (and operators) all arguments are fully evaluated before the function (or operator) is evaluated. There are some common exceptions, such as logical operators and conditional expressions.

However, there are also some lazy elements. The most important lazy subsystem is the processing of database queries. The query results are not retrieved completely before the query results are processed. Instead, the query result is treated as a lazy list of rows. Individual rows of the query result are retrieved as needed.

Wafl is a strongly typed programming language. Each program is completely analyzed and type-checked before evaluation. No type-related errors can occur during program evaluation. However, the Wafl syntax does not contain an explicit type specification. All types are implicitly inferred. Normally, the derived types are not displayed during the evaluation, but if a type error is detected during type checking, the corresponding derived types are reported to support problem localization.

1.4 Introduction to the Types

To understand function type notation, we first need to understand type notation in general. This requires at least a small introduction to the Wafl type system. For exact types the notation is relatively simple, but for polymorphic types it can be more complex.

Wafl supports implicit polymorphism. This means that each function has a strictly defined type, but is as general as possible so that it works for all types to which its definition can apply. For example, we can define a function add3:

add3(x,y) = x + y + 3;

This is a definition of the function add3. It is easy to verify that add3 can only work for integer arguments (because no implicit conversions are allowed and we have an explicitly specified integer argument: 3). We can write the type of this function as follows:

(Int * Int -> Int)

Function types are always enclosed in parenthesis. This type indicates that the function has two arguments of type Int and the result of the same type Int.

Let us now define a function add:

add(x,y) = x + y;

The function add can work for all types for which its definition expression can be evaluated correctly. This includes all types for which the binary operator ‘+’ is defined. In Wafl, these are the primitive types: Integer, Bool and String. The function add therefore has a polymorphic type that includes the exact types (Int * Int -> Int), (Float * Float -> Float) and (String * String -> String). To simplify the notation, we use the parameterized notation:

(Value['1] * Value['1] -> Value['1])

The Value represents a particular set of types (Int, Float, String) and Value['1] represents an instance of the set, where '1 is a type parameter (or type variable). Type parameters take the form of a quotation mark followed by an integer. A type parameter can represent any type that fits the context (i.e. any type from the given set), but the same type in the entire type notation. In this example, '1 is one of the types in the set Value - Int, Float or String, but the same in all three occurrences.

So, if we replace '1 with specific types, one by one, then our type (Value['1] * Value['1] -> Value['1]) virtually becomes a set of types that includes: (Int * Int -> Int), (Float * Float -> Float) and (String * String -> String).

Now, we agree that it was almost more complicated to explain this than to use the set of types. But there are sets that are too large to be written without a special polymorphic notation. For example, if we have a polymorphic list of elements, then its type is denoted as List['1], where '1 denotes the element type and can be any type that Wafl supports. Thus, List['1] represents an infinite set of types.

Let us write a function that checks if a list is longer than a given number:

isLongerThan( list, n ) = size( list ) > n;

First, we know that size is a core library function that returns Int, so n must also be of type Int. The expression of the function definition evaluates to a Bool value, so we conclude that our function will have a type like (... * Int -> Bool). And what is the type of the first argument?

In our example, we expect a list as the first argument, but there are no any implications for its element type. Then it will be a polymorphic list List['1], and the function type will be: (List['1] * Int -> Bool).

But size works not only for lists, but also for arrays. To consider all sequence types (lists and arrays), the function type must be more general:

(Sequence['2]['1] * Int -> Bool

where '2 stands for a sequence type (array or list) and '1 for a sequence elements type.

In addition, size also works for strings. Strings often behave like sequences of characters (even though there is no new type for characters - String is used), so we have a more general type class SequenceStr that includes arrays, lists and strings:

(SequenceStr['2]['1] * Int -> Bool

But that’s not all. There is a map type in Wafl, that is a collection of elements accessed via keys. Its type is Map['2]['1], where '1 is the element type and '2 is the key type. And of course the function size also works for maps. So here is the final type of our function isLongerThan:

(Indexable['1]['2]['3] * Int -> Bool)

where '1 is the type of the indexable collection (list, array, map or string), '2 is the type of the keys (for all collections except maps must be Int) and '3 is the type of the elements.

Here is a list of some of the type classes we often use in Wafl:

There are a few other types and type classes, but this should be enough to get you started.

2 Program Structure

2.1 Program Is an Expression

In Wafl, programs are expressions. Each program (or expression) primarily defines what is to be evaluated and not how it is to be executed or evaluated.

If we want to write a program that computes 1+2+3, then we only write that expression and nothing else:

1+2+3

6

We can use literals, names, operators and functions in expressions. Here are a few simple examples. First, this is an integer expression:

53 / 5 * 4 + 12 % 10 + abs(-7)

49

A float expression:

53. / 5. * 4. + 2.12 + sin(1.34)

45.49348454169532

A string expression:

strUpperCase( "Hello " + 'world!' )

HELLO WORLD!

A Boolean expression:

false or true

true

Wafl supports many of the usual operators and functions for primitive types (integer, float, string and bool). There are also more complex types (list, array, map, tuple, record), which we will discuss in more detail later.

Simple expressions are often not enough. In the following sections, we will see how you can define and use functions and named expressions.

2.2 Comments

There are two types of comments in Wafl. Block comments start with /* and end with */. Line comments start with // and end with the end of the line.

/* This is a block comment,
   in two lines */
1 + 2 // This is a line comment after an expression

3

2.3 Tuples

A tuple is a structured data type. It consists of a series of unnamed elements that are referenced by a position. The element of a tuple can have different types.

We will discuss tuples in detail in the following chapters. Now we just need to introduce tuples to make some of the following examples understandable. It is sometimes easier to represent many simple expressions in one example than to use many examples, and tuples are a good tool for this.

Tuples are written with curly brackets with hashes: {# ... #}, and tuple elements are separated by commas:

{# 1, 2, 3.14, "Hello world!" #}

{# 1, 2, 3.14, 'Hello world!' #}

In the following example we use a tuple to evaluate 6 integer expressions:

{#
    7 - 6,
    1 + 1,
    6 / 2,
    2 * 2,
    12 % 7, //  Remainder of integer division
   -8 %% 7  //  Similar to `%`, but always positive
#}

{# 1, 2, 3, 4, 5, 6 #}

2.4 Local Definitions

A Wafl expression can define and use some local definitions. Local definitions are specified and used in where expressions. Local definitions include expression definitions and function definitions. Expression definitions are also referred to as named expressions.

In a nutshell:

• a named expression is a definition in which a name is defined to represent the value of a given expression, and
• a function is a definition in which a name is defined to represent a mapping of the given arguments to the value of the given expression.

Named expressions are used as values and functions are applied to some specific arguments.

In the following example we define and use both a function and a named expression:

fun( 100, 0 ) + nam
where {
    fun( a, b ) = a * 10 + b;
    nam = fun( 4, 2 );
}

1042

The function definition has name and parenthesis on the left side of the equality symbol, and named expression has only the name on the left side.

Local definitions are specified in where expressions. A where expression consists of a main part and a block of local definitions (where-block for short):

<main-expression-body>
where {
    <definition>;
    <definition>;
    ...
}

where each <definition> represents an expression definition or a function definition.

A function definition binds a function body to a function name and to its arguments. A function definition has the form:

<name>(<arguments>) = <expression>;

where <arguments> is a list of the function argument names. The arguments are separated by commas. The argument list can be empty.

A definition of a named expression binds an expression to a name and has the following form:

<name> = <expression>;

where <name> is any valid name and <expression> is (almost) any valid Wafl expression. The most important restriction is that a name definition expression must not contain a where block.

The functions and the named expressions are by no means the same thing. Their semantics are very different. A named expression is something like a tool to make the expressions shorter and more readable, and it is of course strongly bound to the context. A function, on the other hand, is always free from the context in which it is defined. In the following section, we will discuss some specific details about local definitions and functions.

2.5 Function Definition

A function definition binds a function body to a function name and to its arguments:

<name>(<arguments>) = <expression>;

A function definition expression (<expression>) can use the following names:

• global names;
• function arguments;
• all functions defined in its own where-block, or in some of the parent where-blocks (including its own name) and
• all named expressions defined in its own where-block or in the where-block of the main expression.

In the next example, we can use the following in the expression body of the function f:

• named definition name_main, defined in the main where-block;
• named definition name_f, defined in its own where-block;
• its own argument x;
• function f1, defined in its own where-block;
• function g, defined in a parent where-block.

For example, we could not use:

• function g1 in f, because it is not defined in a fs parent where-block;
• name name_f in f1, because it is not defined in f1s own where-block nor in main where-block.

f('*')
where {
    f(x) = x + name_main + name_f + f1(x) + g(x)
    where {
        name_f = x + x;
        f1(x) = x + x + g(x);
    };
    name_main = '---';    
    g(x) = name_g + g1(x)
    where {
        name_g = x + x;
        g1(x) = x + x;
    };
}

*---************

2.6 Named Expression Definition

A named expression definition binds an expression to a name and has the following form:

<name> = <expression>;

A named expression definition (<expression>) can use the following names:

• global names;
• all functions defined in some of the parent where-blocks;
• all named expressions (other than itself) defined in its direct parent where-block (the one in which it is defined), or in main expression where-block and
• arguments of the function in whose where-block it is defined.

In the following example, we can use the following in the definition of the name name_f:

• named definition name_main, defined in the main where-block;
• named definition name_fa, defined in its direct parent where-block;
• argument x, of the function f in whose where-block it is defined;
• function f1, defined in a parent where-block;
• function g, defined in a higher level parent where-block.

It is important to note that we cannot use recursive references to name definitions (either directly or indirectly) within a name definition expression, but we can use recursive references to a function in whose where-block the named expression is defined.

f('*')
where {
    f(x) = x + name_main + name_f + f1(x) + g(x)
    where {
        name_fa = name_main + x + x;
        name_f = name_main + name_fa + g(x) + f1(x) + x + x;
        f1(x) = x + x + g(x);
    };
    name_main = '---';    
    g(x) = name_g + g1(x)
    where {
        name_g = x + x;
        g1(x) = x + x;
    };
}

*---------************************

2.7 No Variables

It is important to emphasize that the named expressions are not variables. Wafl has no variables. If a name is defined to represent an expression, then it represents the same expression throughout the evaluation of the scope in which the name is available. It is not possible to change the definition.

In the following example, x is defined twice, so an error is reported:

x
where {
    x = 1;
    x = 2;
}

--- Loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_989978_0.tmp
Parser error [C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_989978_0.tmp]
    Definition name repeated! [err 1211:3]
    Line 5:     x = 2;
            ___/
--- End loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_989978_0.tmp

A name can have different definitions in different scopes, even if one of the scopes is contained within another. If more than one definition of the same name is visible, the one with a narrower scope (i.e. closer to the place of use) is relevant.

In the next example, the name x is defined twice:

• the first definition is visible in the main expression and all its subdefinitions, including the body of the function f);
• the second definition is visible in the body of the function f and in all its subdefinitions;
• this is valid;
• the second definition has the narrower scope, so it is used in the body of the function f;
• the first definition is used in the main expression because the second one not visible there.

x + f( "10" )
where {
    x = "ABC";          //  the first `x`
    f( s ) = x + s + y
    where {
        x = "abc";      //  the second `x`
        y = "xyz";
    };
}

ABCabc10xyz

If a named expression is defined in the where-block of a function and uses function arguments (either directly or indirectly), it can have different values in different function evaluations. However, this is not a problem, as it can only be used in the context of this function evaluation.

In the following example, the function f is evaluated twice, first for the argument 'a', and then for the argument 'b'. When evaluating f('a'), the name is evaluated to '*a*' and when evaluating f('b') it is evaluated to '*b*'. As expected, the values of the named expressions are not shared between the different evaluations:

{# f('a'), f('b') #}
where {
    f(s) = s + name + s
    where {
        name = '*' + s + '*';
    };
}

{# 'a*a*a', 'b*b*b' #}

An important aspect of the implementation of named expressions is efficiency. Each named expression is evaluated at most once per context. If it is never used, it is never evaluated, but if it is used several times, it is only evaluated once.

In the following example, the value of the named expression is never requested, so it is never evaluated. We know this for sure, because its evaluation would generate an error:

if 2 < 5
    then 5
    else error
where {
    error = 1/0;    //  Zero division!
}

5

In the following example, we use the same name expression many times. However, we always get the same value, as it is evaluated at most once:

{# x, x, x, x, x, x, x, x, x, x #}
where {
    x = random(1000);
};

{# 600, 600, 600, 600, 600, 600, 600, 600, 600, 600 #}

2.8 The Order of the Definitions

The order of the definitions in the same scope (i.e. in the same where-block) is not important. However, it is good to use either a top-down or a bottom-up strategy to make the program easier to read. A top-down strategy suggests defining the most abstract name first, even if its definition uses some other names that will be defined later. In contrast, a bottom-up strategy suggests introducing the simplest definitions first and using them later in more abstract definitions.

In the following example, we define the same simple function three times (with different names), to demonstrate different styles:

{# topDown('a'), bottomUp('a'), noOrder('a') #}
where {
    topDown(x) = a
    where {
        a = b + b + x + c;
        b = c + x + c;      
        c = "#" + x + "#";  
    };

    bottomUp(x) = a
    where {
        c = "#" + x + "#";
        b = c + x + c;
        a = b + b + x + c;
    };

    noOrder(x) = a
    where {
        c = "#" + x + "#";
        a = b + b + x + c;
        b = c + x + c;
    };
}

{# '#a#a#a##a#a#a#a#a#', '#a#a#a##a#a#a#a#a#', '#a#a#a##a#a#a#a#a#' #}

The three definitions are equivalent to each other, but the last one is more difficult to read.

2.9 Conditional Expression if

In imperative programming languages, it is common to use conditional statements to control the flow of program execution. Wafl is a functional language and does not contain statements, so in Wafl we use conditional expressions instead.

The Wafl programming language has two types of conditional expressions: if and switch. The expression if contains a condition and two optionally evaluated expressions:

if <condition> then <then-exp> else <else-exp> 

where <condition> must be an expression of the logical type Bool, while the expressions <then-exp> and <else-exp> can be of any type, but must have the same type.

The conditional expression is evaluated first. If its value is true, then the expression <then-exp> in the then branch is evaluated and the resulting value is the result of the full if expression. In the other case, if <condition> has the value false, then the expression <else-exp> in the else branch is evaluated and the resulting value is the result of the complete if expression.

{#
    if 5 > 2 then 'five' else 'two',
    if 5 < 2 then 'five' else 'two'
#}

{# 'five', 'two' #}

2.10 Conditional Expression switch

The conditional expression if evaluates one of the two alternative expressions. If more alternatives are required, we can use multiple if expressions or a switch-expression.

The switch expression consists of a conditional expression, at least one case clause and a mandatory default clause:

switch <cond-exp> {
    <case-clause>;
    <case-clause>;
    ...
    <default-clause>
}

The conditional expression is evaluated first. Then, based on the resulting value, one of the case clauses is selected and evaluated, or, if none is selected, the default clause is evaluated. The result of the selected and evaluated clause is the result of the switch expression.

Each case clause begins with the keyword case, followed by a comma-separated list of values. The list of values is followed by an expression that ends with a semicolon:

case <literal>, ... <literal> [:] <exp>;

An optional colon symbol can separate the value list from the clause expression. In addition, the keyword case can be used as a separator instead of a comma and an optional colon symbol can be used in front of it. So, case 1,2,3 is the same as case 1: case 2: case 3.

The default clause is mandatory. It is defined as:

default [:] <exp> [;]

The following example uses both types of conditional expressions to calculate how many days a given month has:

{#
    daysInMonth( 1, 2000 ),
    daysInMonth( 2, 2000 ),
    daysInMonth( 2, 2001 ),
    daysInMonth( 2, 2004 ),
    daysInMonth( 2, 2100 )
#}
where{
    daysInMonth( month, year ) =
        switch month {
            case 2:
                if isLeapYear(year)
                    then 29
                    else 28;
            case 4, 6, 9, 11:
                30;
            default:
                31
            };

    isLeapYear(year) =
        year % 4 = 0
        and ( year % 100 != 0
              or year % 400 = 0 );
}

{# 31, 29, 28, 29, 28 #}

The conditional expression <cond-exp> is evaluated first. All case clauses are checked in the specified order to see if there is a literal that matches the conditional value. If such a case clause is found, the corresponding expression is evaluated and its value is the result of the complete switch expression. If no specified literal matches the value of the <cond-exp>, the expression of the default clause is evaluated and its value is the result of the complete switch expression.

There are three simple rules:

• The conditional expression and all literals in all case clauses must be of the same primitive type.
• All other expressions (case clause expressions and the default expression) must be of any but same type.
• If the same literal is specified several times, only the first occurrence is taken into account.

One could say that it is unusual that the syntax here is so flexible, but it was introduced to create a syntactic similarity to C-like languages.

2.11 Recursion

Since Wafl is a functional programming language, it has no variables, so iterative processing is (almost) impossible. The main method to express “repetitive” behavior of functions is the use of recursion.

Recursion is a very important technique that allows a function definition to use the function itself. It is often used in mathematics as a tool for defining infinite (but still enumerable) structures.

The usual example of a recursive definition in mathematics is the definition of factorial function. The factorial, which is usually denoted by the postfix operator !, is defined as follows:

The definition of every recursive function is based on two main elements:

1. the recognition of the terminal condition, i.e. the case where the arguments allow a non-recursive, direct evaluation of the result, and

2. the definition of the recursive evaluation in such a way that the application of each step brings the evaluation closer to the terminal condition.

Both recursion elements are of great importance. We need to consider them carefully when using recursion. If the terminal condition is not well defined, the evaluation of a recursive function may never finish for some arguments (or at least not in an acceptable time frame). On the other hand, if a recursive step is not well defined, the efficiency of the function may suffer for some arguments.

In the case of the factorial function, the terminal condition is met if the argument is zero. In this case, the result can be evaluated directly. In other cases, the result is defined based on the application of the same principles for smaller arguments. Following these rules, we can evaluate n! in n+1 steps.

In the following example, we define and use the function factorial:

{#
    factorial(0),
    factorial(1),
    factorial(2),
    factorial(3),
    factorial(4),
    factorial(5),
    factorial(16)
#}
where{
    factorial( n ) = 
        if n<=1 then 1
        else n * factorial(n-1);
}

{# 1, 1, 2, 6, 24, 120, 20922789888000 #}

Another example of recursive definitions are the Fibonacci numbers. The first and second elements of the sequence are defined as 1, while every other element is defined as the sum of the two preceding elements:

And here is the function fib, which evaluates a given element of the Fibonacci number sequence:

{#
    fib(1),
    fib(2),
    fib(3),
    fib(4),
    fib(5),
    fib(6)
#}
where{
    fib( n ) = 
        if n<=2 then 1
        else fib(n-1) + fib(n-2);
}

{# 1, 1, 2, 3, 5, 8 #}

In imperative programming languages, recursion is usually taught as an exotic technique. It is usually noted that while it looks nice, it is not efficient and can cause other problems. For example, deep recursion can destroy the organization of the internal memory of imperative programming languages (where “deep” usually means close to a thousand or several thousand steps).

Do not worry about this in Wafl. As a functional programming language, Wafl relies on recursion as one of its elementary techniques. You are free to use deep recursion, but be careful - there will be no memory corruption, but very deep recursion can still cause problems due to a high memory usage. But in Wafl “deep” is not measured in hundreds and thousands, here we are talking about hundreds of millions.

Knowing this, it may seem strange now, but there are enough advanced constructs in the programming language that programmers do not need to explicitly iterate in most cases, and deep recursions are not often used in reality. We will look at lists and higher order functions in the next chapter and learn how to program efficiently.

2.12 Libraries

Wafl libraries are used by declaring a local library name and binding it to an externally defined library.

Wafl Library Definition

Regular Wafl libraries are files with the following syntax:

<LIBRARY_FILE> ::= 
    library [<name>] { <definition>* } 
    [<lib_where_subdefinitions>]
<lib_where_subdefinitions> ::= 
    where { <definition>* }

Each library begins with a declaration library [<name>]. The name specified in the library is used exclusively for the documentation. It can contain a version number, as long as it follows the Wafl syntax for names.

The declaration is followed by a block of public definitions. The public definitions can be followed by an optional where block with private definitions.

The following example shows a simple library with a public function f and a private function g:

library Example {
    f( x ) = g( x ) + g( x );
}
where {
    g( x ) = x + x ;
}

Library Declaration

To use a library in Wafl programs (and in other libraries), the library must be declared. Each library declaration must be specified in the where block. It represents the definition of a name as a library reference. Library references are normally placed at the end of the outermost where blocks of programs and libraries.

A library reference has the following syntax:

<name> = library [file] <filename>

where <filename> must be specified as a string literal.

For example, if the previous library example is available as the file example.wlib, then a corresponding library reference can be declared as follows:

elib = library 'example.wlib';

The specified name (elib in the example) is used in the program to refer to the library. The name of the library, which is defined in the library, is not used for referencing. This approach allows us to use different versions of the same library at the same time by simply using different reference names:

elib1 = library 'v1/example.wlib';
elib2 = library 'v2/example.wlib';

However, we strongly recommend using the same reference names for all libraries in a project.

Referencing Library Elements

A library definition is comparable to namespaces in C++ or package names in some other languages. To use a name defined in a library, it must be preceded by the library name and the scope operator ::.

For example, to use the function f, which is defined in a library declared as elib, we must write elib::f.

elib::f( "A" )
where {
    elib = library file 'example.wlib';
}

"AAAA"

Importing a Library

From version 0.6.9, the importing syntax is supported. It has a form of a declarative statement, which must stand at the very beginning of a program. Import declaration can have different forms, and each of them is equivalent to a regular library declaration form:

• import libname; - The basic form is equivalent to a declaration libname = library;, or libname = library 'libname'; The library manager will first try to load a binary library libname with an appropriate extension (.dll or .so), and with added prefix libw if necessary. If no binary library is found, then it will try to load a regular Wafl library libname.wlib.
• import 'libname.ext'; - This form is similar to the basic one, but no extension will be added implicitly. It is the same as libname = library 'libname.ext';.
• import libname = libfilename; - This form explicitly defines a library name which is not the same as the file neme. It is the same as libname = library 'libfilename';. The extension may be specified, also.
• import libname = param pname; - This form corresponds to a parametrized libraries declaration libname = library param 'pname';. See Parametrized Libraries for more detail.

Importing a Library Into the Program Namespace

From version 0.6.10, the using syntax is supported. It is similar to the importing syntax with two significant differences:

• the using keyword is used instead of import;
• the library names are imported into the main program namespace.

It is still possible to use the full library name referencing as with import and the library declaration.

Library Documentation

Library documentation can be created automatically in Markdown format using a command:

clwafl -doc <lib_file_name>

For example, we can use the following command to create a documentation for the example.wlib library:

clwafl -doc example.wlib > example_wlib_doc.md

A library documentation contains:

• documentation of the library declaration and
• documentation of the public definitions.

Library names and definition names and types are automatically extracted from the code. Definition descriptions are extracted from the comments in a Doxygen-like manner:

• The supported formats for documenting comments are:

  • /// for single-line comments and

  • /** ... */ for multi-line comments.

• All documenting comments that precede a library declaration or a function definition are extracted and used as the corresponding descriptions.

• Markdown elements can be used in the documenting comments.

Parametrized Libraries

In some cases, we do not need to select a specific library during development, but only when the program is used. If we provide several different libraries with the same interface (public names), we can parametrize the program evaluation by specifying a selected library. Different libraries can, for example, use different databases or different file formats.

To specify a library when using a program, we use parametrized libraries. A parametrized library declaration consists of two parts. First, the parametrized library is declared in the program using the following syntax:

<name> = library param [<libname>]

where <libname> is a parametrized library name. If no <libname> is specified, the name <name> is used as the default value instead.

When executing the program, the parametrized library name must then be bound to a library file name using the command line parameter:

-lib:<name>:<filename>

where <name> is a parametrized library name and must correspond to the name used in the program, and <filename> is a library file name, to be used as a parametrized library instance.

For example, we can write a program as:

elib::f( "A" )
where {
    elib = library param;
}

and execute it with:

clwafl -lib:elib:example.wlib program.wafl

to get the same output as before:

"AAAA"

Binary Libraries

Binary Wafl Libraries are libraries written in C and C++. The binary libraries are distributed as .so or .dll files. They are used in a similar way to regular Wafl libraries, but with a specific declaration syntax:

<name> = library extern [cpp] <libname>

where <libname> can be an exact library file name or a generic library name. The Wafl loader attempts to load one of the following files, depending on the platform:

• <libname>
• <libname>.so
• libw<libname>.so
• <libname>.dll
• libw<libname>.dll

To list the contents of a binary library, use clwafl with the command line option -listlib:<libname>, or the equivalent shorthand ? <libname>. For more details add the option -verbose or use ?? <libname>.

Each binary library includes the function _libData_(), that returns some general information on the library:

Timer::_libData_()
where { Timer = library; }

{ build: 'RELEASE 64b', name: 'Timer', verMajor: 0, verMinor: 6, verPatch: 10, verStrFull: '0.6.10 (25091)', verStrPublic: '0.6.10', verTweak: '25091' }

Simple Universal Library Declaration

Universal library declarations assume the implicit recognition of library types instead of using explicit library type declarations. The syntax of the simple library declaration is:

<libname> = library [<libfilename>];

The <libfilename> is optionally specified as a literal string. The following declaration specifies, for example, that the library MyLib is first searched for a binary library libwAlib.dll (or libwAlib.so); if no binary library is found, a regular Wafl library Alib.wlib is used:

MyLib = library 'Alib';

If <libfilename> is not specified, the library name <libname> is used by default. In the following example, it is the same as if the library file name is specified as 'MyLib', so that a binary library libwMyLib.dll (or libwMyLib.so) is searched for first; if no binary library is found, then a regular Wafl library MyLib.wlib is used.

MyLib = library;

Library Search Path

The libraries are searched for in the following directories:

• <ref>
• <ref>/lib
• <app-libdir>
• <app-libdir>/lib
• <app-cwd>
• <app-cwd>/lib
• <sys-libdir>
• <prg>
• <prg>/lib
• <prg>/../lib

where:

• <ref> is the location of the file from which the library is referenced;
• <app-libdir> is the application library directory, usually specified as the -libdir interpreter option or libdir ini-file option; defaults to current working directory;
• <app-cwd> is the root directory of a Wafl application (service); it is specified when application/service is started, in a way that depends on the service type;
• <sys-libdir> is the system defined library directory, usually specified as libdir-system ini-file option; default value is ${WAFL_PATH}/lib;
• <prg> is the location where the currently used Wafl program module (interpreter) is located.

3 Programming With Functions

3.1 Strict Type Checking

Wafl is a strongly typed programming language. This means that Wafl requires a detailed and very strict type checking before program evaluation. Each function application must fully comply with the function type.

Strong type checking is usually paired with explicit declarations of name types. In Wafl, however, no explicit type declarations are required as the types are automatically inferred during the code analysis.

Due to the strict type checking, no implicit type conversions are allowed.

In the following example, we have a program with incorrect type usage. The addition operator is defined for various types, but it is not defined for operands of different types. An error is therefore reported:

1 + '2.0'

--- Loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_878529_0.tmp
Typechecking failed!
- Program   [Line: 2]
    The argument (2) type is not suitable for the context: 
        1 + '2.0'   [Line: 2]
    The expression type is not suitable for the context: 
        '2.0'
        Exp.type is: String
        Not compatible with: Int
        Before simplification: Value['2]
--- End loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_878529_0.tmp

The correct way to deal with such problems is to use explicit type conversions. This will be covered later in this tutorial.

3.2 Automatic Type Inference

Wafl is a strongly typed programming language. However, the Wafl syntax does not contain explicit type specification. All types are inferred implicitly. Normally, the inferred types are not displayed to user during program evaluation, but if a type error is detected during type checking, the related inferred types are reported.

In the following example, three local functions are defined:

• The function g is recognized to be of type (Float -> Float) (maps a single float argument to a float result);
• The function h is recognized to be of type (Int -> Int)(maps an integer argument to an integer result).
• The function f is not well defined because there is an addition operator a first operand of type Float and a second operand of type Int, but the implemented addition operator does not allow the different operand types.

f(7.0)
where{
    f(x) = g(x) + h(x); //  Type checking error!
    g(x) = sin(x);
    h(x) = x + 5;   
}

--- Loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_827585_0.tmp
Typechecking failed!
- f ( x ) : '2   [Line: 4]
    The argument (2) type is not suitable for the context: 
        g(x) + h(x)   [Line: 4]
    The result type is not suitable for the context: 
        h(x)   [Line: 4]
        Exp.type is: (Int -> Int)
        Not compatible with: Float
        Before simplification: Value['5]
--- End loading: C:\Users\smalkov\AppData\Local\Temp\wafltmpfile_827585_0.tmp

The error report contains some redundant data, as all branches of the type checking process are reported to allow a better understanding of the reported problems. If we read the report from the beginning, we can see all the actions that the type checker has performed:

• the attempt to check only type of the function f failed because f uses the names g and h whose types have not yet been inferred;
• the attempt to check the type of the function g inferred its type : (Float -> Float);
• the type of the function h is inferred also: (Int -> Int);
• it tried again to check the type of the function f and failed again because h(x) is not a valid usage in the context, which means that x is already assumed to have a non-float type;
• it tried again to check the type of the function f, but now in a wider context and failed for the same reason.

In most cases, it is better to read the report from the bottom. The last block of reported unrecognized types is the most important. Any line in the report beginning with OK: indicates that the given definition type is well inferred.

Reading from the bottom up, the error report shows that the type checking for Program and f fails and the problem is in the subexpression h(x). Further analysis shows that this is h(x) from the definition body of f.

3.3 Polymorphism

Polymorphism is the property of a function to be well defined for arguments of different data types. Implicit polymorphism is a very important feature of the Wafl programming language.

Type inference starts with the most general assumption that each of the local definitions is completely polymorphic, i.e. that any argument of any function can be of any data type. Step by step, the assumed polymorphic types are reduced to types for which expressions and definitions are applicable.

In the following example, two polymorphic functions add and sub are defined and used with arguments of different types:

{#
    add(1,2),
    add(1.3,2.3),
    add('a','b'),
    sub(5,1),
    sub(5.4,1.2),
    f(5,4,3),
    f(1.2, 3.4, 1.3),
    add( asFloat(add(1,2)), 3.1 )
#}
where{
    add(x,y) = x + y;
    sub(x,y) = x - y;
    f(x,y,z) = sub( add(x,y), z);
}

{# 3, 3.5999999999999996, 'ab', 4, 4.2, 6, 3.3, 6.1 #}

The function add has the type (Value['1] * Value['1] -> Value['1]). This means:

1. it can be applied to arguments of any value type (Integer, Float or String);
2. both arguments must be of the same value type and
3. the result is of the same value type.

Similarly, the type of the function sub is inferred to be (Numeric['1] * Numeric['1] -> Numeric['1]). Thus:

1. it is applicable to arguments of any numeric type (Integer or Float);
2. both arguments must be of the same type and
3. the result is of the same type.

Both Numeric['1] and Value['1] are so-called combined data types. They can be further reduced to different primitive data types. The type '1 stands for a polymorphic type name, like a type variable. Identical polymorphic type names in a type must be reduced to identical specific types in each specific function application.

In each particular function application, the function type must be reduced to a non-polymorphic data type. However, different applications of the same polymorphic function can be reduced to different types in a program. When used in function definitions, polymorphic functions can be used in a polymorphic way, without further reduction of the data types, or with reduction to a more specific but still different polymorphic type. Their types are further reduced if the application of the defining function makes this necessary.

The function f in our example is defined as:

f(x,y,z) = sub( add(x,y), z);

and its type is inferred as (Numeric['1] * Numeric['1] * Numeric['1] -> Numeric['1]). Thus:

1. it is applicable to three arguments of any numeric type (Integer or Float);
2. all arguments must be of the same type and
3. the result is of the same type.

The function f uses both add and sub. In the specific application, the type of the function add is reduced from Value['1] to Numeric['1], while the type of the function sub is not reduced any further.

It is important to note that each specific application is reduced independently of the other applications. Therefore, in the same example, our function add is successfully applied to a pair of integers, a pair of floats and a pair of strings, and the functions sub and f are successfully applied to integers and floats. Also, in the last expression, the function add is applied to both integers and floats.

3.4 Higher Order Functions

One of the essential features of functional programming languages is that functions are treated as first-order citizens. Functions can be used as arguments and results of other functions, in a much simpler way than in the most imperative languages.

The functions that take functions as arguments or return a function as a result are called higher order functions. They are essential for functional programming.

In the following simple example, the function double is used as an argument to the function apply:

apply(double,2)
where{
    apply(f,x) = f(x);
    double(x) = x + x;    
}

4

The function double has the type (Value['1] -> Value['1]). It is similar to the add function from one of the previous examples.

The function apply has the type (('1 -> '1) * '1 -> '1). This means:

• its first argument must be a unary function of type ('1 -> '1);
• its second argument must be of type '1,
• its result is of type '1 and
• the type variable '1 can be replaced by any type, but in the same time in all previous assertions.

In the given example, the function apply applies the function double to 2. In this particular application, the type variable '1 is replaced by Int.

More complex examples follow later.

3.5 Partial Application

A partial application is any function application where not all expected arguments are specified.

For example, if we were to specify only the first argument of the add function (from the previous examples), the result would be a unary function that returns its argument incremented by one.

One way to do this is to define a new function:

f(x) = add( 1, x );

Another possibility is to use a partial application:

f = add(1,_);

In Wafl, the syntax of the partial application is similar to a regular function call, but the underscore ‘_’ is used instead of unspecified arguments. You must always use as many arguments as the function expects, but some of the arguments can be specified and others can be left unspecified.

The result of a partial application is a function. Its arguments correspond to the unspecified arguments of the partial function application, in the preserved order.

It is possible to leave all arguments unspecified. However, this is not very useful as the result is the function itself.

In the following example, several partial applications are used:

{#
    strGetFirst5a( "1234567890" ),
    strGetFirst5b( "1234567890" ),
    charAt( "123456", 1 ),
    charAt( "123456", 2 ),
    add2( 5 ),
    // The following expressions give the same result
    subStr( "1234567890", 5, 3 ),
    subStr( _, 5, _ )( _, 3 )( "1234567890" )
#}
where{
    // The following definitions are identical.
    // Both functions return
    // the first 5 characters of a string.
    strGetFirst5a( s ) = strLeft( s, 5 );
    strGetFirst5b = strLeft( _, 5 );

    // charAt(n) returns the nth character of a string.
    charAt = subStr( _, _, 1 );

    // twice(f,x) applies f twice to x
    twice( f, x ) = f( f(x) );
    // inc(x) returns x incremented by 1
    inc(x) = x + 1;
    // add2 returns its argument incremented by 2
    add2 = twice( inc, _ );
}

{# '12345', '12345', '2', '3', 7, '678', '678' #}

In many functional programming languages, a partial application is implemented by specifying only the first argument of a function (or, more generally, some of the arguments from the beginning of the argument list, in the appropriate order). This approach is called curried functions. The result of a curried partial application is a function that maps the remaining arguments to the result.

The partial application, as implemented in Wafl, is more general than curried functions.

3.6 Lambda Functions

In functional programming languages, the term lambda function refers to various concepts for defining unnamed functions at the place where they are used.

When we use higher-order functions, we often have to specify a function as an argument that is not needed elsewhere. If we use a function only once in a program, it is easier and often more readable to define it inline than to introduce a regular function definition.

In the Wafl programming languagewe define lambda functions in the following form:

A lambda function can appear at any point where we can use a regular function name. Sometimes it is necessary to put the lambda function in parenthesis to clarify the syntax.

In our first lambda example, we define and use an unnamed function that returns its argument incremented by 1:

(\x:x+1)(41)

42

This function is the same as the inc function from the previous examples, but now it is defined as a lambda and used in the place of the definition. This is much shorter than using a full definition syntax, as in the following example:

inc(41)
where {
    inc(x) = x+1;
}

42

For the first time, let us define a function that takes only functions as arguments and returns a new function as a result. The function combine takes two functions as arguments. It returns a unary function that applies the combined functions to its argument. The following expression should therefore always evaluate to true:

combine(f,g)(x) == f(g(x))

One way to write combine is to first define an auxiliary function c that takes three arguments f, g and x and returns their partial application:

combine = c(f,g,_)
where {
    c(f,g,x) = f(g(x));
}

A simpler way is to use lambda instead of the definition of the function c, but the solution is equivalent:

{#
    add2(1),
    add3(1),
    combine( inc, inc )(10),
    combine(\x:x+1,\x:x+1)(10)
#}
where{
    combine( f, g ) = ( \f,g,x : f(g(x)) )( f, g, _ );
    add3 = combine( add2, inc );
    add2 = combine( inc, inc );
    inc(x) = x + 1;
}

{# 3, 4, 12, 12 #}

In the following example, we use combine to define the function repeat that generalizes twice from the previous examples. For a given function f and a given integer n, repeat returns a function that applies f to its argument n times. In repeat we use the lambdas to write the identity function, and in the main expression we use a lambda equivalent of the function inc:

{#
    repeat( \x:x+1, 0 )( 100 ),  
    repeat( \x:x+1, 1 )( 100 ),
    repeat( \x:x+1, 10 )( 100 )   
#}
where{
    repeat( f, n ) =
        if n=0 
            then \x:x 
            else combine( f, repeat(f,n-1) );
    combine( f, g ) = ( \f,g,x : f(g(x)) )( f, g, _ );
}

{# 100, 101, 110 #}

Note that this implementation of repeat is not very efficient. However, it shows how higher-order functions can be combined with lambdas to achieve very interesting goals.

3.7 Lambda Closures

In functional programming languages, a closure is a function that binds some elements of its outer scope. We can say that partial applications are a kind of closures.

Let us go back to the definition of the function combine. We can say that combine binds the given functions f and g in a closure:

combine( f, g ) = ( \f,g,x : f(g(x)) )( f, g, _ );

Definitions like this are very common: first we need to define a function with multiple arguments and then create a closure by partially applying this function. It seems like we write the same things twice.

Fortunately, we can use lambda closures (or lambdas with bindings), to create closures more easily. To define a lambda closure, we need not only the lambda arguments, but also the list of names from the definition space that we need to bind. These names are listed in square brackets, after the lambda arguments:

There is an alternative, older syntax for the same thing, where a hash symbol ‘#’ is used to separate the list of lambda arguments from the list of bound names:

Now we can define the function combine even more easily than before with the help of a lambda closure:

{#
    combine(\x:x+1,\x:x+1)(10),
    combine(operator+(2,_), operator*(8,_))(5)
#}
where{
    combine( f, g ) = \x [f,g]: f(g(x));
}

{# 12, 42 #}

3.8 Operators as Functions

The syntax for partial application is not applicable to operators. Furthermore, operators cannot be used as arguments for function application. For this reason, Wafl introduces the functional syntax of operators. Each operator has a corresponding equivalent function. If there is an operator <op>, then there is also the corresponding function operator<op>, with the same number of arguments and the same type.

The following example shows how we can use the functional syntax of operators to partially apply the operator ‘+’:

{#
    operator+( _, 'b' )( 'a' ),
    operator+( 'a', _ )( 'b' ),
    apply( operator+( _, 5 ), 10 ),
    apply( operator+( _, 5 ), _ )( 10 ),
    apply2( operator+, _, _ )( 5, 10 ),
    apply2( _, 5 ,10 )( operator+ )
#}
where{
    apply( f, x ) = f( x );
    apply2( f, x, y ) = f( x, y );
}

{# 'ab', 'ab', 15, 15, 15, 15 #}

3.9 Dot Operator

Due to the functional semantics of subroutines, the source code of programs written in functional programming languages is very often quite unreadable.

For example, consider the following definition of the function g. For a given string s, it extracts a substring starting at position 5 of length 8, then replaces each ‘a’ with ‘B’, then replaces each ‘b’ with ‘A’, and finally converts the string to lowercase. Basically, it is a very simple function, but it is very unreadable, no matter how carefully we indent the code:

g(s) = 
    strLowerCase(
        strReplaceAll(
            strReplaceAll(
                subStr(s,5,8),
                'a','B'
            ),
            'b','A'
        )
    );

Wafl tries to solve the problem by introducing a dot operator ., which is very similar to the object-oriented dot syntax. In short, any function that is defined for at least one argument can be used with more than just the usual syntax:

but also using the dot syntax, where the function application is written as an OO method of the first argument:

These two syntaxes have the same semantics. Programmers are free to use both and choose the best one for each case.

Using the dot syntax usually leads to better readable source code. In the following example, we define two equivalent functions. For f we use the dot syntax and for g we use the usual syntax of the function application.

{#
    f( 'abcdABCDabcdABCD' ),
    g( 'abcdABCDabcdABCD' )
#}
where{
    f(s) = 
        s.subStr(5,8)
        .strReplaceAll('a','B')
        .strReplaceAll('b','A')
        .strLowerCase();

    g(s) = 
        strLowerCase(
            strReplaceAll(
                strReplaceAll(
                    subStr(s,5,8),
                    'a','B'
                ),
                'b','A'
            )
        );
}

{# 'bcdbacda', 'bcdbacda' #}

Transformational Semantics

A consecutive use of dot syntax can represent an application of transofrmational semantics. Each application of the dot syntax represents a single transformation step that transforms its first argument into the result of the applied function. The entire sequence applications of the dot operator represents a series of such transformation steps.

In the last example, the function f is defined as a series of transformations of the input string x. Four successive transformations are applied to calculate the result of the function.

To enable such applications, in view of the dot syntax, any function that has a main argument and can be regarded as a kind of transformation of this argument, should be defined so that the main argument is the first one.

Continuation Operator

The dot operator has the highest priority. The only operators with higher precedence are the library referencing operator ‘::’, the record/tuple element selector ‘$’ and the record/tuple element update operator ‘^’. In the following example, the abs function is used via the dot operator before the multiplication:

-3 * 2 .abs()

-6

The high precedence of the dot operator often requires the use of parentheses around the preceding expression. To avoid annoying parentheses, Wafl supports the arrow operator ‘=>’, which behaves very similarly to the dot operator, with the only difference that it has the lowest precedence.

If we replace ‘.’ with ‘=>’ in the previous example, then the application of the function abs has the lowest priority and is only evaluated after the entire previous expression has been evaluated:

-3 * 2 => abs()

6

The lowest precedence means that there is no other operator or syntax construction with a higher priority. For example, the function echoLn in the next example is not only applied to the preceding else expression, but to the entire if-then-else expression:

if 3>2
  then 3
  else 2
=> echoLn() 
+ 1

3
4

Alternative Syntax - Arrow Operator

In the first Wafl versions, this technique was called arrow syntax and the operator ‘->’ was used instead of ‘.’. In the current version, the operators ‘->’ and ‘.’ are equivalent. However, we recommend using the dot syntax. The arrow operator may no longer be supported in some of the future versions. This old arrow operator ‘->’ should not be confused with the new arrow operator ‘=>’.

3.10 Explicit Computation State

A few sections earlier, there was an example of Fibonacci numbers:

{# fib(1), fib(2), fib(3), fib(4), fib(5), fib(6), fib(7) #}
where{
    fib( n ) = 
        if n<=2 then 1
        else fib(n-1) + fib(n-2);
}

{# 1, 1, 2, 3, 5, 8, 13 #}

This is an interesting example of recursive programming. However, even a simple analysis shows that this approach is very inefficient. The problem is that the function is evaluated over and over again for the same numbers. Let us analyze the case of fib(6):

fib(6)
 -> fib(5) + fib(4)
     |        -> fib(3) + fib(2)
     |            |        -> 1
     |            -> fib(2) + fib(1)
     |                -> 1     -> 1
     -> fib(4) + fib(3)
         |        -> fib(2) + fib(1)
         |         -> 1     -> 1
         -> fib(3) + fib(2)
             |        -> 1
             -> fib(2) + fib(1)
                 -> 1     -> 1

As we can see: fib(6) is evaluated once, fib(5) once, fib(4) twice, fib(3) three times, fib(2) 5 times and fib(1) 3 times. We see that this sequence corresponds to the Fibonacci number sequence, except for the last step: 1, 1, 2, 3, 5, 3. Since only calls to the lowest level return the exact value, it is easy to conclude that for any n the total number of evaluations of fib(2) and fib(1) is equal to fib(n). And this grows rapidly, approximately with ϕⁿ, where ϕ is the golden ratio (1.61803…).

So our function fib becomes very slow for large numbers. How can we improve this? The formula shows that we should keep the last two results during the computation. This is relatively easy to do in imperative programming. In C/C++, for example, we can do something like the following:

unsigned fib( unsigned n ) {
    unsigned prev2=1, prev1=1, result=1;
    //  for n=0 and n=1 result is already ok
    //  result == 1 == fib(0) == fib(1)
    //  prev1 == 1 == fib(1)
    //  prev2 == 1 == fib(0)
    for( int i=2; i<=n; i++ ) {
        result = prev1 + prev2; // result = fib(i)
        prev2 = prev1;          // prev2 = fib(i-2)
        prev1 = result;         // prev1 = fib(i-1)
    }
    return result;  
}

But in Wafl we do not have variables, so it’s not as simple as in C++. There is no implicit computation state, and the only way to pass the computation state is to do it explicitly. One solution could be to pass the same state as in the C++ example with every recursive call:

{# fib(1), fib(2), fib(3), fib(4), fib(5), fib(6), fib(7) #}
where {
    fib(n) = if n <= 2 then 1 
             else fib_s(1,1,2,n);
    fib_s(p1,p2,i,n) = if i=n then p2
                       else fib_s(p2,p1+p2,i+1,n);
}

{# 1, 1, 2, 3, 5, 8, 13 #}

If we check this carefully, we can remove the constant factor n from fib_s and get a better solution:

{# fib(1), fib(2), fib(3), fib(4), fib(5), fib(6), fib(7) #}
where {
    fib(n) = if n <= 2 then 1 
             else fib_s(1,1,n-2);
    fib_s(p1,p2,i) = if i=0 then p2
                     else fib_s(p2,p1+p2,i-1);
}

{# 1, 1, 2, 3, 5, 8, 13 #}

However, it is not hard to see that this approach to the problem is not so nice.

3.11 Cached Functions

Another approach to exponentially growing recursion is to memorize the previous results. Cached functions can help here.

Cached functions is a Wafl technique to memorize the previous results of a function. If we have a fast growing recursion tree, as in the case of fib, or if we have a function that is computed very often for the same arguments, then we can suggest that this function should have its results cached.

The syntax is simple:

<name>(<args>) = cached <exp>;

If we try to use it with fib, then it becomes:

{# fib(1), fib(2), fib(3), fib(4), fib(5), fib(6), fib(7) #}
where{
    fib( n ) = cached
        if n<=2 then 1
        else fib(n-1) + fib(n-2);
}

{# 1, 1, 2, 3, 5, 8, 13 #}

When we test this solution with larger numbers, we see that it is much faster than the original solution, but that the previous solution with explicit state transfer is still more efficient. This is no surprise - the problem is that the cached solution has to store the computed results and search for the previously stored result. However, if we apply fib over and over again to the same range of numbers, the cached solution becomes much more efficient than any other.

And it is easy to use, which is a big advantage.

4 Primitive Types

Wafl has four primitive types: Integer, Float, String and Bool. In this chapter we discuss the important elements of the primitive types.

This chapter is quite long and detailed, but its content is elementary, so we recommend a cursory reading. It is enough to get an idea of what is supported, and later you can use this chapter as a reference if needed.

4.1 Literals

Integer and float literal constants have the same syntax as in the programming languages C and C++.

Floating point literals must contain a decimal point and at least one digit in front of it.

Logical literal constants are true and false.

String literals are quoted using single or double quotation marks. It does not matter which type of quotation mark is used, but the same type must be used at the beginning and at the end of the string.

Special characters are specified by escape sequences, like in C/C++. The most important escape sequences are: single quotation mark (\'), double quotation mark (\"), backslash (\\), new line (\n), carriage return (\r), horizontal tab (\t), vertical tab (\v), form feed (\f) and backspace (\b). As in C/C++, the characters can be encoded with 3 octal digits: \nnn.

Examples of integer literals:

{#
    0, 42, -21
#}

{# 0, 42, -21 #}

Examples of float literals:

{#
    3.4, 0., 1.2e-3
#}

{# 3.4, 0., 0.0012 #}

Examples of bool literals:

{#
    true, false
#}

{# true, false #}

Examples of string literals:

{#
    'single quotation marks',
    "double quotation marks",
    "two\nlines",
    "octal codes A=\101 a=\141"
#}

{# 'single quotation marks', 'double quotation marks', 'two\012lines', 'octal codes A=A a=a' #}

4.2 Operators

4.2.1 Integer operators

Wafl has the usual arithmetic operators:

• binary:
  • addition (+);
  • subtraction (-);
  • multiplication (*);
  • integer division (/);
  • reminder of integer division (%);
  • modulus (%%);
  • power (**) and
• unary:
  • negation (-).

The division of integer values always produces an integer result.

The remainder and modulus operators are very similar. The difference is that the remainder of the integer division (%) returns positive values for positive dividends and negative values for negative dividends, while the modulus operator (%%) always returns a positive result:

{#
    17 / 10,
    17 % 10,
    17 %% 10,
    -17 / 10,
    -17 % 10,
    -17 %% 10,
    17 / -10,
    17 % -10,
    17 %% -10,
    -17 / -10,
    -17 % -10,
    -17 %% -10
#}

{# 1, 7, 7, -1, -7, 3, -1, 7, 7, 1, -7, 3 #}

Bit-level integer operators are syntactically and semantically equivalent to these operators in C/C++:

• binary:
  • bit-level conjunction (&);
  • bit-level disjunction (|);
  • bit-level left shift (<<);
  • bit-level right shift (>>) and
• unary:
  • bit-level complement (~).

{#
    // '11110000' & '00111111' = '00110000' = 48
    240 & 63,   
    // '011' | '110' = '111' = 7
    3 | 6,      
    // bit-level complement
    ~5,
    // '11110' << 3 = '11110000' = 240
    30 << 3,   
    // '11111111' >> 3 = '11111' = 31
    255 >> 3
#}

{# 48, 7, -6, 240, 31 #}

The power operator a ** b returns a to the power of b. Any integer raised to a negative power will yield zero, except for one. One raised to any power will always yield 1:

{#
    2 ** 3,
    2 ** -3,
    1 ** 3,
    1 ** -3,
    -2 ** 3,
    -2 ** -3
#}

{# 8, 0, 1, 1, -8, 0 #}

Multiplication, division, remainder, modulus and bit-level conjunction have a higher precedence than addition, subtraction and bit-level disjunction. The power operator has the higher priority. Shift operators have the lower priority.

4.2.2 Float Operators

Wafl has the usual float operators:

• binary:
  • addition (+);
  • subtraction (-);
  • multiplication (*);
  • division (/);
  • power (**) and
• unary:
  • negation (-).

{#
    2.1 + 3.45678,
    3.0 - 1.2,
    3.14 * 2.17,
    17.0 / 10.,
    2.0 ** 3.0,
    2.0 ** 0.5
#}

{# 5.55678, 1.8, 6.8138, 1.7, 8., 1.4142135623730951 #}

4.2.3 String operators

Wafl has a single binary string operator:

• string concatenation (+).

"One" + "Two"

OneTwo

4.2.4 Bool operators

The usual logical operators are supported in both C-like and SQL-like syntax:

• binary:
  • conjunction (&&, and);
  • disjunction (||, or) and
• unary:
  • negation (!, not).

{#
    true or false,
    true || false,
    true and false,
    true && false,
    not true,
    !true
#}

{# true, true, false, false, false, false #}

4.2.5 Comparison Operators

The usual comparison operators are defined for the types Integer, Float and String:

• two versions of the equality operator - C-like (==) and SQL-like (=);
• two versions of the inequality operator - C-like (!=) and SQL-like (<>);
• less-than (<);
• less-than or equal (<=);
• greater-than (>) and
• greater-than or equal (>=).

{#
    1 < 2,
    1.2 <= 2.3,
    "abcd" > "ABCD",
    "abcd" >= "AB",
    21 * 2 = 42,
    21 == 42 / 2,
    17 != 18,
    -3.14 <> 3.14
#}

{# true, true, true, true, true, true, true, true #}

4.3 Conversion Functions

Wafl is a strongly typed programming language and no implicit type conversions are allowed. Therefore, the Wafl core library contains the conversion functions:

• asInt - from any other primitive type to Integer;
• asFloat - from any other primitive type to Float;
• asString - from any other type to String;
• asChar - from any other primitive type to a single character String and
• asBool - from any other primitive type to Bool.

There are several other conversion functions for specific type pairs.

4.3.1 Conversion to Integer

The function asInt(x) converts every non-integer primitive value x into the Integer type:

• asInt(x) converts a Float value x to the nearest integer, just like the synonymous function round;
• asInt(x) converts a String value x, which is a valid integer literal, into the corresponding integer value;
  • if x is a float value literal, only the digits before decimal point are used;
  • if x is not a valid integer literal, asInt returns zero;
• asInt(x) converts the Bool values true to the integer value 1 and false to 0.

For the conversion from Float to Integer, there are also:

• round(x) - the same as asInt(x), converts a float value into the nearest Integer;
• ceil(x) - returns the nearest integer that is not smaller and
• floor(x) - returns the nearest integer that is not larger.

There are also functions for converting String values to Integer:

• ascii(x) - converts a string value x to the ASCII code of the first character of the string;
  • if x is an empty string, the result of the function is zero.

Examples of conversions from Float to Integer:

{#
    asInt(3.6),
    asInt(-3.6),
    round(3.6),
    round(-3.6),
    ceil(3.6),
    ceil(-3.6),
    floor(3.6),
    floor(-3.6)
#}

{# 4, -4, 4, -4, 4, -3, 3, -4 #}

Examples of conversions from String to Integer:

{#
    asInt('3'),
    asInt('3.8'),
    asInt('abc'),
    ascii('abc'),
    ascii('')
#}

{# 3, 3, 0, 97, 0 #}

Examples of conversions from Bool to Integer:

{#
    asInt(true),
    asInt(false)
#}

{# 1, 0 #}

4.3.2 Conversion to Float

The function asFloat(x) converts every primitive non-float value x into the type Float:

• asFloat(x) converts the Integer value x to the corresponding Float value.
• asFloat(x) converts the String value x, which represents a valid Float literal, into the corresponding Float value;
  • if x is not a valid Float literal, asFloat returns zero;
• asFloat(x) converts the Bool value true into the value 1.0 and the value false into 0.0.

{#
    asFloat(7),
    asFloat('6.2'),
    asFloat('abc'),
    asFloat(true),
    asFloat(false)
#}

{# 7., 6.2, 0., 1., 0. #}

4.3.3 Conversion to String

There are four functions and an operator for converting values of other data types into strings:

The function asString(x) converts every non-string value x into String. It converts a value x into its string representation, according to the Wafl syntax.

There is a synonymous unary postfix operator $ with the same behavior.

{#
    asString(3),
    asString(3.14),
    asString(true),
    asString(false),
    asString('123'),
    asString( {# 1, 2.3, "abc", {# true, 's' #} #} ),
    asString([1,2,3,4,5,6,7,8,9,10]),

    3$,
    3.14$,
    true$,
    false$,
    '123'$,
    {# 1, 2.3, "abc", {# true, 's' #} #}$,
    [1,2,3,4,5,6,7,8,9,10]$
#}

{# '3', '3.14', 'true', 'false', '123', '{# 1, 2.3, \'abc\', {# true, \'s\' #} #}', '[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]', '3', '3.14', 'true', 'false', '123', '{# 1, 2.3, \'abc\', {# true, \'s\' #} #}', '[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]' #}

The function asPreview(x) is similar to asString, but returns a shorter string. For simple data, it behaves in the same way as asString. For larger structured data and longer strings, it extracts only a part of the complete string representation.

{#
    asPreview('01234567989'),
    asPreview( 
        '01234567890123456789012345678901234567890123456789'
        '01234567890123456789012345678901234567890123456789'
    ),
    asPreview([1,2,3,4,5,6,7,8,9,10]),
    asPreview(1..1000)
#}

{# '01234567989', '012345678901234567890123456789 ... 0123456789 (len=100)', '[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]', '[1, 2, 3, 4, 5, ..., 999, 1000] (len=1000)' #}

The function asChar(x) works with integers and logical values. It:

• converts an Integer into a string consisting of a single character with a given ASCII code;
• converts the logical value true into the string value "T" and the logical value false into the string value "F".

{#
    asChar(65),
    asChar(65.7),
    asChar(true),
    asChar(false)
#}

{# 'A', 'B', 'T', 'F' #}

The function toString(x,n) converts the float value x into string with n decimal places.

{#
    toString(1234.56789,0),
    toString(1234.56789,1),
    toString(1234.56789,2),
    toString(1234.56789,3)
#}

{# '1235.', '1234.6', '1234.57', '1234.568' #}

4.3.4 Conversion to Bool

The function asBool(x) converts every primitive non-bool value x into the type Bool:

• asBool(x) converts all non-zero Integer values to true and zero to false;
• asBool(x) converts all non-zero Float values to true and zero to false;
• asBool(x) converts string values "true" and "T" to true, and all other values to false.

{#
    asBool( 2 ),
    asBool( -3 ),
    asBool( 0 ),
    asBool( 2.1 ),
    asBool( -3.2 ),
    asBool( 0.0 ),
    asBool( "true" ),
    asBool( "True" ), // this is not same as "true"
    asBool( "T" ),
    asBool( "t" )     // this is not same se "T"
#}

{# true, true, false, true, true, false, true, false, true, false #}

4.4 Integer Functions

Wafl core library includes three integer functions:

• abs(x) - absolute value;
• sgn(x) - sign and
• between(x,a,b) - check whether x is between a and b and
• random(x) - random value.

4.4.1 Integer Function abs

The integer function abs(x) computes an absolute integer value of the given integer value x:

{#
    abs( 123 ),
    abs( -123 ),
    abs( -0 )
#}

{# 123, 123, 0 #}

4.4.2 Integer Function sgn

The integer function sgn(x) returns a sign of the number x. For positive values it returns 1, for negative values -1 and for zero it returns zero:

{#
    sgn( 20 ),
    sgn( -2 ),
    sgn( 0 )
#}

{# 1, -1, 0 #}

4.4.3 Integer Function between

The integer function between(x,a,b) checks whether the number x lies between the numbers a and b, including the limits. It is usually applied as x.between(a,b). This is equivalent to the expression x >= a and x <= b:

{#
    10 .between( 5, 20 ),
    10 .between( 10, 20 ),
    10 .between( 5, 10 ),
    10 .between( 5, 9 ),
    10 .between( 11, 20 )
#}

{# true, true, true, false, false #}

4.4.4 Function random

The integer function random(x) returns a random integer value in the range [0,x-1]. In the following example, we compute 20 random values in the range [0,4]:

{#
    random( 5 ), random( 5 ), random( 5 ), random( 5 ),
    random( 5 ), random( 5 ), random( 5 ), random( 5 ),
    random( 5 ), random( 5 ), random( 5 ), random( 5 ),
    random( 5 ), random( 5 ), random( 5 ), random( 5 ),
    random( 5 ), random( 5 ), random( 5 ), random( 5 )
#}

{# 0, 1, 3, 3, 2, 1, 2, 4, 0, 3, 2, 1, 4, 0, 0, 0, 3, 1, 4, 2 #}

Randomizing

By default the random number generator is reinitialized the first time it is used, using the current system timer as the seed. This is usually exactly what is expected and required.

However, sometimes it can be necessary to have the same random number sequence every time the program is executed (for debugging, benchmarking and some other cases). For such cases there is the clwafl command line option -nornd, which specifies a fixed predefined seed initialization.

Execute the previous program with:

clwafl -nornd program.wafl

and it will always return the same result.

4.5 Float Functions

The Wafl core library contains the following float functions:

• abs(x) - absolute value;
• sgn(x) - sign;
• between(x,a,b) - check whether x is between a and b and
• roundTo(x,y) - rounding;
• exp(x) - e to the power of x;
• ln(x) - natural logarithm;
• log(x) - logarithm to the base 10;
• log2(x) - logarithm to the base 2;
• pow(x,y) - x to the power of y;
• sqrt(x) - square root;
• sin(x) - sine;
• cos(x) - cosine;
• tan(x) - tangent;
• asin(x) - arc sine;
• acos(x) - arc cosine;
• atan(x) - arc tangent and
• atan2(y,x) - arc tangent of y/x (works for x=0).

The following conversion functions have already been presented in the previous sections:

• round(x) - converts a float value to the nearest Integer value;
• ceil(x) - returns the nearest Integer value that is not smaller and
• floor(x) - returns the nearest Integer value that is not larger.

4.5.1 Float Function abs

The float function abs(x) returns the absolute value of a given float value x.

{#
    abs( 123.456 ),
    abs( -123.456 ),
    abs( -0.0 )
#}

{# 123.456, 123.456, 0. #}

4.5.2 Float Function sgn

The float function sgn(x) returns the sign of the number x. For positive values it returns 1.0, for negative values -1.0 and for zero it returns zero:

{#
    sgn( 20.3 ),
    sgn( -2.4 ),
    sgn( 0.0 )
#}

{# 1., -1., 0. #}

4.5.3 Float Function between

The float function between(x,a,b) checks whether the number x lies between the numbers a and b, including the limit values. It is usually applied as x.between(a,b). This is equivalent to the expression x >= a and x <= b:

{#
    10.0 .between( 9.5, 10.5 ),
    10.0 .between( 10.0, 10.5 ),
    10.0 .between( 9.5, 10.0 ),
    10.0 .between( 10.1, 10.5 ),
    10.0 .between( 9.5, 9.9 )
#}

{# true, true, true, false, false #}

4.5.4 Float Function roundTo

The float function roundTo(x,y) rounds the float value x. The given float value y defines a least significant digit.

{#
    roundTo( 1234.56789, 0.001 ),
    roundTo( 1234.56789, 0.01 ),
    roundTo( 1234.56789, 0.1 ),
    roundTo( 1234.56789, 1. ),
    roundTo( 1234.56789, 10. ),
    roundTo( 1234.56789, 100. ),
    roundTo( 1234.56789, 1000. ),
    roundTo( 1234.56789, 10000. )
#}

{# 1234.568, 1234.57, 1234.6000000000001, 1235., 1230., 1200., 1000., 0. #}

4.5.5 Function exp

{#
    exp( -10.0 ),
    exp( 0.0 ),
    exp( 1.0 ),
    exp( 10.0 )
#}

{# 4.5399929762484854e-05, 1., 2.718281828459045, 22026.465794806718 #}

4.5.6 Function ln

The float function ln(x) returns the natural logarithm log_e x. It is defined for positive float values.

{#
    ln( 0.1 ),
    ln( 1.0 ),
    ln( 2.7182818284590452353602874),
    ln( 100. ),
    ln( 1000. )
#}

{# -2.3025850929940455, 0., 1., 4.605170185988092, 6.907755278982137 #}

4.5.7 Function log

The float function log(x) returns the logarithm log₁₀ x. It is defined for positive float values.

{#
    log( 0.001 ),
    log( 0.01 ),
    log( 0.1 ),
    log( 1.0 ),
    log( 10. ),
    log( 100. ),
    log( 1000. )
#}

{# -3., -2., -1., 0., 1., 2., 3. #}

4.5.8 Function log2

The float function log2(x) returns the logarithm log₂ x. It is defined for positive float values.

{#
    log2( 0.001 ),
    log2( 0.0078125 ),
    log2( 0.25 ),
    log2( 0.5 ),
    log2( 1.0 ),
    log2( 2. ),
    log2( 4. ),
    log2( 128. ),
    log2( 1000. )
#}

{# -9.965784284662087, -7., -2., -1., 0., 1., 2., 7., 9.965784284662087 #}

4.5.9 Function pow

The float function pow(x,y) returns xy - x to the power of y.

It is defined for positive x and any y. Negative x is only permitted if y is an integer. Zero x is only permitted for positive y.

{#
    pow( 2., 3. ),
    pow( 2., -3. ),
    pow( 2.5, -3.7 ),
    pow( -2., 3. ),
    pow( 0., 3.2 )
#}

{# 8., 0.125, 0.03369938443095647, -8., 0. #}

4.5.10 Function sqrt

The float function sqrt(x) returns the square root of x. It is defined for non-negative float values x.

{#
    sqrt(1.),
    sqrt(4.),
    sqrt(9.),
    sqrt(16.),
    sqrt(3433.32)
#}

{# 1., 2., 3., 4., 58.594538994687895 #}

4.5.11 Trigonometric functions

The following trigonometric functions are available:

• sin(x) - sine;
• cos(x) - cosine;
• tan(x) - tangent;
• asin(x) - arc sine;
• acos(x) - arc cosine;
• atan(x) - arc tangent and
• atan2(y,x) - arc tangent of y/x (works for x=0).

The angles are measured in radians. In addition, atan2(x,y) maps a pair of float values to the corresponding angle. If y is not zero, atan2(x,y) = atan(x/y), but atan2 is also defined for y=0.

{#
    sin(3.14/2.0) * cos(3.14/2.0),
    tan(3.14/2.0),
    asin(0.5) + acos(0.5),
    atan(0.5),
    atan2(1.0,2.0),
    atan2(1.0,0.0)
#}

{# 0.0007963264582434141, 1255.7655915007897, 1.5707963267948968, 0.4636476090008061, 0.4636476090008061, 1.5707963267948966 #}

4.6 String Functions

In this section we introduce the string functions.

The conversion functions (asChar, asString, ascii and toString) are presented in the previous sections.

4.6.1 Basic String Functions

strLen

The function strLen(x) returns the length of the string x.

It is important to understand that string x can contain any characters and that characters with the ASCII code zero are not treated as string terminals. Therefore, the String type can work not only with character strings, but also with byte strings.

There are two more general synonyms length and size.

{#
    strLen( "abc" ),
    strLen( "abc\0abc" ),
    length( "abc\0abc" ),
    size( "abc\0abc" )
#}

{# 3, 7, 7, 7 #}

strCat

The strCat(x,y) function computes the concatenation of two given strings. It is equivalent to the string operator +.

{#
    "abc" + "def",
    strCat( "abc", "def" )
#}

{# 'abcdef', 'abcdef' #}

isNull, ifNull

Due to the databases, the String type supports the special undefined value NULL. The isNull(s) function checks whether the string s is NULL. The function ifNull(s,x) returns s if s is not NULL, but x if s is NULL.

ifNull(s,x) == if isNull(s) then x else s

{#
    $-1,    //  This returns null string
    isNull('a'),
    isNull($-1),
    ifNull("abc","xyz"),
    ifNull($-1,"xyz")
#}

{# 'NULL', false, true, 'abc', 'xyz' #}

4.6.2 String Extraction Functions

String extraction functions extract a part of the given string and return it. Wafl core library contains the following string extraction functions:

sub and subStr

The function sub(s,p,n) returns a substring of character string s that starts at the zero based position p with the length n.

{#
    subStr( "abcdefgh", 0, 3 ),
    sub( "abcdefgh", 0, 3 ),
    sub( "abcdefgh", 2, 3 ),
    sub( "abcdefgh", -2, 5 ),
    sub( "abcdefgh", 5, 10 ),
    sub( "abcdefgh", 5, -2 )
#}

{# 'abc', 'abc', 'cde', '', 'fgh', '' #}

Special cases:

• if a negative position is specified, an empty string is returned (example sub( "abcdefgh", -2, 5 ));
• if a greater length is specified than available, a shorter string is returned (example sub( "abcdefgh", 5, 10 ))
• if a negative length is specified, an empty string is returned (example sub( "abcdefgh", 5, -2 )).

strLeft and strRight

The strLeft(s,n) function returns a substring containing the first n characters of the string s:

• for a positive n, that is less than strLen(s), it is the same as sub(s,0,n);
• for a negative n it is the same as strLeft(s,strLen(s)+n)
  • we can read it as “all but the last -n characters”;

The strRight(s,n) function returns a substring containing the last n characters of the string s:

• for a positive n, that is less than strLen(s), it is the same as sub(s,strLen(s)-n,n);
• for a negative n it is the same as strRight(s,strLen(s)+n)
  • we can read it as “all but the first -n characters”.

{#
    strLeft( "abcdefgh", 3 ),    //  first 3 characters
    strLeft( "abcdefgh", 10 ),   //  whole string
    strLeft( "abcdefgh", -5 ),   //  all but last 5 characters
    strLeft( "abcdefgh", -10 ),  //  empty string
    strRight( "abcdefgh", 3 ),   //  last 3 characters
    strRight( "abcdefgh", 10 ),  //  whole string
    strRight( "abcdefgh", -5 ),  //  all but first 5 characters
    strRight( "abcdefgh", -10 )  //  empty string
#}

{# 'abc', 'abcdefgh', 'abc', '', 'fgh', 'abcdefgh', 'fgh', '' #}

strLTrim, strRTrim and strTrim

The function strLTrim(s) returns the largest substring of s that does not contain any leading, non-visible characters.

The function strRTrim(s) returns the largest substring of s that does not contain any trailing, non-visible characters.

The function strTrim(s) returns the largest substring of s that contains neither leading nor trailing, non-visible characters.

{#
    strLTrim( "\0 \t \n   abcd \b \003 \0 \r " ),
    strRTrim( "\0 \t \n   abcd \b \003 \0 \r " ),
    strTrim( "\0 \t \n   abcd \b \003 \0 \r " )
#}

{# 'abcd \010 \003 \000 \015 ', '\000 \011 \012   abcd', 'abcd' #}

4.6.3 String Index and Slice Operators

The index operator s[i] is equivalent to subStr(s, i %% strLen(s) , 1). This means that indexing beyond the length is possible. The index operator s[i] is similar, but not equivalent to subStr(s,i,1). They are only equivalent if the following applies: 0 <= i < strLen(s)

{# 
  s[-4], s[-3], s[-2], s[-1],
  s[0], s[1], s[2], s[3], 
  s[4], s[6], s[7], s[8]
#}
where {
  s = "abcd";
}

{# 'a', 'b', 'c', 'd', 'a', 'b', 'c', 'd', 'a', 'c', 'd', 'a' #}

The slice operator uses a similar syntax to the index operator, but behaves like subStr, strLeft and strRight. If 0 < n < m <= strLen(s), then:

• s[:n] is the same as strLeft(n), it extracts the first n characters;
• s[n:] is the same as strRight(-n)), it extracts all but first n characters and
• s[n:m] is the same as strRight(strLeft(s,m),-n), and the same as subStr(s,n,m-n).

If the index n is negative or greater than strLen(s), then n %% strLen(s) is used. The same applies to m.

{# 
    s[:6],
    s[:-2],
    s[2:],
    s[-6:],
    s[2:6], 
    s[2:-2], 
    s[-6:6],
    s[-6:-2]
#}
where {
  s = "abcdefgh";
}

{# 'abcdef', 'abcdef', 'cdefgh', 'cdefgh', 'cdef', 'cdef', 'cdef', 'cdef' #}

It is often easier to use the slice operator than extraction functions, but basically they do the same thing.

4.6.4 String Search Functions

The Wafl core library contains the following string search functions:

All search functions return the start position of the second specified string in the first specified string if it is found, and -1 if it is not found.

Functions whose names end with ‘I’ are case-insensitive: strPosI, strNextPosI, strLastPosI, and strNextLastPosI.

strPos, strPosI, strNextPos and strNextPosI

The function strPos(s,p) returns the position of the first occurrence of the string p in the string s.

The function strPosI(s,p) returns the position of the first occurrence of the string p in the string s, ignoring upper and lower case.

The function strNextPos(s,p,i) returns the position of the first occurrence of the string p in the string s after position i.

The function strNextPosI(s,p,i) returns the position of the first occurrence of the string p in the string s after position i, ignoring upper and lower case.

{# 
    strPos( s, n ),     //  not found
    strPos( s, x ),     
    strNextPos( s, x, 0 ),
    strNextPos( s, x, 3 ),
    strNextPos( s, x, 6 ),
    strNextPos( s, x, 9 )
#}
where {
    s = "abcabcabcab";
    x = "ab";
    n = "xxx";
};

{# -1, 0, 3, 6, 9, -1 #}

strLastPos, strLastPosI, strNextLastPos and strNextLastPosI

The function strLastPos(s,p) returns the position of the last occurrence of the string p in the string s.

The function strPosI(s,p) returns the position of the last occurrence of the string p in the string s, ignoring upper and lower case.

The function strNextPos(s,p,i) returns the position of the last occurrence of the string p in the string s before the position i.

The function strNextPosI(s,p,i) returns the position of the last occurrence of the string p in the string s before the position i, ignoring upper and lower case.

{# 
    strLastPos( s, n ),     //  not existing
    strLastPos( s, x ),     
    strNextLastPos( s, x, 9 ),
    strNextLastPos( s, x, 6 ),
    strNextLastPos( s, x, 3 ),
    strNextLastPos( s, x, 0 )
#}
where {
    s = "abcabcabcab";
    x = "ab";
    n = "xxx";
};

{# -1, 9, 6, 3, 0, -1 #}

strBeg and strEnd

The functions strBeg and strEnd check whether the first string has the second string at the beginning or at the end:

{#
    strBeg( "abcdef", "ab" ),
    strBeg( "abcdef", "cd" ),
    strBeg( "abcdef", "ef" ),
    strEnd( "abcdef", "ab" ),
    strEnd( "abcdef", "cd" ),
    strEnd( "abcdef", "ef" )
#}

{# true, false, false, false, false, true #}

strHasSub and strHasSubI

The strHasSub(s,ss) function checks whether the string s contains the substring ss. The strHasSubI function does the same, but ignores case:

{#
    strHasSub( "abcdef", "ab" ),
    strHasSub( "abcdef", "bc" ),
    strHasSub( "abcdef", "ef" ),
    strHasSub( "abcdef", "ac" ),
    strHasSub( "abcdef", "AB" ),
    strHasSub( "abcdef", "BC" ),
    strHasSub( "abcdef", "EF" ),
    strHasSub( "abcdef", "AC" )
#}

{# true, true, true, false, false, false, false, false #}

{#
    strHasSubI( "abcdef", "ab" ),
    strHasSubI( "abcdef", "bc" ),
    strHasSubI( "abcdef", "ef" ),
    strHasSubI( "abcdef", "ac" ),
    strHasSubI( "abcdef", "AB" ),
    strHasSubI( "abcdef", "BC" ),
    strHasSubI( "abcdef", "EF" ),
    strHasSubI( "abcdef", "AC" )
#}

{# true, true, true, false, true, true, true, false #}

4.6.5 Substring Counting Functions

The Wafl core library contains the following fuctions for counting substrings:

All counting functions return the number of occurences of the given substring in the given string. The functions whose names end with ‘I’ ignore the upper and lower case. The functions with ‘Dis’ in the names count only the disjunctive substrings.

{# 
    strCountSub('aaaaaA','aa'),
    strCountSubI('aaaaaA','aa'),
    strCountSubDis('aaaaaA','aa'),
    strCountSubDisI('aaaaaA','aa')
#}

{# 4, 5, 2, 3 #}

4.6.6 String Replace Functions

The Wafl core library contains the following functions for replacing the parts of the strings with another string:

Each of the strReplace* functions evaluates a new string and does not change any of the given strings.

The function strReplace(s,p,x,i) returns a copy of string s in which the i.th occurrence of the substring p is replaced by x. The string s remains unchanged.

The function strReplaceI(s,p,x,i) is similar to the function strReplace, but ignores upper and lower case when searching for p.

The function strReplaceAll(s,p,x) returns a copy of the string s in which all occurrences of substring p are replaced by x. The string s remains unchanged.

The function strReplaceAllI is similar to the function strReplaceAll, but ignores upper and lower case when searching for p.

{#
    strReplace( s, 'a', '@', 2 ),
    strReplaceI( s, 'a', '@', 2 ),
    strReplaceAll( s, 'a', '@' ),
    strReplaceAllI( s, 'a', '@' )
#}
where {
    s = "abABabAB";
}

{# 'abAB@bAB', 'ab@BabAB', '@bAB@bAB', '@b@B@b@B' #}

4.6.7 Functions strSplit... and strJoin

The function strSplit(s,p) returns a list of all substrings of the string s that are separated by the substring p.

The function strJoin(lst,p) concatenates all elements of the list lst and inserts the separator p between them.

strSplit( 'a,bb,c,dd,e', ',' )

['a', 'bb', 'c', 'dd', 'e']

strJoin( ['a','b','c','d','e','f','g','h'], ';' )

a;b;c;d;e;f;g;h

strJoin( strSplit( 'a,bb,c,dd,e', ','), ';' )

a;bb;c;dd;e

The function strSplitTrim is similar to strSplit, but it detects and removes all empty spaces before and after the separators. It is functionally equivalent, but more efficient than the mapping of strTrim after the split:

s.strSplit(p).map(strTrim) == s.strSplitTrim(p)

The function strSplitLines(s) is similar to strSplit(s,'\n'), but it detects and removes both LF (Linux, ‘\n’) and CRLF (Windows, ‘\r\n’) new line sequences:

{#
    strSplit( '\nabc\ndef\nghi\n', '\n' ),
    strSplit( '\r\nabc\r\ndef\r\nghi\r\n', '\n' ),
    strSplitLines( '\nabc\ndef\nghi\n' ),
    strSplitLines( '\r\nabc\r\ndef\r\nghi\r\n' )
#}

{# ['', 'abc', 'def', 'ghi', ''], ['\015', 'abc\015', 'def\015', 'ghi\015', ''], ['', 'abc', 'def', 'ghi', ''], ['', 'abc', 'def', 'ghi', ''] #}

The function strSplitLinesTrim is similar to strSplitTrim and strSplitLines. It is functionally equivalent, but more efficient than mapping strTrim after using strSplitLines:

s.strSplitLines().map(strTrim) == s.strSplitLinesTrim()

The function strChars converts a string into a list of characters.

{#
    strChars( 'abc\ndef' )
#}

{# ['a', 'b', 'c', '\012', 'd', 'e', 'f'] #}

4.6.8 Encoding functions

Sometimes we need to encode a string in a format that follows a specific syntax. Wafl contains four string encoding functions. All these functions have the common type: (String -> String).

The function strEncodeHtml(s) returns an encoded string that can be inserted into HTML. All special characters are replaced by corresponding HTML escape sequences:

strEncodeHtml( "abc&<>def" )

abc&<>def

The function strEncodeSql(s) returns an encoded string ready for use in SQL string literals. All special characters are replaced by SQL escape sequences:

strEncodeSql( "abc'quotes'abc" )

abc''quotes''abc

The function strEncodeUri(s) returns an encoded string according to the rules of URI syntax:

strEncodeUri( "a + b = c" )

a%20%2B%20b%20%3D%20c

The function strEncodeWafl(s) returns an encoded string according to the Wafl syntax:

strEncodeWafl( "a\n \0 \'\"..." )

a\012 \000 \'\"...

4.6.9 Other String Functions

Here we discuss three other string functions:

The function strLowerCase converts all letters in a string to lower case.

The function strUpperCase converts all letters in a string to upper case.

{#
    strLowerCase( 'aAbBcC' ),
    strUpperCase( 'aAbBcC' )
#}

{# 'aabbcc', 'AABBCC' #}

The function strReverse returns the reversed string.

{#
    strReverse( 'aAbBcC' )
#}

{# 'CcBbAa' #}

4.6.10 UTF-8 Functions

To handle UTF-8 strings correctly, please only use the functions that handle strings as sequences of UTF-8 multibyte code-points. Many of the usual string functions work well with UTF-8, also.

Please note that two important functionalities are not yet supported by the Wafl library:

• string ordering handles strings as single-byte characters strings;
• case insensitive functions do not work well with UTF-8 multibyte characters.

Most of the specific UTF-8 behavior is covered by the following functions.

BOM Functions

Some applications require that files with UTF-8 content have a UTF-8 BOM (Byte Order Mark) sequence at the beginning of the file. The following functions enable the handling of UTF-8 BOM.

The function utfBom() returns the UTF-8 BOM.

The function utfIsBom(s) checks whether the string content corresponds exactly to the UTF-8 BOM.

The function utfHasBom(s) checks whether the string begins with a UTF-8 BOM.

{#
    utfBom(),
    utfIsBom( utfBom() ),
    utfIsBom( 'abc' ),
    utfHasBom( utfBom() + 'abc' ),
    utfHasBom( 'abc' )
#}

{# '\357\273\277', true, false, true, false #}

The function utfAddBom(s) returns a string with a UTF-8 BOM appended to the beginning, if it is not already present.

The function utfTrimBom(s) returns a string without a leading UTF-8 BOM.

{#
    utfAddBom('abc'),
    utfHasBom( utfAddBom('abc') ),
    utfTrimBom( utfAddBom('abc') ),
    utfHasBom( utfTrimBom( utfAddBom('abc') ) )
#}

{# '\357\273\277abc', true, 'abc', false #}

UTF-8 Validity Functions

The function utfIsValid(s) checks whether a string is a valid UTF-8 string. Please note that each single-byte characters string is a valid UTF-8 string.

The function utfRepInvalid(s,c) returns a strings in which all invalid UTF-8 code-points are replaced by the character c.

{#
    utfIsValid( sub('abc€def',4,4) ),
    utfRepInvalid( sub('abc€def',0,4), '@' ),  //  only the first byte of a MB 
    utfRepInvalid( sub('abc€def',4,4), '@' )  //  only the second byte of a MB
#}

{# false, 'abc@', '@@de' #}

utfLen

The function utfLen(s) returns the string length by counting the complete UTF-8 code-points. The string length in code-points is always less than or equal to the length in bytes (strLen, length or size).

{#
    strLen( 'abc€def' ),
    utfLen( 'abc€def' )
#}

{# 9, 7 #}

utfLessThan and sortUtf8

The regular comparison operators work for single-byte strings only. The function utfLessThan(s1,s2) uses the UTF-8 multi-byte collation, as implemented for the operating system.

The sortUtf8 function is a equivalent to sort(_,utfLessThan).

utfAt

The function utfAt(s,i) is similar to the indexing operator s[i], but uses indices based on code-points. It returns the i-th UTF-8 code-point of the string s.

For more details, see indexing operator.

{#
    s[0], s[1], s[2], s[3],
    s.utfAt(0), s.utfAt(1), s.utfAt(2), s.utfAt(3)
#}
where {
  s = "abАБабAB";
}

{# 'a', 'b', '\320', '\220', 'a', 'b', '\320\220', '\320\221' #}

{#
    s[-1], s[-2], s[-3], s[-4],
    s.utfAt(-1), s.utfAt(-2), s.utfAt(-3), s.utfAt(-4)
#}
where {
  s = "abАБабAB";
}

{# 'B', 'A', '\261', '\320', 'B', 'A', '\320\261', '\320\260' #}

utfSub, utfSlice, utfLeft, utfRight

The function utfSub(s,p,n) is similar to subStr(s,p,n), but uses code-point based indices. It returns a substring of the string s, beginning at the zero based position p with length n, where position and length are counted based on UTF-8 code-points instead of characters.

For more details, please read subStr.

{#
    subStr( "abcdАБВГабвгABCD", 0, 8 ),
    utfSub( "abcdАБВГабвгABCD", 0, 8 )
#}

{# 'abcd\320\220\320\221', 'abcd\320\220\320\221\320\222\320\223' #}

The function utfSlice(s,n,m) is similar to the string slice operator s[n:m], but uses code-point based indices. It returns a substring of the string s, starting at the zero based position n and ending before the position m, where positions n and m are counted based on UTF-8 code-points instead of characters.

For more details, see string slice operator.

{#
    "abcdАБВГабвгABCD" [2:6],
    utfSlice( "abcdАБВГабвгABCD", 2, 6 )
#}

{# 'cd\320\220', 'cd\320\220\320\221' #}

The function utfLeft(s,n) is similar to the string function strLeft, but uses code-point based indices. It returns a substring containing the first n UTF-8 code-points of the string s.

For more details please study strLeft.

{#
    strLeft( "abcdАБВГабвгABCD", 6 ),
    utfLeft( "abcdАБВГабвгABCD", 6 )
#}

{# 'abcd\320\220', 'abcd\320\220\320\221' #}

The function utfRight(s,n) is similar to string function strRight, but uses indices based on code-points. It returns a substring containing the last n UTF-8 code-points of the string s.

For more details, please see strRight.

{#
    strRight( "abcdАБВГабвгABCD", 6 ),
    strRight( "abcdАБВГабвгABCD", 6 )
#}

{# '\320\263ABCD', '\320\263ABCD' #}

Other UTF-8 Functions

The function utfChars(s) is similar to the string function strChars, but uses code-points instead of characters. It returns a list of all UTF-8 code-points of the string s.

For more details please study strChars.

{#
    strChars( "abАБабAB" ),
    utfChars( "abАБабAB" )
#}

{# ['a', 'b', '\320', '\220', '\320', '\221', '\320', '\260', '\320', '\261', 'A', 'B'], ['a', 'b', '\320\220', '\320\221', '\320\260', '\320\261', 'A', 'B'] #}

The function utfReverse(s) is similar to the string function strReverse, but uses code-points instead of characters. It returns a reversed string, taking care to preserve the UTF-8 code-points.

For more details, please read strReverse.

{#
    strReverse( "abАБабAB" ),
    utfReverse( "abАБабAB" )
#}

{# 'BA\261\320\260\320\221\320\220\320ba', 'BA\320\261\320\260\320\221\320\220ba' #}

Using Regular String Functions

Many of the regular string functions work well with UTF-8 strings, as long as the arguments are valid UTF-8 strings:

5 List Type

List is the most important and most frequently used structured data type in functional programming languages. List is a sequential type, which means that a list can contain many elements in an ordered sequence. In Wafl, a list can consist of elements of any type, but all elements of a list must have the same type.

Due to the importance of the concept of list processing, it is recommended to study this chapter carefully. The functions discussed here are essential for programming in Wafl.

5.1 List Literals

The general list type is written as List['1], where '1 denotes a type variable (a pure polymorphic type). Each specific list in a program must have a specific type, where this free type is fully defined.

A list without elements is called an empty list. An empty list is written as nil or []. These two syntaxes are equivalent.

Non-empty list literals are written as elements enclosed in square brackets and separated by commas.

{#
    [],
    nil,
    [1,2,3],                    //  List[Int]
    ['a','b','c','d'],          //  List[String]
    [[1,2],[3,4,5],[6,7,8]]     //  List[List[Int]]
#}

{# [], [], [1, 2, 3], ['a', 'b', 'c', 'd'], [[1, 2], [3, 4, 5], [6, 7, 8]] #}

In the previous example we have the following lists:

• an empty [];
• an empty nil;
• a list of integers with 3 elements;
• a list of strings with 4 elements and
• a list of list of integers, with 3 elements.

It is allowed to specify a comma separator after the last element of a list. It has no function there, but it makes it easier to edit, copy, and comment/uncomment list elements.

5.2 Basic List Functions

The processing of list elements is often explained using the terms head and tail of the list. The head stands for the first element of the list and the tail stands for all but the first element of the list. Both head and tail only make sense for non-empty lists.

The basic list functions include elementary operations to check the list size, to extract its head, tail or a sub-list, to construct a list and to compare two lists.

List Comparison

Lists can be compared for equality. The operators == and != evaluate the expected results:

{#
    [] = nil,
    [] != nil,
    [] = [1,2,3],
    [] != [1,2,3],
    [1,2,3] = [1,2,3],
    [1,2,3] = [1,2,3,4,5],
    [1,2,3] != [1,2,3],
    [1,2,3] != [1,2,3,4,5]
#}

{# true, false, false, true, true, false, false, true #}

empty and nonEmpty

To check whether a list is empty or not, the functions empty(lst) and nonEmpty(lst) are available. They are equivalent to comparing a list with an empty list literal.

{#
    empty( [] ),
    empty( nil ),
    empty( [1,2,3] ),
    [] = nil,
    [1,2,3] = nil
#}

{# true, true, false, true, false #}

{#
    nonEmpty( [] ),
    nonEmpty( nil ),
    nonEmpty( [1,2,3] ),
    [] != nil,
    [123] != nil
#}