# A tour of Alice

> Explore collections, control flow, types, objects, and safe concurrency in runnable examples.

Canonical: https://alice-lang.org/documentation/learn/tour/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Values and collections

Assignments introduce local variables. Arrays use brackets, ranges use `..`, and blocks describe work to perform for each element.

```alice
guests = ["Alice", "Rabbit", "Hatter"]
guests.each_with_index { |name, i| puts "#{i + 1}. #{name}" }
puts (1..5).map { |x| x * x }.sum
```

Expected output:

```text
1. Alice
2. Rabbit
3. Hatter
55
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.Z3Vlc3RzID0gWyJBbGljZSIsICJSYWJiaXQiLCAiSGF0dGVyIl0KZ3Vlc3RzLmVhY2hfd2l0aF9pbmRleCB7IHxuYW1lLCBpfCBwdXRzICIje2kgKyAxfS4gI3tuYW1lfSIgfQpwdXRzICgxLi41KS5tYXAgeyB8eHwgeCAqIHggfS5zdW0)

`each_with_index` gives the block an element and its zero-based index. The second expression maps each integer from 1 through 5 to its square, then sums the results. An inclusive range uses `..`; `1...5` stops before 5.

## Decisions and methods

```alice
def describe(n : Int32) : String
  if n < 0
    "negative"
  elsif n == 0
    "zero"
  else
    "positive"
  end
end
for n in -1..1
  puts describe(n)
end
```

Expected output:

```text
negative
zero
positive
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.ZGVmIGRlc2NyaWJlKG4gOiBJbnQzMikgOiBTdHJpbmcKICBpZiBuIDwgMAogICAgIm5lZ2F0aXZlIgogIGVsc2lmIG4gPT0gMAogICAgInplcm8iCiAgZWxzZQogICAgInBvc2l0aXZlIgogIGVuZAplbmQKZm9yIG4gaW4gLTEuLjEKICBwdXRzIGRlc2NyaWJlKG4pCmVuZA)

The final `if` expression supplies the method's return value. Each branch produces a `String`. Conditions and loops have their own [reference chapter](https://alice-lang.org/documentation/language/control-flow.md).

## Model data

```alice
record Point(x : Int32, y : Int32)
a = Point.new(2, 3)
puts a.x + a.y
puts a == Point.new(2, 3)
record struct Vec(x : Float64, y : Float64)
  def length : Float64
    Math.Sqrt(x * x + y * y)
  end
end
puts Vec.new(3.0, 4.0).length
```

Expected output:

```text
5
true
5
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.cmVjb3JkIFBvaW50KHggOiBJbnQzMiwgeSA6IEludDMyKQphID0gUG9pbnQubmV3KDIsIDMpCnB1dHMgYS54ICsgYS55CnB1dHMgYSA9PSBQb2ludC5uZXcoMiwgMykKcmVjb3JkIHN0cnVjdCBWZWMoeCA6IEZsb2F0NjQsIHkgOiBGbG9hdDY0KQogIGRlZiBsZW5ndGggOiBGbG9hdDY0CiAgICBNYXRoLlNxcnQoeCAqIHggKyB5ICogeSkKICBlbmQKZW5kCnB1dHMgVmVjLm5ldygzLjAsIDQuMCkubGVuZ3Ro)

A record has named fields and value equality. A `record struct` is a value type. Use a [class](https://alice-lang.org/documentation/language/classes.md) when you need an object with identity and mutable behavior.

## Work with .NET

```alice
using System.Text
builder = StringBuilder.new
builder.Append("Alice")
builder.Append(" on .NET")
puts builder.ToString()
puts Math.Sqrt(81.0)
```

Expected output:

```text
Alice on .NET
9
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.dXNpbmcgU3lzdGVtLlRleHQKYnVpbGRlciA9IFN0cmluZ0J1aWxkZXIubmV3CmJ1aWxkZXIuQXBwZW5kKCJBbGljZSIpCmJ1aWxkZXIuQXBwZW5kKCIgb24gLk5FVCIpCnB1dHMgYnVpbGRlci5Ub1N0cmluZygpCnB1dHMgTWF0aC5TcXJ0KDgxLjAp)

`using` imports a namespace; `.new` creates an object. .NET members keep their declared names, such as `Append` and `ToString`. You can use .NET's libraries and NuGet packages directly.

## Know the safety rules

Alice checks types at compile time. A nullable type uses `?`, `val` prevents reassignment, and unsafe writes across concurrent work are rejected with AL0202. These rules still apply when the syntax looks like Ruby.

```alice
val limit = 10
# limit = 20  # compile error: immutable binding
```

Read [types and nil safety](https://alice-lang.org/documentation/language/types.md) and [race safety](https://alice-lang.org/documentation/concurrency/race-safety.md) before depending on those guarantees. The next chapter builds a [real project](https://alice-lang.org/documentation/learn/first-project.md) with source files, dependencies, and tests.

## Continue reading

- Previous: [Your first program](https://alice-lang.org/documentation/learn/first-program.md)
- Next: [Your first project](https://alice-lang.org/documentation/learn/first-project.md)