Sugar

=====

Overview

========

Sugar is a source-to-source compiler that targets JavaScript. It is designed

with the following principles in mind:

- indentation-based syntax

- remove non-essential syntax (`.`, `;`, etc)

- offer syntax sugar for complex operations

- focus on architecture/program structure

- minimize personal differences in style between programmers

Basic example

-------------

```

console log "Hello, World!"

```

Class example

-------------

```

@class Animal

@property name

@constructor name

self name = name

@end

@method getName

return name

@end

@end

@class Dog: Animal

@property name = "dog"

@end

```

Module example

-------------

```

@module hello

@version 0.0.0

# Shared variables are module-level variables

@shared MESSAGE = "Hello, World!"

# You can define functions/classes here

@function say message=MESSAGE

console log (message)

@end

# This is the initialization function

say ()

```

Data types

==========

Variables

=========

Allocations

-----------

```

var a=0, b=0, c=0

```

```

# a=0, b=1, b=2

var a, b, c = [0, 1, 2]

```

```

# a=0, b=1, c=[2]

var a, b | c = [0, 1, ,2]

```

Assignment

----------

Conditional::

Assigns a default value to the lvalue if it is not defined

```

# <expression> <slot> ?= <expression>

user name ?= "anonymous"

``

Operations

==========

Conditionals

============

Expressions::

The following expression can be assigned anywhere

```

(if <predicate> -> <expression> | <predicate> -> <expression> | <expression>)

```

One-liners::

```

if <predicate> -> <statement>

elif <predicate> -> <statement>

else <expression>

```

Full-blocks::

```

if <predicate>

<statement>

...

elif <predicate>

<statement>

...

else

<statement>

...

end

```

Iterations

==========

For loops::

```

# for <variable> in <expression>

for i in 0..10

<statement>

...

end

```

For loops one-liner::

Iterations have a compact format

```

0..10 :: {<statement>;...}

```

Mapping one-liner::

Iterations can also produce a value, which can then be used

as an expression.

```

console log (0..10 ::= {<statement>;...})

```

Filter one-liner::

```

0..10 ::? {_|_ > 5}

```

Filter+map one-liner::

```

0..10 ::? {<statement>;...} ::= {<statement>;...}

```

Invocation

==========

Closures

========

No arguments::

```{<statement>...}```

With arguments::

```

{arg,...|

<statement>

...

}

```

Implicit arguments:

Any closure/function can have implicit arguments. They are `_`, `_1`, ... `_N`,

where `_` == `_0` and `N` corresponds to the index of the argument.

```

{_ + _1 + _2 + _3}

```

Functions

=========

```

@function f a, b=1, c=2, ...rest

<statement>

...

@end

```

When annotation::

Functions can be _guarded_ against execution in case a condition is not

met using the `@when` annotation.

```

@function f a

@when a > 10

return True

@end

```

Pre/post decoration::

Design-by-contract annotations `@pre` and `@post` allow to express pre

and post conditions that will be asserted at function start and before

termination.

```

@function f i

@pre i > 0

@post i > 10

i += 10

return i

@end

```

As annotation::

It is possible to _tag_ a function as belonging to a specific group using

the `@as` annotation. This has no effect on the code but is used as

meta-information.

```

@function f i

@as helper

return i + 1

@end

```

Classes

=======

Modules

======

History

=======

New features in 2016-04

-----------------------

Multiple allocation::

`var a=0, b=1`

Decomposition allocation::

```

var a, b = [0, 1] # a=0, b=1

var a, b | c = [0, 1, 3, 4] # a=0, b=1, c=[3,4]

```

Implicit returns in closures::

The last operation's value will be implicitely returned in closures

```

var a = {10 + 20}() # Is equivalent to {return 10 + 20}

```

Implicit arguments in functions::

If `_`, `_1`, ..., `_N` is referenced but not resolves, it will automatically

resolve to the nth argument of the current closure/function.

```

{ _ + _1 + _2} # Equivalent to {_,_1,_2|_ + _1 + -2}

```

Map/filter syntax::

```

var a = 0..10 ::= {_ + 1} # Produces [1,2,3,4,5,6,7,8,9,10]

var b = 0..10 ::? {_ > 5} # Produces [6,7,8,9]

var b = 0..10 ::? {_ > 5} = {_ * 10} # Produces [60,70,80,90]

```

New `__scope__` and `__name__` automatic variables::

```

@module m

@function f

console log (__name__) # prints `f`

console log (__scope__) # prints `m.f`

@end

```

`assert` improvement::

Failing assertions now show both the scope and the original predicate,

```

@module m

@function f

# prints "m.f: 10 * 10 < 50 failed"

assert (10 * 10 < 50, "failed!")#

@end

```

Native `for` loops::

For loops and iterations now use the native JavaScript `for` iteration,

closing over variables to prevent hoisting. As a result, iterations

don't use `extend.iterate` anymore.

# EOF