doc: typo and small fixes in nitreference

[nit.git] / doc / nitreference / nitreference-main.tex

% This file is part of Nit ( http://www.nitlanguage.org ).
%
% Copyright 2011 Jean Privat <jean@pryen.org>
%
% Licensed under the Apache License, Version 2.0 (the "License");
% you may not use this file except in compliance with the License.
% You may obtain a copy of the License at
%
%     http://www.apache.org/licenses/LICENSE-2.0
%
% Unless required by applicable law or agreed to in writing, software
% distributed under the License is distributed on an "AS IS" BASIS,
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
% See the License for the specific language governing permissions and
% limitations under the License.
\noindent\textbf{A Concise Reference of the Nit Language}

This document attempts to be as short as possible while covering all features of the language in deepth.
It is not a real manual to learn the language since concepts are covered when required.
Forward and backward references about concepts are written like this~\goto{redef} which means Section~\ref*{redef}.
An index\goto{index} also lists concepts and keywords for an improved navigation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Basic Syntax}\label{syntax}\label{end}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The syntax of Nit belongs to the Pascal tradition and is inspired by various script languages (especially Ruby).
Its objective is readability.

Indentation is not meaningful in Nit; blocks usually starts by a specific keyword and finish with @end@.
Newlines are only meaningful at the end of declarations, at the end of statements, and after some specific keywords.
The philosophy is that the newline is ignored if something (a statement, a declaration, or whatever) obviously needs more input; while the newline terminates lines that seems completed.
See the complete Nit grammar for more details.

\begin{lst}
print 1 + 1 # a first complete statement that outputs "2"
print 2 + # the second statement is not yet finished
2 # the end of the second statement, outputs "4"
\end{lst}

Nit tries to achieve some uniformity in its usage of the common punctuation:
equal (@=@) is for assignment,
double equal (@==@) is for equality test\goto{Bool}, 
column (@:@) is for type declaration,
dot (@.@) is for polymorphism\goto{call},
comma (@,@) separates elements,
and quad (@::@) is for explicit designation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Identifiers}\label{identifier}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Identifiers of modules, variables, methods, attributes and labels must begin with a lowercase letter and can be followed by letters, digits, or underscores.
However, the usage of uppercase letters (and camelcase) is discouraged and the usage of underscore to separate words in identifiers is preferred: @some_identifier@.

Identifiers of classes and types must begin with a uppercase letter and can be followed by letters, digits, or underscores.
However, in classes, the usage of camelcase is preferred while formal types should be written all in uppercases: @SomeClass@ and @SOME_VIRTUAL_TYPE@.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Style}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

While Nit does not enforce any kind of source code formatting, the following is encouraged:
\begin{itemize}
\item indentation is done with the tabulation character and is displayed as 8 spaces;
\item lines are less than 80 characters long;
\item binary operators have spaces around them: @4 + 5@, @x = 5@;
\item columns (@:@) and commas (@,@) have a space after them but not before: @var x: X@, @[1, 2, 3]@;
\item parenthesis and brackets do not need spaces around them;
\item superfluous parenthesis should be avoided;
\item the @do@ of methods\goto{fun} and the single @do@\goto{do} is on its own line and not indented;
\item the other @do@ are not on a newline.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Comments and Documentation}\label{comment}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

As in many script languages, comments begin with a sharp (@#@) and run up to the end of the line.
Currently, there is no multiline-comments.

A block of comments that precede any definition of module, class, or property, is considered as its documentation and will be displayed as such by the autodoc.
At this point, documentation is displayed verbatim (no special formatting or meta-information).

\begin{lst}
# doc. of foo
module foo

# doc. of Bar
class Bar
        # doc. of baz
        fun baz ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Types, Literals and Operations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Object}\label{Object}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Nit is a full object language.
Each value is the instance of a class\goto{class}.
Even the basic types described in this section.

@Object@ is the root of the class hierarchy.
All other classes, including the basic ones, are a specialization of @Object@.
\goto{superclass}

Classes\goto{class}, methods\goto{fun} and operators\goto{operator} presented in this section are defined in the standard Nit library that is implicitly imported in every module\goto{module}.
Many other classes and methods are also defined in the standard library.
Please look at the specific standard library documentation for all details.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Int and Float}\label{Int}\label{Float}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@1@, @-1@ are @Int@ literals, and @1.0@, @-0.1@ are @Float@ literals.
Standard arithmetic operators are available with a common precedence rules: @*@, @/@, and @%@ (modulo) ; then @+@ and @-@. 
Some operators can be composed with the assignment (@=@). \goto{operator}
\begin{lst}
var i = 5
i += 2
print i # outputs 7
\end{lst}

Conversion from @Int@ to @Float@ and @Float@ to @Int@ must be done with the @to_f@ and @to_i@ methods.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{String}\label{String}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Literal strings are enclosed within quotes (@"@).
Common escaping sequences are available (@\n@, @\t@, etc.)
To insert a value inside a literal string, include the values inside brackets (@{}@).
@+@ is the concatenation operator but is less efficient than the bracket form.

\begin{lst}
var i = 5
print "i={i}; i+1={i+1}" # outputs "i=5; i+1=6"
\end{lst}

All objects have a @to_s@ method that converts the object to a String.
@print@ is a top-level method\goto{toplevel} that takes any number of arguments\goto{vararg} and prints to the standard output.
@print@ always add a newline, another top-level method, @printn@, does not add the newline.

\begin{lst}
var x: String
x = 5.to_s # -> the String "5"
print x, 6 # outputs "56"
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Bool}\label{Bool}\label{is}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@true@ and @false@ are the only two @Bool@ values.
Standard Boolean operators are available with the standard precedence rule: @not@; then @and@; then @or@.

Common comparison operators are available: @==@ and @!=@ on all objects; @<@, @>@, @<=@, @>=@ and @<=>@ on @Comparable@ objects (which include @Int@, @String@ and others). \goto{operator}

\begin{itemize}
\item @==@, @<@, @>@, @<=@, @>=@ and @<=>@ are standard Nit operators (it means they are redefinable)\goto{operator}.
\item @and@, @or@ and @not@ are not standard Nit operators: they are not redefinable, also they are lazy and have adaptive typing flow effects\goto{adaptive typing}.
\item @==@ is not for reference equality but for value equality (like @equals@ in Java).
There is a special reference equality operator, @is@, but it cannot be redefined and its usage is not recommended.
Note also that while @==@ is redefinable, it has a special adaptive typing flow effect when used with @null@\goto{null}.
\item @!=@ is not a standard Nit operator. In fact @x != y@ is syntactically equivalent to @not x == y@.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Array}\label{Array}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@Array@ is a generic class\goto{generic}, thus @Array[Int]@ denotes an array of integers and @Array[Array[Bool]]@ denotes an array of array of Booleans.
Literal arrays can be declared with the bracket notation (@[]@).
Empty arrays can also be instantiated with the @new@\goto{new} keyword and elements added with the @add@ method.
Elements can be retrieved or stored with the bracket operator\goto{operator}.

\begin{lst}
var a = [1, 2, 3, 4] # A literal array of integers
print a.join(":") # outputs "1:2:3:4"
var b = new Array[Int] # A new empty array of integers
b.add(10)
b.add_all(a)
b.add(20)
print b[0] # outputs "10"
print b.length # outputs "6"
b[1] = 30
print b.join(", ") # outputs "10, 30, 2, 3, 4, 20"
\end{lst}

Note that the type of literal arrays is deduced using the static type combination rule\goto{combination}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Range}\label{Range}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@Range@ is also a generic class but accepts only @Discrete@ types (@Int@ is discrete).
There are two kinds of literal ranges, the open one @[1..5[@ that excludes the last element, and the closed one @[1..5]@ that includes it.

\begin{lst}
print([1..5[.join(":")) # outputs "1:2:3:4"
print([1..5].join(":")) # outputs "1:2:3:4:5"
\end{lst}

Ranges are mainly used in @for@ loops\goto{for}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{HashMap}\label{HashMap}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@HashMap@ is a generic class that associates keys with values.
There is no literal hashmap, therefore the @new@\goto{new} keyword is used to create an empty @HashMap@ and the bracket operators\goto{operator} are used to store and retrieve values.

\begin{lst}
var h = new HashMap[String, Int] 
# h associates strings to integers
h["six"] = 6
print h["six"] + 1 # outputs "7"
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Control Structures}\label{control}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Traditional procedural control structures exist in Nit.
They also often exist in two versions: a one-liner and a block version.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Control Flow}\label{control flow}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Control structures dictate the control flow of the program.
Nit heavily refers to the control flow in its specification:
\begin{itemize}
\item No unreachable statement;
\item No usage of undefined variables\goto{var};
\item No function without a @return@ with a value\goto{fun};
\item Adaptive typing\goto{adaptive typing}.
\end{itemize}

Some structures alter the control flow but are not described in this section: @and@, @or@, @not@\goto{Bool}, @or else@\goto{or else} and @return@\goto{return}.

Note that the control flow is determined only from the position, the order and the nesting of the control structures.
The real value of the expressions used has no effect on the control flow analyses.
\begin{multicols}{2}
\begin{lst}
if true then
        return
else
        return
end
print 1
# Compile error: 
# unreachable statement
\end{lst}
\columnbreak
\begin{lst}
if true then
        return
end
print 1
# OK, but never executed
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{if}\label{if}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{multicols}{2}
\begin{lst}
if exp then stm
if exp then stm else stm
if exp then
        stms
end
\end{lst}
\columnbreak
\begin{lst}
if exp then
        stms
else if exp then
        stms
else
        stms
end
\end{lst}
\end{multicols}
Note that the following example is invalid since the fist line is syntactically complete thus the newline terminate the whole @if@ structure\goto{syntax}; then an error is signaled since a statement cannot begin with @else@.
\begin{lst}
if exp then stm # OK: complete 'if' structure
else stm # Syntax error: unexpected 'else'
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{while}\label{while}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lst}
while exp do stm
while exp do
        stms
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{for}\label{for}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@for@ declares an automatic variable\goto{var} used to iterates on @Collection@ (@Array@ and @Range@ are both @Collection@).

\begin{lst}
for x in [1..5] do print x # outputs 1 2 3 4 5
for x in [1, 4, 6] do
        print x # outputs 1 4 6
end
\end{lst}

In fact, @for@ is syntactic sugar for a closure\goto{closure}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{loop}\label{loop}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Infinite loops are mainly used with breaks.
They are useful to implement \textit{until} loops or to simulate the \textit{exit when} control of Ada.

\begin{lst}
loop
        stms
        if exp then break
        stms
end
\end{lst}

Note that @loop@ is different from @while true@ because the control flow does not consider the values of expression\goto{control flow}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{do}\label{do}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Single @do@ are used to create scope for variables or to be attached with labeled breaks.

\begin{lst}
do
        var x = 5
        print x
end
# x is not defined here
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{break, continue and label}\label{break}\label{continue}\label{label}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Unlabeled @break@ exits the current @for@, @while@, @loop@, or closure\goto{closure}.
Unlabeled @continue@ skips the current @for@, @while@, @loop@, or closure.

@label@ can be used with @break@ or @continue@ to act on a specific control structure (not necessary the current one). 
The corresponding @label@ must be defined after the @end@ keyword of the designated control structure.

\begin{lst}
for i in [0..width[ do
        for j in [0..height[ do
                if foo(i, j) then break label outer_loop
                # The 'break' breaks the 'for i' loop
        end
end label outer_loop
\end{lst}

@label@ can also be used with @break@ and single @do@ structures.

\begin{lst}
do
        stmts
        if expr then break label block
        stmts
end label block
\end{lst}

In closures, @break@ and @continue@ can return values\goto{closure return}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{abort}\label{abort}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@abort@ stops the program with a fatal error and prints a stack trace.
Since there is currently no exception nor run-time-errors, abort is somewhat used to simulate them.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{assert}\label{assert}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@assert@ verifies that a given Boolean expression is true, or else it aborts.
An optional label can be precised, it will be displayed on the error message.
An optional @else@ can also be added and will be executed before the abort.
\begin{lst}
assert bla: whatever else
        # "bla" is the label
        # "whatever" is the expression to verify
        print "Fatal error in module blablabla."
        print "Please contact the customer service."
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Local Variables and Static Typing}\label{var}\label{static type}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@var@ declares local variables.
In fact there is no global variable in Nit, so in this document \textit{variable} always refers to a local variable.
A variable is visible up to the end of the current control structure.
Two variables with the same name cannot coexist: no nesting nor masking.

Variables are bound to values.
A variable cannot be used unless it has a value in all control flow paths (\`a la Java).

\begin{lst}
var x
var y
if whatever then
        x = 5
        y = 6
else
        x = 7
end
print x # OK
print y # Compile error: y is possibly not initialized
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Adaptive Typing}\label{adaptive typing}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Nit features adaptive typing, which means that the static type of a variable can change according to:
the assignments of variables,
the control flow\goto{control flow},
and some special operators (@and@, @or@\goto{Bool}, @or else@\goto{or else}, @==@, @!=@\goto{null}, and @isa@\goto{isa}).

\begin{multicols}{2}
\begin{lst}
var x # a variable
x = 5
# static type is Int
print x + 1 # outputs 6
x = [6, 7]
# static type is Array[Int]
print x[0] # outputs "6"
\end{lst}
\columnbreak
\begin{lst}
var x
if whatever then
        x = 5
else
        x = 6
end
# Static type is Int
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variable Upper Bound}\label{upper bound}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

An optional type information can be added to a variable declaration.
This type is used as an upper bound of the type of the variable.
When a initial value is given in a variable declaration without a specific type information, the static type of the initial value is used as an upper bound.
If no type and no initial value are given, the upper bound is set to @nullable Object@\goto{null}.

\begin{lst}
var x: Int # Upper bound is Int
x = "Hello" # Compile error: expected Int
var y: Object # Upper bound is Object
y = 5 # OK since Int specializes Object
var z = 5 # Upper bound is Int
z = "Hello" # Compile error: expected Int
var t: Object = 5 # Upper bound is Object
t = "Hello" # OK
\end{lst}

The adaptive typing flow is straightforward, therefore loops (@for@\goto{for}, @while@\goto{for}, @loop@\goto{for}) and closures\goto{closure} have a special requirement: on entry, the upper bound is set to the current static type; on exit, the upper bound is reset to its previous value.

\begin{lst}
var x: Object = ...
# static type is Object, upper bound is Object
x = 5
# static type is Int, bound remains Object
while x > 0 do
        # static type remains Int, bound sets to Int
        x -= 1 # OK
        x = "Hello" # Compile error: expected Int
end
# static type is Int, bound reset to Object
x = "Hello" # OK
\end{lst}

\future{A possible future version of Nit will use a fixed point analysis, thus remove the need of resetting the upper bound.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Type Checks}\label{isa}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@isa@ tests if an object is an instance of a given type.
If the expression used in an @isa@ is a variable, then its static type is automatically adapted, therefore avoiding the need of a specific cast\goto{as}.

\begin{lst}
var x: Object = whatever
if x isa Int then
        # static type of x is Int
        print x * 10 # OK
end
\end{lst}

Remember that adaptive typing follows the control flow\goto{control flow}, including the Boolean operators\goto{Bool}.

\begin{lst}
var a: Array[Object] = ...
for i in a do
        # the static type of i is Object 
        if not i isa Int then continue
        # now the static type of i is Int
        print i * 10 # OK
end
\end{lst}

An interesting example:
\begin{lst}
var max = 0
for i in whatever do
        if i isa Int and i > max then max = i
        # the > is valid since, in the right part
        # of the "and", the static type of i is Int
end
\end{lst}

Note that type adaptation occurs only in an @isa@ if the target type is more specific that the current type.
\begin{lst}
var a: Collection[Int] = ...
if a isa Comparable then
        # the static type is still Collection[Int]
        # even if the dynamic type of a is a subclass
        # of both Collection[Int] and Comparable
        ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Nullable Types}\label{null}\label{nullable}\label{or else}\label{not null}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@null@ is a literal value that is only accepted by some specific static types.
However, thanks to adaptive typing, the static type management can be mainly automatic.

@nullable@ annotates types that can accept @null@ or an expression of a compatible nullable static type.

\begin{lst}
var x: nullable Int
var y: Int
x = 1 # OK
y = 1 # OK
x = null # OK
y = null # Compile error
x = y # OK
y = x # Compile error
\end{lst}

Adaptive typing works well with nullable types.

\begin{lst}
var x
if whatever then
        x = 5
else
        x = null
end
# The static type of x is nullable Int
\end{lst}

Moreover, like the @isa@ keyword, the @==@ and @!=@ operators can adapt the static type of a variable when compared to @null@.

\begin{lst}
var x: nullable Int = whatever
if x != null then
        # The static type of x is Int (without nullable)
        print x + 6
end
# The static type of x is nullable Int
\end{lst}

And another example:
\begin{lst}
var x: nullable Int = whatever
loop
        if x == null then continue
        # The static type of x is Int
end
\end{lst}

%FIXME: Pas clair il parrait
@or else@ can be used to compose a nullable expression with any other expression.
The value of @x or else y@ is @x@ if @x@ is not @null@ and is @y@ if @x@ is null.
The static type of @x or else y@ is the combination\goto{combination} of the type of @y@ and the not null version of the type of @x@.
\begin{lst}
var i: nullable Int = ...
var j = i or else 0
# the static type of j is Int (without nullable)
\end{lst}

Note that nullable types require a special management for attributes and constructors\goto{initialization}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Explicit Cast}\label{as}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@as@ casts an expression to a type.
The expression is either casted successfully or there is an @abort@\goto{abort}.

\begin{lst}
var x: Object = 5 # static type of x is Object
print x.as(Int) * 10 # outputs 50
print x.as(String) # aborts: cast failed
\end{lst}

Note that @as@ does not change the object nor does perform conversion.
\begin{lst}
var x: Object = 5 # static type of x is Object
print x.as(Int) + 10 # outputs "15"
print x.to_s + "10" # outputs "510"
\end{lst}


Because of type adaptation, @as@ is rarely used on variables.
@isa@ (sometime coupled with @assert@\goto{assert}) is preferred.
\begin{lst}
var x: Object = 5 # static type of x is Object
assert x isa Int
# static type of x is now Int
print x * 10 # outputs 50
\end{lst}

@as(not null)@ can be used to cast an expression typed by a nullable type to its non nullable version.
This form keeps the programmer from writing explicit static types.

\begin{lst}
var x: nullable Int = 5 # static type of x is nullable Int
print x.as(not null) * 10 # cast, outputs 50
print x.as(Int) * 10 # same cast, outputs 50
assert x != null # same cast, but type of x is now Int
print x * 10 # outputs 50
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Static Type Combination Rule}\label{combination}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Adaptive typing, literal arrays\goto{Array}, @or else@\goto{or else}, and valued @break@ in closure\goto{closure} need to determine a static type by combining other static types.
This is done by using the following rule:
\begin{itemize}
\item The final type is @nullable@ if at least one of the types is @nullable@.
\item The final type is the static type that is more general than all the other types.
\item If there is no such a type, and the thing typed is a variable, then the final type is the upper bound type of the variable; else there is a compilation error.
\end{itemize}
% FIXME: the 'thing' typed?!

\begin{lst}
var d: Discrete = ...
# Note: Int < Discrete < Object
var x
if whatever then x = 1 else x = d
# static type is Discrete
if whatever then x = 1 else x = "1"
# static type is nullable Object (upper bound)
var a1 = [1, d] # a1 is a Array[Discrete]
var a2 = [1, "1"] # Compile error:
                # incompatible types Int and String 
\end{lst}

\future{A possible future version of Nit will introduce union types, thus simplifying the rule of combination.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Modules}\label{module}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@module@ declares the name of a module.
While optional it is recommended to use it, at least for documentation purpose\goto{comment}.
The basename of the source file must match the name declared with @module@.
The extension of the source file must be @nit@.

A module is made of, in order:
\begin{itemize}
\item the module declaration;
\item module importations;
\item class definitions (and refinements) \goto{class};
\item top-level function definitions (and redefinitions) \goto{toplevel};
\item main instructions \goto{toplevel}.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Module Importation}\label{import}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@import@ declares dependencies between modules.
By default, a module publicly imports the module @standard@.
Dependencies must not produce cycles.
By importing a module, the importer module can see and use classes and properties defined in the imported module.

\begin{itemize}
\item @import@ indicates a public importation.
Importers of a given module will also import its publicly imported modules.
%Modules that import the current module will implicitly also import the other module.
An analogy is using @#include@ in a header file (@.h@) in C/C++.
\item @private import@ indicates a private importation.
Importers of a given module will not automatically import its privately imported modules.
An analogy is using @#include@ in a body file (@.c@) in C/C++.
%Modules that import the current module will not see the classes and properties imported.
%However, while the classes and properties imported are invisible, the information that the module import an other one is still public and required to compile and run the program.
\item @intrude import@ indicates an intrusive importation.
@intrude@ @import@ bypasses the @private@ visibility and gives to the importer module a full access on the imported module.
Such an import may only be considered when modules are strongly bounded and developed together.
The closest, but insufficient, analogy is something like including a body file in a body file in C/C++.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Visibility}\label{visibility}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

By default, all classes\goto{class}, methods\goto{fun}, constructors\goto{init} and virtual types\goto{type} are public which means freely usable by any importer module.
Once something is public it belongs to the API of the module and should not be changed.

@private@ indicates classes and methods that do not belong to the API.
They are still freely usable inside the module but are invisible in other modules (except those that use @intrude import@).

@protected@ indicates restricted methods and constructors.
Such methods belong to the API of the module but they can only be used with the @self@ receiver.
Basically, @protected@ methods are limited to the current class and its subclasses.
Note that inside the module (and in intrude importers), there is still no restriction.

Visibility of attributes is more specific and is detailed in its own section\goto{attribute visibility}.

\begin{multicols}{2}
\begin{lst}
module m1
class Foo
        fun pub do ...
        protected fun pro
        do ...
        private fun pri
        do ...
end
private class Bar
        fun pri2 do ...
end
var x: Foo = ...
var y: Bar = ...
# All OK, it is
# inside the module
x.foo
x.pro
x.pro
y.pri2
\end{lst}
\columnbreak
\begin{lst}
module m2
import m1
class Baz
        super Foo
        fun derp
        do
                self.pro # OK
        end
end
var x: Foo = ...
x.pub # OK
x.pro # Compile error:
      # pro is protected
x.pri # Compile error:
      # unknown method pro

var y: Bar
# Compile error:
# unknown class Bar
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Visibility Coherence}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

In order to guarantee the coherence in the visibility, the following rules apply:
\begin{itemize}
\item Classes and properties privately imported are considered private: they are not exported and do not belong to the API of the importer.
\item Properties defined in a private class are private.
\item A static type is private if it contains a private class or a private virtual type\goto{type}.
\item Signatures of public and protected properties cannot contain a private static type.
\item Bounds of public generic class\goto{generic} and public virtual types\goto{type} cannot contain a private static type.
\end{itemize}

% FIXME: What about specialization links between a public class and a privately imported public class

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Classes}\label{class}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@interface@, @abstract class@, @class@ and @enum@ are the four kinds of classes. All these classes can be in multiple inheritance, can define new methods and redefine inherited method (yes, even interfaces). Here are the differences:
\begin{itemize}
\item interfaces can only specialize other interfaces, cannot have attributes, cannot have constructors, cannot be instantiated.
\item abstract classes cannot specialize enums, can have attributes, must have constructors, cannot be instantiated.
\item concrete classes (i.e. @class@) cannot specialize enums, can have attributes, must have constructors, can be instantiated.
\item enums (e.g. @Int@ or @Bool@) can only specialize interfaces, cannot have attributes, cannot have constructors, have proper instances but they are not instantiated by the programmer---it means no @new Int@. Note that at this point there is no user-defined enums.
\end{itemize}

All kinds of classes must have a name, can have some superclasses and can have some definitions of properties.
Properties are methods\goto{fun}, attributes\goto{attribute}, constructors\goto{init} and virtual types\goto{type}.
All kinds of classes can also be generic\goto{generic}.
When we talk about ``classes'' in general, it means all these four kinds.
We say ``concrete classes'' to designate only the classes declared with the @class@ keyword alone.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Class Specialization}\label{superclass}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@super@ declares superclasses.
Classes inherit methods, attributes and virtual-types defined in their superclasses.
Currently, constructors are inherited in a specific manner\goto{init inheritance}.

@Object@ is the root of the class hierarchy.
It is an interface and all other kinds of classes are implicitly a subclass of @Object@.

There is no repeated inheritance nor private inheritance.
The specialization between classes is transitive, therefore @super@ declarations are superfluous (thus ignored).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Class Refinement}\label{refine}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@redef@ allows modules to refine imported classes (even basic ones).
Refining a class means:
\begin{itemize}
\item adding new properties: methods, attributes, constructors, virtual types;
\item redefining existing properties: methods and constructors;
\item adding new superclasses.
\end{itemize}

Note that the kind\goto{class} or the visibility\goto{visibility} of a class cannot be changed by a refinement.
Therefore, it is allowed to just write @redef class X@ whatever is the kind or the visibility of @X@.

In programs, the real instantiated classes are always the combination of all their refinements.
%This is quite powerful and permit a programing style only found in some dynamically typed languages or aspect-oriented languages.

\begin{lst}
redef class Int
        fun fib
        do
                if self < 2 then return self
                return (self-1).fib + (self-2).fib
        end
end
# Now all integers have the fib method
print 15.fib # outputs 610
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Methods}\label{fun}\label{self}\label{return}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@fun@ declares methods.
Methods must have a name, may have parameters, and may have a return type.
Parameters are typed; however, a single type can be used for multiple parameters.
\begin{lst}
fun foo(x, y: Int, s: String): Bool ...
\end{lst}

@do@ declares the body of methods.
Alike control structures\goto{control}, a one-liner version is available.
Moreover, a shorter version using the @=@ symbol is also available for functional methods.
Therefore, the three following methods are equivalent. 
\begin{lst}
fun next1(i: Int): Int
do
        return i + 1
end

fun next2(i: Int): Int do return i + 1

fun next3(i: Int): Int = i + 1
\end{lst}

Inside the method body, parameters are considered as variables\goto{var}.
They can be assigned and are subject to adaptive typing.

@self@, the current receiver, is a special parameter.
It is not assignable but is subject to adaptive typing.

@return@ exits the method and returns to the caller.
In a function, the return value must be provided with a return in all control flow paths\goto{control flow}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Method Call}\label{call}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Calling a method is usually done with the dotted notation @x.foo(y, z)@.
The dotted notation can be chained.

A method call with no argument does not need parentheses.
Moreover, even with arguments, the parentheses are not required in the principal method of a statement.
\begin{lst}
var a = [1]
a.add 5 # no () for add
print a.length # no () for length, no () for print
\end{lst}

However, this last facility requires that the first argument does not start with a parenthesis or a bracket.
\begin{lst}
foo (x).bar # will be interpreted as (foo(x)).bar
foo [x].bar # will be interpreted as (foo[x]).bar
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Method Redefinition}\label{redef}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@redef@ denotes methods that are redefined in subclasses\goto{superclass} or in class refinements\goto{refine}.
The number and the types of the parameters must be invariant.
Thus, there is no need to reprecise the types of the parameters, only names are mandatory.

The return type can be redefined to be a more precise type.
If same type is returned, there is no need to reprecise it.

The visibility, also, cannot be changed, thus there is also no need to reprecise it.

\begin{lst}
class Foo
        # implicitly an Object
        # therefore inherit '==' and 'to_s' 
        var i: Int
        redef to_s do return "Foo{self.i}"
        redef ==(f) do return f isa Foo and f.i == self.i
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Abstract Methods}\label{abstract}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@is abstract@ indicates methods defined without a body.
Subclasses and refinements can then redefine it (the @redef@ is still mandatory) with a proper body.

\begin{lst}
interface Foo
        fun derp(x: Int): Int is abstract
end
class Bar
        super Foo
        redef derp(x) do return x + 1
end
\end{lst}

Concrete classes may have abstract methods.
It is up to a refinement\goto{refine} to provide a body.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Call to Super}\label{super}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@super@ calls the ``previous'' definition of the method.
It is used in a redefinition of a method in a subclass or in a refinement,
It can be used with or without arguments; in the latter case, the original arguments are implicitly used.

The @super@ of Nit behave more like the @call-next-method@ of CLOS that the @super@ of Java or Smalltalk.
It permits the traversal of complex class hierarchies and refinement.
Basically, @super@ is polymorphic: the method called by @super@ is not only determined by the class of definition of the method but also by the dynamic type of @self@.

\begin{comment}
The principle it to produce a strict order of the redefinitions of a method (the linearization).
Each call to @super@ call the next method definition in the linearization.
From a technical point of view, the linearization algorithm used is based on C4.
It ensures that:
\begin{itemize}
\item A definition comes after its redefinition.
\item A redefinition in a refinement comes before a redefnition in a
\item The order of the declaration of the superclasses is used as the ultimate deabiguization.
\end{itemize}

%@super@ is really powerful and can deals with very complex multiple inheritance and multiple refinement thanks to some linearization algorithm.

\begin{lst}
class A
        fun derp: String do return "A"
end
class B
        super A
        redef fun derp do return "B" + super
end
class C
        super A
        redef fun derp do return "C" + super
end
class D
        super B
        super C
        redef fun derp do return "D" + super
        # Here the linearization order of the class D is DBCA
        # D before B because D specializes B
        # B before A because B specializes A 
        # D before C because D specializes C
        # C before A because C specializes A
        # B before C because in D 'super B' is before 'super C'  
end
var b = new B
print b.derp # outputs "BA"
var d = new D
print d.derp # outputs "DBCA"
\end{lst}
\end{comment}

% TODO: linearization.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Operators and Setters}\label{operator}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Operators and setters are methods that require a special syntax for their definition and their invocation.

\begin{itemize}
\item binary operators: @+@, @-@, @*@, @/@, @\%@, @==@, @<@, @>@, @<=@, @>=@, @<<@, @>>@ and @<=>@.
Their definitions require exactly one parameter and a return value.
Their invocation is done with @x + y@ where @x@ is the receiver, @+@ is the operator, and @y@ is the argument.
\item unary operator: @-@.
Its definition requires a return value but no parameter.
Its invocation is done with @-x@ where @x@ is the receiver.
\item bracket operator: @[]@.
Its definition requires one parameter or more and a return value.
Its invocation is done with @x[y, z]@ where @x@ is the receiver, @y@ the first argument and @z@ the second argument.
\item setters: @something=@ where @something@ can be any valid method identifier.
Their definitions require one parameter or more and no return value.
If there is only one parameter, the invocation is done with @x.something = y@ where @x@ is the receiver and y the argument.
If there is more that one parameter, the invocation is done with @x.something(y, z) = t@ where @x@ is the receiver, @y@ the first argument, @z@ the second argument and @t@ the last argument.
\item bracket setter: @[]=@.
Its definition requires two parameters or more and no return value.
Its invocation is done with @x[y, z] = t@ where @x@ is the receiver, @y@ the first argument, @z@ the second argument and @t@ the last argument.
\end{itemize}

\begin{lst}
class Foo
        fun +(a: Bar): Baz do ...
        fun -: Baz do ...
        fun [](a: Bar): Baz do ...
        fun derp(a: Bar): Baz do ...
        fun derp=(a: Bar, b: Baz) do ...
        fun []= (a: Bar, b: Baz) do ...
end
var a: Foo = ...
var b: Bar = ...
var c: Baz = ...
c = a + b
c = -b
c = a[b] # The bracket operator '[]'
c = a.derp(b) # A normal method 'derp'
a.derp(b) = c # A setter 'derp='
a[b] = c # The bracket setter '[]='
\end{lst}

@+=@ and @-=@ are combinations of the assignment (@=@) and a binary operator.
These feature are extended to setters where a single @+=@ is in fact three method calls: a function call, the operator call, then a setter call.
\begin{lst}
a += c # equiv. a = a + c
a[b] += c # equiv. a[b] = a[b] + c
a.foo += c # equiv. a.foo = a.foo + c
a.bar(b) += c # equiv. a.bar(b) = a.bar(b) + c
\end{lst} 

% FIXME: priority of operators?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variable Number of Arguments}\label{vararg}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

A method can accept a variable number of arguments using ellipsis (@...@).
The definition use @x: Foo...@ where @x@ is the name of the parameter and @Foo@ a type.
Inside the body, the static type of @x@ is @Array[Foo]@.
The caller can use 0, 1, or more arguments for the parameter @x@.
Only one ellipsis is allowed in a signature.

\begin{lst}
fun foo(x: Int, y: Int..., z: Int)
do
        print "{x};{y.join(",")};{z}"
end
foo(1, 2, 3, 4, 5) # outputs "1;2,3,4;5"
foo(1, 2) # outputs "1;;2"
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Top-level Methods and Main Body}\label{toplevel}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Some functions, like @print@, are usable everywhere simply without using a specific receiver.
Such methods are just defined outside any classes.
In fact, these methods are implicitly defined in the @Object@ interface, therefore inherited by all classes, therefore usable everywhere.
However, this principle may change in a future version.

In a module, the main body is a bunch of statements at the end of a file.
The main body of the main module is the program entry point.
In fact, the main method of a program is implicitly defined as the redefinition of the method @main@ of the @Sys@ class; and the start of the program is the implicit statement @(Sys.new).main@.
Note that because it is a redefinition, the main part can use @super@\goto{super} to call the ``previous'' main part in the imported modules.
If there is no main part in a module, it is inherited from imported modules.

Top-level methods coupled with the main body can be used to program in a pseudo-procedural way.
Therefore, the following programs are valid:
\begin{multicols}{2}
\begin{lst}
print "Hello World!"
\end{lst}
\columnbreak 
\begin{lst}
fun sum(i, j: Int): Int
do
        return i + j
end
print sum(4, 5)
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Intern and Extern Methods}\label{intern}\label{extern}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@intern@ and @extern@ indicate concrete methods whose body is not written in Nit.

The body of @intern@ methods is provided by the compiler itself for performance or bootstrap reasons.
For the same reasons, some intern methods, like @+@ in @Int@\goto{Int} are not redefinable.

The body of @extern@ methods is provided by libraries written in C; for instance, the system libraries required for input/output.
Extern methods are always redefinable.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Attributes}\label{attribute}\label{writable}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@var@, used inside concrete and abstract classes, declares attributes.
Attributes require a static type and can possibly have an initial value (it may be any kind of expression, even including @self@\goto{self})

%In Nit, attributes cannot be directly accessed.
%In fact by declaring an attribute, two methods are automatically generated.
%One is the getter, the other is the setter.

\begin{lst}
class Foo
        var i: Int = 5
        fun dec(x: Int): Int
        do
                var k = self.i
                if k > x then self.i = k - x else self.i = 0
        end
end
\end{lst}

Note that from an API point of view, there is no way to distinguish the read access of an attribute with a normal method neither to distinguish a write access of an attribute with a setter.
Therefore, the read access of an attribute is called a getter while the write access is called a setter.
\begin{lst}
var x = foo.bar # Is bar an attribute or a method?
foo.bar = y # Is bar an attribute or a setter?
# In fact, we do not need to know.
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Visibility of Attributes}\label{attribute visibility}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

By default, a getter is public and a setter is private.
The visibility of getters can be precised with the @private@ or @protected@ keywords.
The visibility of setters can be specified with an additional @writable@ keyword.

\begin{lst}
class Foo
        var pub_pri: X
        protected var pro_pri: X
        var pub_pub: X writable
        private var pri_pro: X protected writable
        var pub_pri2: X private writable # the default
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Redefinition of Attributes}\label{redef var}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Getters and setters of attributes behave like genuine methods that can be inherited and redefined.
Getters and setters can also redefine inherited methods.
@redef var@ declares that the getter is a redefinition while @redef writable@ declares that the setter is a redefinition.

\begin{lst}
interface Foo
        fun derp: Int is abstract
        fun derp=(o: Int) is abstract
end
class Bar
        super Foo
        redef var derp: Int redef writable
end
class Baz
        super Bar
        redef fun derp do ...
        redef fun derp=(o) do ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Constructors and Instantiation}\label{init}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@init@ declares constructors in concrete and in abstract classes.
The role of constructors is basically to initialize the attributes of the class.
Constructors can have: a visibility (by default it is public), a name (by default, constructors are anonymous) and parameters.
They cannot have a return value.

\begin{lst}
class Foo
        init(i:Int) do ...
        init herp do ...
        init derp(i, j: Int) do ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Class Instantiation}\label{new}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@new@ instantiates a concrete class using a specific constructor. 
\begin{lst}
var x = new Foo(4) # invoke init
var y = new Foo.herp # invoke herp
var z = new Foo.derp(1, 2) # invoke derp
\end{lst}
Note that syntactically, @new Bar@ means ``instantiate @Bar@ with the anonymous constructor'', and @new Bar.foo@ means ``instantiate @Bar@ with the constructor named @foo@'', but @(new Bar).foo@ means ``instantiate @Bar@ with the anonymous constructor then call the method @foo@ on the result''.

Constructors can also be called by other constructors in order to factorize or delegate parts of the construction process.
In other constructors, @init@ denotes the anonymous constructor.
\begin{lst}
class Foo
        init(i: Int) do self.derp(i.to_s)
        init herp do self.init(5)
        init derp(s: String) do ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Initialization of Attributes}\label{initialization}\label{isset}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The tricky part in constructors is the initialization of attributes since they cannot be initialized in an atomic way.
The various steps apply in the following order:
\begin{itemize}
\item Attributes typed by a nullable type are initialized with @null@\goto{null}; other attributes remain uninitialized.
\item Default values of all attributes (including inherited ones) are computed in the order of their definitions.
\item The constructor designated in the @new@ is executed.
\item During the constructor execution (including any methods or other constructors called), accessing an uninitialized attribute aborts the program.
\item After the execution of the constructor designated in the @new@, if some attributes remain uninitialized, the program aborts.
\end{itemize}

\begin{comment}
@isset@ can be used to avoid aborting during the construction.
It checks if an attribute is defined.
\begin{lst}
class Foo
        var x: Int
        fun safe_x: nullable Int
        do
                if isset self.x then
                        return self.x
                else
                        return null
                end
        end
        init
        do
                print safe_x or else 0 # outputs 0
                # "print x" would have aborted the program
                self.x = 5
                print safe_x or else 0 # outputs "5"
                print x # outputs "5". It is safe.
        end
end
var f = new Foo
\end{lst}
\end{comment}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Free and Inherited Constructors}\label{init inheritance}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

When there is no constructor defined in a concrete class or in an abstract class that specializes only interfaces (@Object@ is always a superclass), a free anonymous constructor is implicitly declared.
This free constructor gathers all attributes without a initial value and assign them in order.
If all attributes have an initial value (or if there is no attributes), the free constructor has no parameters.

\begin{lst}
class Foo
        var x: Int
        var y: String
        var z: Int = 0
        # a free init(x: Int, y: String) is implicit
end
var f = new Foo(5, "five") # OK
\end{lst}

When there is no constructors defined in a concrete class or in an abstract class, and this class has only one direct superclass that is a concrete class or an abstract class, and all attributes defined in this class have an initial value, then all constructors of the superclass are inherited.

\begin{lst}
class Bar
        super Foo
        var t: String = "Hello"
        # init(Int, String) is inherited
end
\end{lst}

If none of these two cases apply, then there is a compilation error.
The programmer usually has to define its own constructors for the class.

\begin{lst}
class Baz
        super Foo
        var u: Int
        # Compile error: a constructor must be defined
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Generic Classes and Virtual Types}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Generic Classes}\label{generic}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Generic classes are defined with formal generic parameters declared within brackets.
Formal generic parameters can then be used as a regular type inside the class.
Generic classes must always be qualified when used.

\begin{lst}
class Pair[E]
        var first: E
        var second: E
        fun is_same: Bool
        do
                return self.first == self.second
        end
end
var p1 = new Pair[Int](1, 2)
print p1.second * 10 # outputs "20"
print p1.is_same # outputs "false"
var p2 = new Pair[String]("hello", "world")
p2.first = "world"
print p2.is_same # outputs "true"
\end{lst}

Unlike many object-oriented languages, generic classes in Nit yield a kind of sub-typing.
For example, @Pair[Int]@ is a subtype of @Pair[Object]@.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Virtual Types}\label{type}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@type@ declares a virtual types in a class.
A bound type is mandatory.
Virtual types can then be used as regular types in the class and its subclasses.
Subclasses can also redefine it with a more specific bound type.
One can see a virtual type as an internal formal generic parameter or as a redefinable \textit{typedef}.

\begin{lst}
class Foo
        type E: Object
        var derp: E 
end
class Bar
        super Foo
        redef type E: Int
end
var b = new Bar(5)
print b.derp + 1 # outputs 6
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Closures}\label{closure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Closures are pieces of code that are passed to methods as additional arguments.
Closures are defined and used with the @!@ character.
The following example shows the use of the @sort@ method for arrays (defined in the Nit standard library).

\begin{lst}
var a = [4, 2, 9, 6]
a.sort !cmp(x, y) = x <=> y
print a.join(", ") # outputs "2, 4, 6, 9"
a.sort !cmp(x, y) = y <=> x
print a.join(", ") # outputs "9, 6, 4, 2"
\end{lst}

@!cmp@ indicates the closure parameter of the @sort@ method.
The documentation of the @sort@ method says that @!cmp@ is used to compare two elements.
Thus, @sort@ provides to @!cmp@ two elements and expects a Boolean result. %saying if the first element provided should be sorted before the second element provided.
%Therefore, when invoking @sort@, the programmer gets two automatic variables (one associated to each element) and is expected to return a Boolean.

Closures can also be used to perform work.
In the following example, @file_open@ is used to open a file for reading.
If the opening fails, the @!error@ closure is executed with the reason as argument (``file not found'' for instance).
If the opening is successful, @!work@ is executed and the automatic variable @f@ is associated with the opened file handler.
@file_open@ also ensures that the file is correctly closed when the @!work@ closure returns.

\begin{lst}
var fname = "input.txt"
file_open(fname) !work(f) do
        print f.read_line
!error(e) do
        print "Cannot open '{fname}': {e}"
end
\end{lst}

Note that a method can have multiple closures.
Syntactically, a closure is ended by the start of another closure or by the @end@ keyword that terminates the list of the closures.
In the one-liner version, there is no @end@ but only one closure can be used.

Closures can access visible variables.
In the following example, the @iterate@ procedure asks for an @!each@ closure that is executed on each element of a @Collection@.
In fact, the @for@ control structure is a call of the @iterate@ method.
The following two examples are thus strictly equivalent.

\begin{multicols}{2}
\begin{lst}
var sum = 0
var a = [4, 2, 9]
a.iterate !each(i) do
        sum += i
end
print sum # outputs "15"
\end{lst}
\columnbreak
\begin{lst}
var sum = 0
var a = [4, 2, 9]
for i in a do
        sum += i
end
print sum # outputs "15"
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Returning Values and Escaping}\label{closure return}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@break@ and @continue@ are extended to closures.

@continue@ exits the closure.
If the closure expects a return value, @continue@ can also be used to return the correct value.
As with method definition, the @do continue value@ syntax can be replaced by @= value@ as in the first @sort@ example.


@break@ exits completely the called method.
If the called method is a function, @break@ is also used to set the result returned by the function.
The types returned by @break@ can be different from the return type of the function.
The return type of the whole expression is the combination\goto{combination} of the return type of the function and the types of each @break@.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Closures in Method Declarations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Closure parameters are declared with their signature between the prototype and the @do@ of the method.
Closure invocations in the body of the method simply use the closure name (without the @!@) like a standard call.
More than one closure parameter can be declared.
Each has to be declared on a separate line.
%At the method invocations, the closure name is used to associate each closure definition with each closure parameter.
The order of the closure definitions does not matter.

\begin{multicols}{2}
\begin{lst}
fun twice
        !work
do
        work
        work
end
twice !work do print "One"
# outputs "One One"
\end{lst}


\begin{lst}
fun foo(i: String): String
        !f(j: String): String
do
        var k = f(i + "B")
        # k will be "ABC"
        return k + "D"
end
var x = foo("A") !f(y) =
                y + "C"
print x # outputs "ABCD"
\end{lst}
\columnbreak
\begin{lst}
fun bar(i: String)
        !b1(j: String): String
        !b2(k: String)
do
        b2(b1(i))
end

bar("A") !b1(y) do
        continue y + "B"
!b2(z) do
        print z
end
# outputs "AB"
\end{lst}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Default Closures}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

A default closure can be given along with the closure parameter declaration in a method.
If there is no default closure, then the corresponding closure argument is mandatory.
Otherwise, if there is a default closure, the corresponding closure argument is optional.


\begin{lst}
fun are_all_comparable(a: Collection[Int]): Bool
        !cmp(x, y: Int): Bool = x == y
do
        if a.is_empty then return true
        var e1 = a.first
        for e2 in a do if not cmp(e1, e2) then return false
        return true
end

var a = [2, 2, 6, 2]
print are_all_comparable(a) # outputs "false"
var x = are_all_comparable(a) !cmp(i, j) = i%2 == j%2
print x # outputs "true"
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Break Closures}\label{break closure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Some closures, called break closures, cannot be continued.
On the method definition, it means that the closure invocation does not return (like a @return@ or an @abort@).
On method invocations, it means that the closure definition must not continue.
Break closures are usually used to process error or exception handling.


\begin{lst}
fun open_file(fname: String)
        !work(f: File)
        break !error(e: String) do
                print "Cannot open {fname}: {e}."
                abort
        end
do
        # ...
end

open_file("config.ini") !error(e) do
        print "Cannot open file (config.ini): {e}."
!work(f) do
        # ...
end
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Full Closure Example}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

To conclude the explanation about closures, the last example shows the bracket operator\goto{operator} (@[]@) of the @Map@ interface.
A map, like @HashMap@, is used to implement a dictionary that associates some objects (keys) to some other objects (items).
The operator returns the item associated to key.
The operator has a @!def@ closure that is executed when the key is not found.
@!def@ is expected to return the item associated with the new key so it can be stored in the hashmap then returned.
By default, @!def@ aborts.


\begin{lst}
var map = new HashMap[Int, String]
map[5] = "five" # associate '5' to "five"
var x1 = map[5] # return "five"
var x2 = map[6] !def = "six" # associate '6' to "six" 
                                # and return "six"
var x3 = map[6] !def = "?" # return "six" since '6' is
                                # a known key
var x4 = map[7] !def do break "seven" # return "seven" 
                                # since '7' is not a known key
var x5 = map[7] # aborts since '7' was not associated 
                                # with the previous statement
\end{lst}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Conclusion}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The specification of Nit is not yet completed.
At least the major following features need to be implemented and documented:
\begin{itemize}
\item User-defined @enum@.
\item Union and intersection types.
\item A usable native interface to bind Nit with system libraries and other languages.
\end{itemize}
Moreover, the language also needs a complete and stable standard library.

Some other topics also need a deeper analysis : exceptions, threads, parallelism, contracts, etc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Index}\label{index}{\small\raggedleft
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@#@\goto{comment},
@!@\goto{closure},
@.@\goto{call},
@..@\goto{Range},
@...@\goto{vararg},
@{}@\goto{String},
@[]@ (array)\goto{Array},
@[]@ (operator)\goto{operator},
@[]@ (generic)\goto{generic},
@"@\goto{String},
@abstract@ (class)\goto{class},
@abstract@ (method)\goto{abstract},
adaptive typing\goto{adaptive typing},
@and@\goto{Bool},
@Array@\goto{Array},
@as@\goto{as},
@assert@\goto{assert},
attribute\goto{attribute},
@Bool@\goto{Bool},
@break@\goto{break},
break closure\goto{break closure},
cast\goto{as},
@class@\goto{class},
closure\goto{closure},
comment\goto{comment},
constructor\goto{init},
@continue@\goto{continue},
control structure\goto{control},
@do@\goto{do},
@else@ (if)\goto{if},
@else@ (abort)\goto{abort},
@end@\goto{end},
@enum@\goto{class},
@extern@\goto{extern},
@false@\goto{Bool},
@Float@\goto{Float}
@for@\goto{for},
@fun@\goto{fun},
generic class\goto{generic},
getter\goto{attribute},
@HashMap@\goto{HashMap},
identifier\goto{identifier},
@if@\goto{if},
@import@\goto{import},
@in@\goto{for},
@init@\goto{init},
inheritance\goto{superclass},
@Int@\goto{Int},
@interface@\goto{class},
@intern@\goto{intern},
@is@\goto{is},
@isa@\goto{isa},
@isset@\goto{isset},
@label@\goto{label},
@loop@\goto{loop},
@module@\goto{module}
@new@\goto{new},
@not@\goto{Bool},
@not null@\goto{null},
@null@\goto{null},
@nullable@\goto{null},
@Object@\goto{Object},
operator\goto{operator},
@or@\goto{Bool},
@or else@\goto{or else} 
@private@\goto{visibility}
@protected@\goto{visibility},
@Range@\goto{Range},
@redef@ (class)\goto{refine},
@redef@ (method)\goto{redef},
@redef@ (attribute)\goto{redef var},
@return@\goto{return},
@self@\goto{self},
setter\goto{operator},
setter (attribute)\goto{attribute},
specialization\goto{superclass},
@String@\goto{String},
@super@ (class)\goto{superclass},
@super@ (method)\goto{super},
syntax\goto{syntax},
@then@\goto{if},
@true@\goto{Bool},
type (static)\goto{static type},
@type@\goto{type},
@upper bound@\goto{upper bound},
@var@ (attribute)\goto{attribute},
@var@ (variable)\goto{var},
virtual type\goto{type},
visibility\goto{visibility},
@while@\goto{while},
@writable@\goto{writable},
}