# Constants

## A value fixed for the run

A constant is a name in capitals at the top level of a file, with a value after `=`. It never changes, and any function of the file can read it:

```agentica
SECONDS_PER_DAY = 24 * 60 * 60
GREETING = "hello"

def main() -> Void
  puts("#{GREETING}: #{SECONDS_PER_DAY}")
end
```

```output
hello: 86400
```

A name is capital letters, digits and `_`, at least two characters (`LIMIT`, `MAX_DEPTH`). Another spelling is `PARSE-CONSTANT-NAME`:

```agentica
MaxDepth = 8

def main() -> Void
  puts(MaxDepth)
end
```

Does not compile: `error[PARSE-CONSTANT-NAME]`

- Constants come after the imports and before types and functions, with no blank line between them.
- Give a type as in a binding (`RATIO: Float = 1.5`). It also types `[]` and `{}`.

## Build a table once

A function that builds a list or a map runs the code each time it is called. A constant is built once, before `main`, and every read gives the same value:

```agentica
PRICES = {"tea": 3, "cocoa": 5}
FRUITS = Set.new(["kiwi", "apple"])

def kind(name: String) -> String
  return "fruit" if FRUITS.include?(name)

  "drink"
end

def main() -> Void
  puts(PRICES.get("cocoa", 0))
  puts(kind("kiwi") + " " + kind("tea"))
end
```

```output
5
fruit drink
```

- A constant works like any value: `PRICES.get(...)`, `PRICES["tea"]`, `FRUITS.size`.
- A constant may read another one, above or below it. A loop is `CHECK-CONSTANT-CYCLE`.

## When a constant is built

- A literal such as `WIDTH = 8` is part of the program.
- Any other constant is built once, before `main`, and only if a function that `main` can reach reads it. An unread constant never runs.
- If an initializer fails, the program stops before `main` prints anything:

```agentica
BAD = [1][5]

def main() -> Void
  puts("never printed")
  puts(BAD)
end
```

Runtime error: `error[RUNTIME-INDEX-OUT-OF-RANGE]`

The stack trace names `BAD`.

## What a constant may hold

- It may hold literals, lists, maps, sets, struct and enum values, operators, other constants and builtins without effects (`Set.new`, `map`, `reduce`, ...).
- A call of your own function, a function value, a `while` loop or a builtin that reads or writes the world is `CHECK-CONSTANT-EXPRESSION`:

```agentica
LINE = IO.gets!()

def main() -> Void
  puts(LINE)
end
```

Does not compile: `error[CHECK-CONSTANT-EXPRESSION]`

- Its type is numbers, text, lists, maps, sets, ranges, `Result`, or structs and enums of those. A channel, task or function is `CHECK-CONSTANT-TYPE`. The one exception is a whole initializer `ATS.new()`, a table that every task shares ([a constant table](https://www.agentica-lang.com/agentica/library/concurrency/ats/index.md#a-constant-table)).
- Nothing assigns to a constant: `LIMIT = 2` in a function is `PARSE-INVALID-ASSIGNMENT-TARGET`.

## Share a constant between files

A constant above `private` (or in a file with no `private`) is public, and the importing file brings it in by name, like a function or a struct:

File `limits.agc`:

```agentica
MAX = 100
NAMES = ["x", "y"]
```

```agentica
import {MAX, NAMES as LABELS} from "limits"

def main() -> Void
  puts(MAX)
  puts(LABELS.size)
end
```

```output
100
2
```

A file that imports the module under an alias reads the constant as `Limits.MAX`, like an exported function:

```agentica
import Limits from "limits"

def main() -> Void
  puts(Limits.MAX)
  puts(Limits.NAMES.size)
end
```

```output
100
2
```

A constant the module keeps private is `CHECK-IMPORT-NAME`, as for a function.
