INTRODUCTION

This manual page documents the language as understood by the KL-EL library. For documentation on how to embed the KL-EL compiler and interpreter in an application, see klelapi(3). For a tutorial on how to use the library, see kleltut(3).

The language understood by KL-EL is an expression language. Everything in the language is an expression that has a value. The purpose of the library is to allow these expressions to be input at runtime and have the application make use of the resulting values in some fashion.

There are two kinds of KL-EL expressions: value expressions (often referred to as simply "expressions") and guarded commands. Guarded commands are more complicated, but they are also very useful in certain situations. Because guarded commands are more complex than value expressions, they will be covered second.

Expressions in KL-EL are not sensitive to whitespace; whitespace is only significant inside literal strings.

A NOTE ON TYPES

Every value in KL-EL has one and only one type, and the type of a given expression never changes. That makes KL-EL strongly typed, and this typing discipline is possibly its most interesting feature. KL-EL was designed to be useful in applications where an expression is compiled only once but executed thousands or millions of times with different parameters, and possibly on ephemeral or forensic data. If typechecking were not performed until evaluation, it is possible that a failure could occur after millions of executions on some set of inputs, rendering the entire run (or a large portion of it) invalid. In the best case, the expression could be fixed and execution could pick up where it left off, but in the worst case, it may be impossible to recover the values used previously or begin execution again. Checking types at compile time also makes things faster for multiple executions of a given expression, since types do not need to be checked on each execution.

KL-EL understands four types:

Booleans (either true or false)
Integers (signed 64-bit)
Reals (IEEE double-precision floating point)
Strings (sequences of bytes with no length limitations, embedded NULL bytes are allowed)

Functions are provided to transform values of one type to another type as necessary. In general, there is no concept of type promotion. Expressions like

    "123" + 5

don't work since addition is not defined for strings. There is a slight relaxation of this restriction for expressions involving a mixture of integers and reals -- integers are silently promoted to real values when they are used in arithmetic expressions involving reals. This is the only exception to the typing discipline. Note that the exception only applies to arithmetic expressions -- functions expecting real arguments will not accept integer arguments.

NAMES

Any top-level expression can be named, and this name can be extracted from the compiled expression at runtime. This is useful in situations where there may be many unrelated expressions (say, in a configuration file), and it would be useful to identify expressions in diagnostics or other output.

To name an expression, simply prefix it with a name and a colon. A name in this case may consist of letters, numbers, and underscores, and must begin with a letter. For example, this gives an expression "1 + 1" the name "Example":

  Example : 1 + 1

Once again, note that only top-level expressions may be named.

VALUE EXPRESSIONS

Value expressions are simple expressions that, when evaluated, produce a value. There are seven different kinds of value expressions:

Literals
Variables
Function calls
Unary (arithmetic negation, logical negation, bitwise negation)
Binary (arithmetic, string concatenation, comparison)
Ternary (conditional evaluation)
Let (lexical scoping)

Each of these expression types is covered below. For more information on how to retrieve the value of an evaluated expression using the library, see klelapi(3).

LITERAL BOOLEANS

There is no literal syntax for Boolean values. The standard variables "true" and "false" are defined and have their expected meanings.

LITERAL NUMBERS

Numbers can be written in octal, decimal, or hexadecimal. Octal numbers are prefixed with '0o', and hexadecimal numbers are prefixed with '0x'. Sequences of decimal digits with no prefix are assumed to be in decimal.

Real numbers are written in decimal, with '.' as the decimal point. The decimal point and one digit after it are obligatory. An optional exponent can be provided by suffixing the number with 'e', an optional minus sign (indicating a negative exponent), and at least one decimal digit.

LITERAL STRINGS

Literal strings are written enclosed in double quotes. Any character may appear between the double quotes except for newlines, double quotes, backslashes, percent signs, and literal zeros (NULL bytes). By using escapes, these and other characters can be conveniently inserted. The following escapes are defined:

\\ (backslash)
\" (double quote)
\r (carriage return)
\n (linefeed)
\% (percent sign)
\xHH (the byte whose value is HH in hexadecimal)

Literal strings may also contain interpolations. Interpolations are of one of the forms

    %{name}

    %(name)

It is because of this syntax that percent signs are recognized as an escapable character. Interpolations take the value of the named variable, convert that value to a string, and embed the stringified value into the string produced by evaluating the string literal. Variable names enclosed in curly brackets have their value inserted as is, while those enclosed in parentheses have their values inserted after any special characters have been quoted (this is referred to as a quoted interpolation). In this case "special characters" and the character used to quote them are defined by the application using the library, with sensible defaults.

VARIABLES

Variables can be used anywhere where an expression is expected. Variables are of static type, but their values may change at any time. Variables are either exported from the application using the library (referred to as the "host" or "host application"), or they are introduced by a let expression (see below). Applications using the library can export any number of variables into the KL-EL environment, allowing for simple interaction between the host application and KL-EL. For information on how applications export variables into the KL-EL environment, see klelapi(3).

KL-EL comes with a standard library that defines several variables. New variables can be introduced inside an expression by introducing a new scope using a let expression; these expressions are discussed below.

FUNCTION CALLS

It is not possible to define a function in KL-EL, but the application using the library can export as many functions as it needs. KL-EL also comes with a standard library of functions. The functions in this library are automatically available for use in any expression unless specifically disallowed by the host application.

A function call uses syntax familiar from C:

    name(arg0, arg1, ... argN)

Due to the way types are represented in the type checker, functions are limited to thirteen arguments. It is important to note that functions are not first-class values; they can neither be passed as arguments to nor returned as the result of other functions.

For more information on how to export a function into the KL-EL environment, see klelapi(3).

UNARY OPERATIONS

Below three (3) unary operators are defined in terms of their operator symbol, operand type, and result type. The type codes B, I, and R represent boolean, integer, and real types, respectively.

                       ======= DEFINITION =======
                               o  l  r  r
                               p  e  i  e
                               e  f  g  s
                               r  t  h  u
                               a  t  t  l
                               t        t
                               o
                               r
   ======  OPERATION  ===========================
   Arithmetic Negation         -     I  I
   Arithmetic Negation         -     R  R
   Bitwise NOT                 ~     I  I
   Boolean Negation            !     B  B

Note that unary operators bind more tightly than any binary operator.

BINARY OPERATIONS

Below twenty-one (21) binary operators are defined in terms of their operator symbol, operand types, and result type. These operators are listed in decreasing order of precedence. The type codes B, I, R, and S represent boolean, integer, real, and string types, respectively.

                       ======= DEFINITION =======
                               o  l  r  r
                               p  e  i  e
                               e  f  g  s
                               r  t  h  u
                               a  t  t  l
                               t        t
                               o
                               r
   ======  OPERATION  ===========================
   Multiplication              *  I  I  I
   Multiplication              *  R  I  R
   Multiplication              *  I  R  R
   Multiplication              *  R  R  R
   Division                    /  I  I  I
   Division                    /  R  I  R
   Division                    /  I  R  R
   Division                    /  R  R  R
   Modular Division            %  I  I  I
   Logical Conjunction        &&  B  B  B
   Bitwise Roll Left          <<  I  I  I
   Bitwise Roll Right         >>  I  I  I
   String Concatenation        .  S  S  S
   Addition                    +  I  I  I
   Addition                    +  R  I  R
   Addition                    +  I  R  R
   Addition                    +  R  R  R
   Subtraction                 -  I  I  I
   Subtraction                 -  R  I  R
   Subtraction                 -  I  R  R
   Subtraction                 -  R  R  R
   Logical Disjunction        ||  B  B  B
   Bitwise AND                 &  I  I  I
   Bitwise XOR                 ^  I  I  I
   Bitwise OR                  |  I  I  I
   Less than                   <  I  I  B
   Less than                   <  R  R  B
   Less than                   <  S  S  B
   Greater than                >  I  I  B
   Greater than                >  R  R  B
   Greater than                >  S  S  B
   Less than or equal         <=  I  I  B
   Less than or equal         <=  R  R  B
   Less than or equal         <=  S  S  B
   Greater than or equal      >=  I  I  B
   Greater than or equal      >=  R  R  B
   Greater than or equal      >=  S  S  B
   Equal                      ==  B  B  B
   Equal                      ==  I  I  B
   Equal                      ==  R  R  B
   Equal                      ==  S  S  B
   Not equal                  !=  B  B  B
   Not equal                  !=  I  I  B
   Not equal                  !=  R  R  B
   Not equal                  !=  S  S  B
   Regex match                =~  S  S  B
   Regex non-match            !~  S  S  B

Note that the environment's localization settings (particularly collation order) may affect the result when comparing strings using the relational operators.

For regular expression matches, the right operand is the expression; it is expected to be a string in PCRE syntax. For more information, see pcre(3).

Parentheses can be used to override the normal order of operations when necessary.

THE TERNARY OPERATOR

KL-EL defines a single ternary operator, '?'. Ternary expressions are of the form:

    predicate ? expr1 : expr2

where predicate is an expression of Boolean type and expr1 and expr2 are two expressions of the same type. If predicate evaluates to true, expr1 is evaluated, otherwise expr2 is evaluated. Note that parenthesis are generally required around predicates unless they are syntactically trivial. The type of a ternary expression is the type of expr1 or expr2.

LET EXPRESSIONS

KL-EL is lexically scoped in the ALGOL tradition. New environments are created using let expressions. These expressions are of the form:

    let var = expr1 in expr2

The value of this expression is the value of expr2 with every occurrence of var substituted by the value of expr1. As let expressions are normal expressions, they can be nested. In particular, this is a valid (and common) idiom:

    let var1 = expr1 in
      let var2 = expr2 in
        let var3 = expr3 in
          var1 + var2 + var3

Variables in nested scopes can shadow variables in outer scopes, though this functionality is best used sparingly. Variables exported from the host application are in the outermost scope.

GUARDED COMMANDS

Aside from value expressions, KL-EL supports guarded commands. A guarded command consists of a guard of boolean type, a call to the special function eval, and an optional list of return codes. The intent of guarded commands is to provide the host application with a command (where the meaning of "command" is defined by the host application), along with a set of supporting arguments, that is valid only when the guard expression is valid.

Guarded commands have one of the following forms:

  if (guard) then eval(interpreter, program, arg0, ... argN)

  if (guard) then eval(interpreter, program, arg0, ... argN) pass [code0, ... codeN]

  if (guard) then eval(interpreter, program, arg0, ... argN) fail [code0, ... codeN]

In these forms guard must be a value expression of boolean type, interpreter and program must be constant strings, and codes must be literal integers. The remaining arguments may be of any type.

Guarded commands are useful in situations where it is important to distinguish between the action and the guard. Take for example a file-finding application. In this hypothetical application, a guarded command is used to specify a command to execute on every file that matches its expression thereby allowing the application to customize its behavior based on observed file attributes.

In a guarded command, the arguments to the eval function and the code values are passed as-is to the host application. It is up to the application to determine their meaning. For a discussion on how guarded commands are represented in host applications, see klelapi (3).

It is important to note that guarded commands cannot be nested inside other expressions or guarded commands.