Getting Started, Types, and Values

Hello, World

• Every Gleam project starts with gleam new
  • Creates a project directory with a source file, a test file, and a gleam.toml

name = "basics"
version = "1.0.0"
target = "erlang"

[dependencies]
gleam_stdlib = ">= 0.34.0 and < 2.0.0"

[dev-dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

• Use gleam run to compile and execute the default entry point

import gleam/io

pub fn main() {
  let name = "Gleam"
  io.println("Hello from " <> name <> "!")
}

Hello from Gleam!

• import gleam/io makes the io module available
• pub fn main() is the entry point
  • pub (public) makes it visible outside the module
  • fn is short for "function"
• let name = "Gleam" creates an immutable binding
  • All bindings are final: reassigning a name is a compile error
• <> concatenates strings
  • Gleam does not overload + to add strings
• io.println prints a line with a newline
  • io.debug prints any value using its debug representation

Arithmetic

pub fn main() {
  let sum = 2 + 2
  io.println(string.inspect(sum))

  let product = 6 * 7
  io.println(string.inspect(product))

  let float_div = int.to_float(10) /. int.to_float(3)
  io.println(string.inspect(float_div))
}

4
42
3.3333333333333335

• 2 + 2 is integer arithmetic
  • The result is Int, not Float
• Gleam separates integer and floating-point operators: +, -, *, / for Int; +., -., *., /. for Float
  • int.to_float converts before you can mix them
• Yes, this seems pedantic, but it's consistent

Built-in Types

• Gleam's primitive types map directly to Python equivalents
• But the type system prevents you from mixing them
• Int: arbitrary-precision integer, like Python's int
• Float: 64-bit floating-point, like Python's float
• String: UTF-8 text, like Python's str
• Bool: True or False, like Python's bool
• Nil: the unit value, similar to Python's None but much rarer

Custom Types

• Most important building block in Gleam is the custom type
• packages one or more named variants into a single type

pub type Color {
  Red
  Green
  Blue
}

type Shape {
  Circle(Float)
  Rectangle(Float, Float)
}

• type Color { Red Green Blue } defines a type with three variants
  • Like a Python Enum, but integrated into the type system
  • Red, Green, Blue are constructors, not strings
• type Shape { Circle(Float) Rectangle(Float, Float) } defines variants that carry data
  • Circle(Float) is like a Python dataclass with one float field
  • Rectangle(Float, Float) has two float fields
  • The compiler knows exactly which fields each variant carries
• There is no inheritance: custom types are closed and complete
• Now a function that uses the type:

fn area(shape: Shape) -> Float {
  case shape {
    Circle(r) -> 3.14159 *. r *. r
    Rectangle(w, h) -> w *. h
  }
}

red is Red
circle is Circle(3.0)
rectangle is Rectangle(4.0, 5.0)
circle area is 28.274309999999996
rectangle area is 20.0

• case shape { ... } matches on the value of shape
• Each arm extracts fields, e.g., Circle(r) binds the radius to r
• The compiler verifies that every variant is handled
  • Remove the Rectangle arm and the compiler reports an error
  • Python's if isinstance chains have no such guarantee
• The last expression in each arm is the arm's value: no return needed
• 3.14159 *. r *. r uses *. because r is a Float
  • Yes, we will get π from a library the next time

Records with Named Fields

• When a variant carries several fields, naming them makes the code clearer

type Flavor {
  Chocolate
  Vanilla
  Strawberry
}

type Container {
  Cone
  Cup
}

type IceCream {
  IceCream(flavor: Flavor, container: Container)
}

• IceCream(flavor: Flavor, container: Container) defines a variant with named fields
  • flavor: Flavor means the field named flavor holds a Flavor value
  • Access fields with dot notation: item.flavor, item.container
• Flavor and Container are separate custom types defined above IceCream
  • This is like a Python dataclass whose field types are enums
• Creating a value with named fields: IceCream(flavor: Chocolate, container: Cone)
  • You can also write IceCream(Chocolate, Cone) when the order is unambiguous

fn display(item: IceCream) -> String {
  flavor_string(item.flavor) <> " in a " <> container_string(item.container)
}

chocolate cone is Chocolate in a cone
vanilla cone is Vanilla in a cup
strawberry cone is Strawberry in a cone

• item.flavor and item.container access named fields using dot notation
• flavor_string and container_string are private helper functions (no pub)
• The <> operator chains string concatenation left to right

Tuples

• A tuple groups a fixed number of values of potentially different types
• Gleam writes tuples with a # prefix: #(1, "hello", True)

  let t = #(1, "hello", True)
  io.println(string.inspect(t))

• #(1, "hello", True) creates a tuple of type #(Int, String, Bool)
• The type is inferred: you do not need to write it explicitly
• As in Python, tuples are useful for returning multiple values from a function

  let #(a, b, c) = t
  io.println("a from tuple is " <> string.inspect(a))
  io.println("b from tuple is " <> string.inspect(b))
  io.println("c from tuple is " <> string.inspect(c))

#(1, "hello", True)
a from tuple is 1
b from tuple is "hello"
c from tuple is True

• let #(a, b, c) = t destructs the tuple into three bindings
  • a is 1, b is "hello", c is True
  • Like Python's a, b, c = t but the # makes clear a tuple is expected
• Gleam does not have indexed access like t[0]
  • Destructuring is the idiomatic way to extract tuple fields

Type Inference

• Gleam almost never requires you to write type annotations
• The compiler infers the type of every expression from context
  • let x = 42 infers x: Int
  • let s = "hello" infers s: String
  • fn area(shape: Shape) -> Float carries explicit annotations, but they are optional for local bindings
• You can always add annotations for documentation:
  • The compiler checks annotations against the inferred type and reports a mismatch as an error

let x: Int = 42
let name: String = "Gleam"

Check Understanding

Exercises