ChangeLog.txt

==========
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.
    // 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.