Lists, ranges, and objects

A variable usually names one value. A collection keeps several related values together. Sugar has two main collection shapes: lists and objects.

Create a list

A list keeps entries in order. Write its entries between parentheses and separate them with commas:

let directions = ("north", "east", "below");

This list contains three strings. directions names the whole list.

An empty list uses empty parentheses:

let directions = ();

A one-entry list needs a trailing comma:

let directions = ("north",);

Without the comma, ("north") only groups one expression; it is not a list.

Read entries by index

Every position in a list has an index. Sugar indexes begin at 1:

directions[1]

This produces "north". directions[2] produces "east".

Use len() to ask how many entries a list contains:

directions.len()

The result is 3.

Understand list types

When a declaration needs an explicit list type, Sugar also records the type of its entries:

var guests: List<Joi> = ();

Read List<Joi> as “list of JOIs.” The angle brackets provide a type argument to List:

List is the collection type.
Joi is the type allowed for each entry.
<Joi> configures the list type; it does not create a value.

Reference material sometimes writes List<T> as shorthand for “a list with some entry type.” The T is a placeholder, not code to copy. A real declaration replaces it with any Sugar value type:

let scores: List<number> = (10, 20, 30);
let names: List<str> = ("Mina", "Noor");
let flags: List<bool> = (true, false);
let groups: List<List<number>> = ((1, 2), (3, 4));

Likewise, List<Seat> means a list containing Seat values. In prose, these docs say “a list of JOIs” or “a list of seats” unless the exact type spelling matters.

Sugar often infers a list’s entry type from its values, so ordinary local lists do not need an annotation.

Create a number range

A range creates consecutive whole numbers:

1..5

.. excludes the ending number, so this contains 1, 2, 3, and 4.

1..=5

..= includes the ending number, so this contains 1 through 5.

The bounds may be expressions:

1..=sides

Use in to test membership:

roll in 1..=6

This condition is true when roll is a whole number from 1 through 6. One range may contain at most 100 values.

Create an object

An object groups values under property names:

let challenge = {
  name: "Midnight Run",
  difficulty: 15,
  reward: 20,
};

name, difficulty, and reward are properties. Read one with a dot:

challenge.reward

This produces 20.

Objects may contain other collections:

let amulet = {
  name: "Cursed Amulet",
  stats: {
    charges: 3,
    corruption: 40,
  },
};

Read a nested property by continuing the path:

amulet.stats.corruption

If the object belongs to a mutable variable, a nested property may be assigned:

amulet.stats.corruption += 10;

The next lesson introduces closures as first-class function values. After that, Working with lists gathers conditional entries, list composition, updates, searches, transformations, function lists, and chaining into one practical lesson.