ChangeLog.txt

==========
0.1 -> 0.2 WIP
==========

Language changes:
-----------------
* A new 'with' statement provides syntactic sugar for monadic control flow.
  Within a block, the subsequent statements after a 'with' statement are
  passed as a capture-by-value lambda to the function specified as the 'with'
  statement's operand.
    // 0.2
    foo(x) {
        with y = bar(x);
        with z = bas(y);
        qux(z);
    }

    // desugars to

    foo(x) {
        bar(y => {
            bas(z => {
                qux(z);
            }, y);
        }, x);
    }
  Thanks to Arvid Picciani.

* The 'primitiveCopy' primitive has been renamed to 'bitcopy'.

* The 'pointerCast' primitive has been renamed to 'bitcast', and has been
  generalized to allow bitcasting between any two types.

* New 'memcpy' and 'memmove' primitives are provided. Unlike the libc
  functions, these primitives return void, accept pointers of any type,
  and map to invocations of the 'llvm.memcpy' and 'llvm.memmove' intrinsics,
  with an alignment hint equal to the strictest alignment of the pointed-to
  destination and source types.

* Compiler hook functions are now implicitly defined in a special
  '__operators__' module instead of looked up in the 'prelude' module.

* Static string literals and string constant literals have been combined.
  String literals now always behave like static strings and evaluate to
  singleton Static["string"] values. These static strings can now be
  iterated and indexed like StringConstants. lib-clay provides a
  StringLiteralRef type in order to reference constant strings at runtime.
  A string literal may now also be used as a postfix operator; `foo"bar"` is
  equivalent to `foo("bar")`.

    // 0.1
    #foo          // value of type Static[#foo]
    #"bar"        // value of type Static[#bar]
    "bas"         // value of type StringConstant
    String("zim") // value of type String
    octal(#"177") // octal value of type Int

    // 0.2
    "foo"                 // value of type Static["foo"]
    "bar"                 // value of type Static["bar"]
    StringLiteralRef"bas" // value of type StringLiteralRef
    String"zim"           // value of type String
    octal"177"            // octal value of type Int

* The 'static' keyword has been replaced with the '#' operator in argument
  declarations and expressions. The '#' operator has the same precedence as
  prefix operators. In argument declarations, the '#' is now optional for
  static string literal arguments.

    // 0.1
    foo(static Foo) {}
    bar(static 3) {}
    bas(static #string) {}
    [n] zim(static n) = static n+1;

    // 0.2
    foo(#Foo) {}
    bar(#3) {}
    bas("string") {}
    [n] zim(#n) = #(n+1);

* User-defined operators are now supported. Any string consisting of the
  characters "=!<>+-*/\%~|&" (except for the reserved tokens "-->", "<--",
  "->", "=>", and "=") may be used as a prefix or infix operator. Operator
  names may be used as identifiers by surrounding them with parens. Prefix
  operator expressions desugar into calls to the `prefixOperator` function,
  and infix operator expressions into calls to the `infixOperator` function,
  as follows:

    // 0.2
    foo(a, b, c, d) {
        a = +a;
        a = b + c * d;
    }
    
    // desugars to
    foo(a, b, c, d) {
        a = prefixOperator((+), a);
        a = infixOperator(b, (+), c, (*), d);
    }

  As shown above, infix operator sequences are desugared into a single
  variadic `infixOperator` call, which allows the library to control
  precedence, implement custom composition behavior such as Python-style
  comparison chaining, and to optimize certain sequences of operator
  applications.

  Thanks to Jeremy Clifford.

* The address-of operator has been changed from prefix `&` to prefix `@`. `&`
  is now a user-defined operator character.

    // 0.1
    foo(x, y) { memcpy(&x, &y, TypeSize(Type(x))); }

    // 0.2
    foo(x, y) { memcpy(@x, @y, TypeSize(Type(x))); }

  Thanks to Jeremy Clifford.

* The update-assignment statement syntax has been changed from `a <op>= b;` to
  `a <op>: b;`. `<op>` can be any user-defined operator. Prefix operators
  may now also be used in update assignment with the statement form `<op>: a;`.

    // 0.1
    foo(x, y) {
        x += 1;
        y = -y;
    }

    // 0.2
    foo(x, y) {
        x +: 1;
        -: y;
    }

  Thanks to Jeremy Clifford.

* Pattern guard syntax has been changed from `[T | Predicate?(T)]` to
  `[T when Predicate?(T)]`. `|` is now a user-defined operator character.

    // 0.1
    [T | Sequence?(T)] foo(xs:T) { for (x in xs) println(x); }

    // 0.2
    [T when Sequence?(T)] foo(xs:T) { for (x in xs) println(x); }

  Thanks to Jeremy Clifford.

* If, switch, and while statements may now use variable binding, assignment,
  or expression statements in the conditional before the condition expression.
  Variables bound in the conditional are scoped for the body of the
  subsequent statement. In a while loop, the statements are rerun on every
  iteration.

    // 0.2
    foo() {
        if (var x, y? = bar(); y?)
            println(x);

        var i = 0;
        while (inc(i); i < 5)
            println(i);
    }

* The iterator protocol used by the `for` loop has been changed. The `for`
  syntax now desugars as follows:

    // 0.2
    foo(xs) {
        for (a,b,c in xs)
            bar();

    // desugars to:
    foo(xs) {
        {
            forward _sequence = xs;
            forward _iter = iterator(_sequence);
            while (var _value = nextValue(_iter); hasValue?(_value)) {
                forward a,b,c = getValue(_value);
                bar();
            }
        }
    }

  Iterators now need to implement a single function `nextValue`. The value
  returned by `nextValue` must implement the functions `hasValue?`, which
  returns true if the iterator successfully yielded a value or false if the
  iterator is exhausted, and `getValue`, which returns the yielded value(s)
  by reference or by value. The library implements `hasValue?` and `getValue`
  for Pointer[T] and Maybe[T], so that those types may be used respectively in
  by-reference and by-value iterators.

Library changes:
----------------
* Record types are no longer provided with a static index (x.0) operator
  by default. fieldRefByIndex(x, static 0) may be used if by-index field
  access is needed. Thanks to Jeremy Clifford.

* The 'bitcast' function has been replaced by the new 'bitcast' primitive.
  The order of arguments of 'bitcast' has been reversed to be more in line
  with other cast functions; the target type is now the first argument.

    // 0.1
    var x = bitcast(y, Int);

    // 0.2
    var x = bitcast(Int, y);

* The polymorphic function container type Lambda[[..In],[..Out]] has been
  renamed Function[[..In],[..Out]].

* CodePointer, CCodePointer, and Function constructors can now deduce their
  input and output types when given a monomorphic function or lambda (that is,
  a function with a single overload and fully specified input types).

    // 0.1
    foo(x:Int) = Float(x);

    bar() {
        var cp = CodePointer[[Int],[Float]](foo);
        var ccp = CCodePointer[[Int],[Float]](foo);
        var l1 = Lambda[[Int],[Float]](foo);
        var l2 = Lambda[[Int, Int], [Int]]((x:Int, y:Int) -> x + y);
    }

    // 0.2
    foo(x:Int) = Float(x);

    bar() {
        var cp = CodePointer(foo);
        var ccp = CCodePointer(foo);
        var l1 = Function(foo);
        var l2 = Function((x:Int, y:Int) -> x + y);
    }

* External code pointers can now be constructed from Clay functions for all
  supported calling conventions, not just CCodePointer.

    // 0.2
    foo(x:Int) = Float(x);
    bar() = StdCallCodePointer(foo);

* The StringConstant type has been replaced a new StringLiteralRef type.
  StringLiteralRef values can be constructed from string literals.

    // 0.1
    "foo"

    // 0.2
    StringLiteralRef("foo")

* A new '++' operator is defined for sequence concatenation.  Sequences no
  longer overload the '+' operator for sequence concatenation.

    // 0.1
    foo() {
        println("hello " + "world");
    }

    // 0.2
    foo() {
        println("hello " ++ "world");
    }

  Thanks to Jeremy Clifford.

* A new '\' operator is defined for truncating division. Integers no longer
  overload the '/' operator for integer division.

    // 0.1
    foo() {
        return 3./2., 3/2; // 1.5, 1
    }

    // 0.2
    foo() {
        return 3./2., 3\2; // 1.5, 1
    }

  Thanks to Jeremy Clifford.

* Comparison operators now chain as in Python.

    // 0.1
    foo() {
        println(x >= 0 and x < 4);
    }

    // 0.2
    foo() {
        println(0 <= x < 4);
    }

  Thanks to Jeremy Clifford.

* Bitwise operators are now defined. Prefix `~` performs bitwise-not;
  infix `&` bitwise-and; infix `|` bitwise-or; infix `~` bitwise-xor;
  infix `<<` left-shift; and infix `>>` right-shift.

    // 0.1
    foo(x, y) {
        println(bitnot(x));
        println(bitand(x, y));
        println(bitor(x, y));
        println(bitxor(x, y));
        println(bitshl(x, y));
        println(bitshr(x, y));
    }

    // 0.2
    foo(x, y) {
        println(~x);
        println(x & y);
        println(x | y);
        println(x ~ y);
        println(x << y);
        println(x >> y);
    }

  Thanks to Jeremy Clifford.

Compiler frontend changes:
--------------------------
* LLVM and Clang 3.1 are now required.
* -O2 is now the default optimization level.

==========
0.0 -> 0.1
==========

Tool changes:
-------------
* A "clay-fix" program is provided to update code written for Clay 0.0 to
  compile in 0.1. It is fairly simple at this point, but most converted code
  should just work. Changes that can't be fixed are noted in this
  changelog.
* "clay-bindgen" has been rewritten in Clay, using the libclang C library.

Language changes:
-----------------
* Keywords that do similar things have been combined:
    callbyname ==> alias
    lvalue     ==> ref

* An ellipsis now only has two dots.
    ...        ==> ..

* The 'procedure' keyword has been changed to 'define'.
    procedure  ==> define

* Return type syntax has been changed.
    // 0.0
    foo(x:Int, y:Int) Int = x + y; // anonymous returns
    foo(x:Int, y:Int) z:Int        // named returns
    {
        z <-- x + y;
    }

    // 0.1
    foo(x:Int, y:Int) : Int = x + y; // anonymous returns
    foo(x:Int, y:Int) --> z:Int      // named returns
    {
        z <-- x + y;
    }

    foo() : { // you can now declare no return values
        println("Hello world");
    }

* The 'new' keyword has been removed. A 'new()' function is provided in the
  library that does the exact same thing.

* Hex float syntax (-0x1.234ABCp2) is now supported.

* enum and variant syntax has been changed to be more congruent with record
  syntax:
    // define enum type Foo with values ZIM, ZANG, ZUNG
    enum Foo (ZIM, ZANG, ZUNG);

    // define variant type Foo over Zim, Zang, Zung:
    variant Foo (Zim, Zang, Zung);

    // add Zippity,Doo,Dah to variant Foo
    instance Foo (Zippity, Doo, Dah);

* Scope guard statements are now provided. 'finally foo();' performs 'foo();'
  on scope exit for any reason. 'onerror foo();' performs 'foo();' if the
  scope is exited by a thrown exception, without catching the exception.
    // 0.0
    try {
      foo();
    } catch(ex) {
      bar();
      throw ex;
    }
    bar();

    // 0.1
    finally bar();
    foo();

    // 0.0
    try {
      foo();
    } catch(ex) {
      bar();
      throw ex();
    }

    // 0.1
    onerror bar();
    foo();

* Capture-by-reference lambdas now only support the '() -> {}' syntax.
    // 0.0
    (a,b) ref=> a+b+c

    // 0.1
    (a,b) -> a+b+c

* Universal pattern overloads have been unrestricted. '[F|Foo?(F)] F() {}'
  will now overload all symbols matching 'Foo?(F)' instead of only type
  symbols. Universe overloads also now have lower precedence than specific
  overloads. This change may break code even after it has been fixed.

* Function arguments are now passed by noalias nocapture reference. Mutated
  arguments should not alias, and taking pointers to arguments that outlive
  the function scope are not allowed. (It's currently unchecked by the
  compiler, though.) If you need to pass potentially aliasing mutable
  references or capture argument references, use Pointer[T] arguments.
  Pointers remain unrestricted. Return-by-reference functions also may
  still return aliases into their input arguments.

* Switch syntax has been changed.
    // 0.0
    switch (input) {
    case A:
        a();
        break;
    case B:
        b1();
        b2();
        break;
    case C:
    case D:
        cd();
        break;

    default:
        z();
        break;
    }

    // 0.1
    switch (input)
    case (A)
        a();
    case (B) {
        b1();
        b2();
    }
    case (C, D) {
        cd();
    }
    else {
        z();
    }

* A top-level module name declaration may be included in source files,
  immediately after any 'import' definitions.
    import foo.*;
    import bar.*;

    in module.name;
  Module declarations are not required, but if specified the declared name
  must match the name used to import the module. The module name can be
  followed by an attribute expression list in parens:
    in module.name (Int64, Float32);

    var x = 1;   // x will be an Int64
    var y = 1.0; // x will be a Float32
  Specifying an integer type as a module attribute sets the default type for
  unsuffixed integer literals in the module source code. Likewise, specifying
  a float type sets the default type for unsuffixed floating-point literals.

* You may now import private members from modules with the following syntax:
    import foo.(private member);

* String literals can be delimited with Python-style triple quotes:
    "hello world"
    """hello world"""

* The \a, \b, and \v and octal escape sequences have been removed.

* Octal integer literals have been removed. Literals starting with 0 are now
  interpreted as decimal.

* A single multiple-value expression can now be bound or assigned to multiple
  variables without an explicit unpack operator.
    // 0.0
    var a, b = ...multiValues();

    // 0.1
    var a, b = multiValues();

* Tuple syntax has been changed to use square brackets. Parens are now used
  only for grouping.
    // 0.0
    ()
    (1,)
    (1, 2, 3)

    // 0.1
    []
    [1]
    [1, 2, 3]

  Arrays (formerly occupying []) can be constructed with the array() function.
    // 0.0
    [1, 2, 3] // array

    // 0.1
    array(1, 2, 3)

  The "...()" hack to parenthesize multiple values is no longer necessary.
    // 0.0
    (x, y) -> ...(x+1, y-1)

    // 0.1
    (x, y) -> (x+1, y-1)

  CodePointer (and CCodePointer, etc.) types now must always have their input
  and output type lists in tuples, even if there is one input or output:
    // 0.0
    CodePointer[(Int, Float), String]
    CodePointer[Int, (String, Char)]

    // 0.1
    CodePointer[[Int, Float], [String]]
    CodePointer[[Int], [String, Char]]

  clay-fix's logic for fixing CodePointer types is pretty rudimentary and may
  break code that tries to be fancy. It will add a tuple around any single
  expression in the input or output field that isn't already in parentheses.

* Interface restrictions for generic functions can now be declared:
    [T] define foo(x:T, y:T) : T;

    bar() {
        var a = foo(1, 3); // ok
        //var b = foo(1l, 3i); // type error, types of parameters must match
    }
  The implementation is currently lazy and stupid; it only checks call sites
  against the interface instead of verifying overloads at definition time.
  This will be changed in the future.

* C99-compatible complex numbers are now supported with the Complex32,
  Complex64, and Complex80 types. Suffixing a floating-point literal with
  'j' creates an imaginary literal.  The 'math' module provides
  type-generic overloads for the standard C99 math library functions:
    import math.(sqrt);
    ...
    var x = sqrt(4.0f); // 2.0f
    var y = sqrt(4.0); // 2.0 
    var z = sqrt(-4.0+0.0j); // 2.0j
    var z = sqrt(-4.0f+0.0fj); // 2.0fj
  Thanks to Jeremy Clifford.

* The suffixes for literal integers and floats have been changed.
    i8   ==> ss ("short short")
    i16  ==> s  ("short")
    i32  ==> i  ("int")
    i64  ==> l  ("long")
    i128 ==> ll ("long long")

    u8   ==> uss
    u16  ==> us
    u32  ==> u
    u64  ==> ul
    u128 ==> ull

    f32 ==> f
    f64 ==> ff
    f80 ==> l or (to coerce an integer-looking literal) fl

* A new eval form supports evaluation of static strings as code. eval can be
  used as a statement or expression.
    eval #"""println("Hello world");""";
    var x = eval #"1 + 2";

* "ref x = y;" will now only bind references to lvalues. The old behavior of
  implicitly capturing rvalues or referencing lvalues is provided by
  'forward x = y;" now. clay-fix will convert all "ref" bindings to "forward"
  bindings. Statement forms that implicitly created "ref" bindings, such as
  "for" and "..for" loops, now create "forward" bindings and continue to work
  as before.
    // 0.0
    var x = 1;
    ref rx = x;
    ref ry = 2;

    // 0.1
    var x = 1;
    ref rx = x;
    //ref ry = 2; // now an error
    forward ry = 2;

* Higher-order functions can be called with the block arguments outside the
  call parens. In a statement form, the semicolon is not required with a
  block:
    // 0.0
    maybe(mx, x -> { useX(x); });

    // 0.1
    maybe(mx): x -> {
        useX(x);
    }

  Multiple blocks can be passed in this manner separated by '::':
    // 0.0
    maybe(mx, x -> { useX(x); }, () -> { useNothing(); });

    // 0.1
    maybe(mx): x -> {
        useX(x);
    } :: () -> {
        useNothing();
    }

Library changes:
----------------
* The bitwise operation functions have been given shorter names:
    shiftLeft    ==> bitshl
    shiftRight   ==> bitshr
    rotateLeft   ==> bitrol
    rotateRight  ==> bitror
    bitwiseAnd   ==> bitand
    bitwiseOr    ==> bitor
    bitwiseXor   ==> bitxor
    bitwiseNot   ==> bitnot
    bitwiseAndc  ==> bitandc
    bitwiseBlend ==> bitblend
    bitwiseCast  ==> bitcast

* 'allocateShared' and 'allocateUnique' have been renamed.
    allocateShared ==> newShared or new
    allocateUnique ==> newUnique

    // 0.0
    foo = new Foo(1);

    // 0.1
    foo = new(Foo(1));

* The INT_MIN, INT_MAX etc. constants have been replaced with Least(T) and
  Greatest(T) functions.
    INT8_MIN    ==> Least(Int8)
    INT8_MAX    ==> Greatest(Int8)
    INT16_MIN   ==> Least(Int16)
    INT16_MAX   ==> Greatest(Int16)
    etc.
  LeastPositive(T), LeastPositiveNormalized(T), and GreatestPositiveFinite(T)
  are also provided for floating-point types.

* 'printString' has been renamed.
    printString ==> str

* A static octal(#"777") function has been added to the numbers module.
    // 0.0
    0177
    0177u8

    // 0.1
    octal(#"177")
    octal(UInt8, #"177")

* The space? function from the characters module no longer considers ASCII 0x0B
  (formerly known as '\v') a space character.

* The format of the output from the printRepr function has been changed to give
  more accurate parseable representations of Clay objects.

* printTo() now prints identifiers as their string contents without a
  leading "#".
  printRepr*() still prints identifiers with the leading "#".

* printReprValuesTo no longer puts parens around its output.
  printReprArgumentsTo() gives the old behavior.
    printReprValuesTo ==> printReprArgumentsTo

* A repr() function has been added to the printer.formatter module, which
  prints its argument(s) using printRepr() within a print* or str() call.
    println("x = ", 128uss, " ", 128us); // output: x = 128 128
    println("x = ", repr(128uss, " ", 128us)); // output: x = 128uss, " ", 128us

* The 'arrayLiteral' function has been renamed 'array'.
    arrayLiteral ==> array

* A new 'math' module provides type-generic floating-point and complex math
  functions implemented in Clay. (Standard C99 math is still available from the
  libc module.) Thanks to Jeremy Clifford.

* Assertions can be disabled with the '-Dclay.DisableAssertions' flag.
  assert[] can also be parameterized with one or more static string tags,
  to be selectively disabled with '-Dclay.DisableAssertions.<tag>'.

    assert(false); // disable with -Dclay.DisableAssertions
    assert[#foo](false); // disable with -Dclay.DisableAssertions
                         // or -Dclay.DisableAssertions.foo
    assert[#foo,#bar](false); // disable with -Dclay.DisableAssertions
                              // or -Dclay.DisableAssertions.foo
                              // or -Dclay.DisableAssertions.bar

* In-memory containers now have bounds check assertions on operations such
  as indexing, front, and back. These assertions are tagged #boundsChecks
  and can be disabled with '-Dclay.DisableAssertions.boundsChecks'.

* The standard integer math operators now have overflow and division-by-zero
  checking. These checks can be disabled with
  '-Dclay.DisableAssertions.overflowChecks' (or '-Dclay.DisableAssertions').
  This flag affects addition, subtraction, multiplication, division, remainder,
  left shift, negation and conversion for all standard integer types.

* New functions are provided that perform integer math with defined two's-
  complement wrap-around behavior. These functions should be used when
  overflow is intended.
    wrapAdd
    wrapSubtract
    wrapMultiply
    wrapDivide
    wrapRemainder
    wrapBitshl
    wrapMinus
    wrapCast

* Primitive type default constructors (such as Int(), Char(), etc.) now zero-
  initialize instead of being no-ops. Use 'uninitializedUnsafe(T)' to get an
  uninitialized object-sized hunk of memory as before.

* The variant 'match' function has been changed. Instead of taking pairs of
  types followed by lambdas, it now takes just a set of lambdas, and calls
  the first one whose input types match the value inside the variant.
    // 0.0
    variant Shape = Circle | Square;

    match(shape,
        Circle, c => { ... },
        Square, s => { ... },
    );

    // 0.1
    variant Shape (Circle, Square);

    match(shape,
        (c:Circle) => { ... },
        (s:Square) => { ... },
    );

    // 0.1, using block syntax
    match(shape): (c:Circle) => {
        ...
    } :: (s:Square) => {
        ...
    }

  clay-fix conservatively converts calls to "match" to "matchByType", which
  retains the previous interface.

Compiler frontend changes:
--------------------------
* The compiler now requires LLVM 3.0.
* -unoptimized has been replaced with -O0 -O1 -O2 -O3 flags.
* '-asm' and '-llvm' have been renamed to '-S' and '-emit-llvm' for consistency
  with Clang and GCC. '-emit-llvm' will now also generate LLVM bitcode by
  default; use '-emit-llvm -S' to emit LLVM IR.
* The compiler now supports '-Wl,...' syntax for sending options to the linker.
* The redundant '-dll' option has been removed; use '-shared'.
* Externals are now only built by default for the main module (the source file
  provided on the commandline) when building with the '-c' or '-S' flags. Externals
  imported from other modules will still be compiled in the current compilation
  unit by default for executable and shared library output types, but not for
  object or assembly output. '-import-externals' and '-no-import-externals'
  flags are provided to control this behavior independent of the output
  type.
* External entry points for the main module are also now always compiled;
  '-shared' now only affects the type of file output by the compiler.
* The default output filename for executables and dynamic libraries is now the
  basename of the input file instead of 'a.out'. For instance, 'clay hello.clay'
  will output an executable named 'hello' (or 'hello.exe' if compiling for a
  Windows target).
* FreeBSD is now supported. Thanks to Daniel Kolesa.
* A new '-D' flag sets compiler flags, which may be queried by the 'Flag?' or
  'Flag' primitives.
    $ cat foo.clay
    main() { println(Flag?(#"FOO")); println(Flag(#"BAR")); }
    $ clay -DFOO -DBAR=bar -run foo.clay
    true
    bar
    $ clay -DBAR -run foo.clay
    false

    $
* Clay will now generate debug information on platforms for which LLVM supports
  debug information when given the '-g' flag.