# Lucia Standard Library Functions

This file summarizes the currently implemented built-in functions and built-in methods in Lucia.

## 1. Overview

Current built-ins are:
- Global functions: `print`, `len`, `input`, `str`, `int`, `float`, `bool`, `type_of`, `abs`, `min`, `max`, `pow`, `round`, `floor`, `ceil`, `sqrt`, `log`, `sin`, `cos`, `tan`, `random`, `date`, `datetime`, `today`, `now`
- String methods: `upper`, `lower`, `trim`, `ltrim`, `rtrim`, `split`, `join`, `contains`, `starts_with`, `ends_with`, `replace`, `indexOf`, `repeat`, `substring`, `pad_left`, `pad_right`, `to_int`, `to_float`, `to_bool`, `count`, `capitalize`, `title`, `is_numeric`, `is_alpha`, `is_alnum`
- List methods: `append`, `pop`, `contains`, `sort`, `reverse`, `indexOf`, `slice`, `clear`, `insert`, `remove`, `removeAt`, `extend`, `first`, `last`, `is_empty`, `copy`
- Dictionary methods: `keys`, `values`, `contains_key`, `get`, `clear`, `remove`, `items`, `is_empty`, `size`, `merge`, `put`

## 2. Global built-in functions

### `print(value)`

Signature:

```text
print(value: any) -> void
```

Behavior:
- Prints one value to output.
- Works with any supported runtime value.

Examples:

```lucia
print("hello");
print(42);
print(true);
```

---

### `len(value)`

Signature:

```text
len(value: any) -> int
```

Behavior:
- Returns the length of a collection-like value.
- Semantic layer accepts `any`.
- Recommended usage:
  - `len(listValue)`
  - `len(stringValue)`
  - `len(dictValue.keys())` or `len(dictValue.values())` for dictionaries

Examples:

```lucia
let nums: list<int> = [1, 2, 3];
print(len(nums));

let user: dict<string, any> = {"name": "Ana", "age": 20};
print(len(user.keys()));
```

---

### `input(prompt?)`

Signature:

```text
input(prompt?: any) -> string
```

Behavior:
- Reads one line from standard input.
- Accepts zero or one argument.
- If provided, the argument is used as prompt text.

Examples:

```lucia
let name: string = input();
let city: string = input("City: ");
```

---

### `str(value)`

Signature:

```text
str(value: any) -> string
```

Behavior:
- Converts a value to string.

---

### `int(value)`

Signature:

```text
int(value: any) -> int
```

Behavior:
- Converts a value to integer.

---

### `float(value)`

Signature:

```text
float(value: any) -> float
```

Behavior:
- Converts a value to floating-point number.

---

### `bool(value)`

Signature:

```text
bool(value: any) -> bool
```

Behavior:
- Converts a value to boolean.

---

### `type_of(value)`

Signature:

```text
type_of(value: any) -> string
```

Behavior:
- Returns a Lucia-friendly type name, for example:
  - `int`, `float`, `bool`, `string`, `list`, `dict`, `null`

---

### `abs(value)`

```text
abs(value: int|float) -> int|float
```

Returns the absolute value of a number.

---

### `min(a, b)` / `max(a, b)`

```text
min(a: int|float, b: int|float) -> int|float
max(a: int|float, b: int|float) -> int|float
```

Return the smaller or larger numeric value.

---

### `pow(base, exp)`

```text
pow(base: int|float, exp: int|float) -> int|float
```

Raises `base` to the power of `exp`.

---

### `round(value)` / `floor(value)` / `ceil(value)`

```text
round(value: int|float) -> int
floor(value: int|float) -> int
ceil(value: int|float) -> int
```

Numeric rounding helpers.

---

### `sqrt(value)` / `sin(value)` / `cos(value)` / `tan(value)`

```text
sqrt(value: int|float) -> float
sin(value: int|float) -> float
cos(value: int|float) -> float
tan(value: int|float) -> float
```

Single-argument numeric math helpers.

---

### `log(value)` / `log(value, base)`

```text
log(value: int|float) -> float
log(value: int|float, base: int|float) -> float
```

Computes natural log with one argument, or logarithm with explicit base when two arguments are provided.

---

### `random(min, max)`

```text
random(min: int, max: int) -> int
```

Returns a pseudo-random integer in the inclusive range `[min, max]`.

---

### `date(year, month, day)`

```text
date(year: int, month: int, day: int) -> date
```

Builds a date value.

---

### `datetime(year, month, day, hour, minute, second)`

```text
datetime(year: int, month: int, day: int, hour: int, minute: int, second: int) -> datetime
```

Builds a datetime value.

---

### `today()` / `now()`

```text
today() -> date
now() -> datetime
```

Returns the current date and current datetime respectively.

## 3. String built-in methods

### `string.upper()` / `string.lower()` / `string.trim()`

```text
string.upper() -> string
string.lower() -> string
string.trim() -> string
```

Case transformation and whitespace trimming.

### `string.ltrim()` / `string.rtrim()`

```text
string.ltrim() -> string
string.rtrim() -> string
```

Left and right trim helpers.

### `string.split(sep)`

```text
string.split(sep: string) -> list<string>
```

Splits a string using a separator.

### `string.join(items)`

```text
string.join(items: list<string>) -> string
```

Uses the receiver string as separator to join `items`.

Example:

```lucia
let sep: string = "-";
let items: list<string> = ["a", "b", "c"];
print(sep.join(items));
```

### `string.contains(x)` / `string.starts_with(x)` / `string.ends_with(x)`

```text
string.contains(x: string) -> bool
string.starts_with(x: string) -> bool
string.ends_with(x: string) -> bool
```

Membership and prefix/suffix checks.

### `string.replace(old, new)`

```text
string.replace(old: string, new: string) -> string
```

Returns a new string with replacements applied.

### `string.pad_left(width)` / `string.pad_left(width, fill)`

```text
string.pad_left(width: int) -> string
string.pad_left(width: int, fill: string) -> string
```

Left-pads a string to the requested width.

### `string.pad_right(width)` / `string.pad_right(width, fill)`

```text
string.pad_right(width: int) -> string
string.pad_right(width: int, fill: string) -> string
```

Right-pads a string to the requested width.

### `string.indexOf(x)`

```text
string.indexOf(x: string) -> int
```

Returns the first index of `x`, or `-1` if not found.

### `string.count(x)`

```text
string.count(x: string) -> int
```

Counts occurrences of `x`.

### `string.repeat(n)`

```text
string.repeat(n: int) -> string
```

Returns a string repeated `n` times.

### `string.substring(start)` / `string.substring(start, end)`

```text
string.substring(start: int) -> string
string.substring(start: int, end: int) -> string
```

Returns a substring slice.

### `string.to_int()` / `string.to_float()` / `string.to_bool()`

```text
string.to_int() -> int
string.to_float() -> float
string.to_bool() -> bool
```

String conversion helpers.

### `string.capitalize()` / `string.title()`

```text
string.capitalize() -> string
string.title() -> string
```

Title/capitalization helpers.

### `string.is_numeric()` / `string.is_alpha()` / `string.is_alnum()`

```text
string.is_numeric() -> bool
string.is_alpha() -> bool
string.is_alnum() -> bool
```

Character class checks.

## 4. List built-in methods

### `list.append(item)`

Signature:

```text
list<T>.append(item: T) -> void
```

Behavior:
- Adds exactly one element to the end of a list.
- Semantic validation enforces:
  - exactly 1 argument
  - argument type compatible with the list element type

Valid example:

```lucia
let nums: list<int> = [1, 2];
nums.append(3);
```

Invalid examples:

```lucia
nums.append();          // wrong number of arguments
nums.append("three");  // incompatible type for list<int>
```

### `list.pop()`

```text
list<T>.pop() -> T
```

Removes and returns the last element.

### `list.contains(value)`

```text
list<T>.contains(value: T) -> bool
```

Checks whether a compatible value exists in the list.

### `list.sort()`

```text
list<T>.sort() -> void
```

Sorts the list in place.

### `list.reverse()`

```text
list<T>.reverse() -> void
```

Reverses the list in place.

### `list.indexOf(value)`

```text
list<T>.indexOf(value: T) -> int
```

Returns the first index of `value`, or `-1` if not found.

### `list.slice(start)` / `list.slice(start, end)`

```text
list<T>.slice(start: int) -> list<T>
list<T>.slice(start: int, end: int) -> list<T>
```

Returns a sliced list.

### `list.clear()`

```text
list<T>.clear() -> void
```

Clears all list items.

### `list.insert(index, value)`

```text
list<T>.insert(index: int, value: T) -> void
```

Inserts one item at an index.

### `list.remove(value)`

```text
list<T>.remove(value: T) -> void
```

Removes one matching value when present.

### `list.removeAt(index)`

```text
list<T>.removeAt(index: int) -> T
```

Removes and returns the item at `index`.

### `list.extend(items)`

```text
list<T>.extend(items: list<T>) -> void
```

Appends all items from another list.

### `list.first()` / `list.last()`

```text
list<T>.first() -> T
list<T>.last() -> T
```

Returns first or last element.

### `list.is_empty()`

```text
list<T>.is_empty() -> bool
```

Returns whether the list has no elements.

### `list.copy()`

```text
list<T>.copy() -> list<T>
```

Returns a shallow copy.

## 5. Dictionary built-in methods

### `dict.keys()`

Signature:

```text
dict<K, V>.keys() -> list<K>
```

Behavior:
- Returns a list with dictionary keys.
- Semantic validation enforces zero arguments.

Example:

```lucia
let user: dict<string, any> = {"name": "Ana", "age": 20};
let ks: list<string> = user.keys();
print(ks);
```

---

### `dict.values()`

Signature:

```text
dict<K, V>.values() -> list<V>
```

Behavior:
- Returns a list with dictionary values.
- Semantic validation enforces zero arguments.

Example:

```lucia
let user: dict<string, any> = {"name": "Ana", "age": 20};
let vs: list<any> = user.values();
print(vs);
```

---

### `dict.contains_key(key)`

```text
dict<K, V>.contains_key(key: K) -> bool
```

Checks whether the dictionary contains the given key.

---

### `dict.get(key)` / `dict.get(key, default)`

```text
dict<K, V>.get(key: K) -> V
dict<K, V>.get(key: K, default: V) -> V
```

Returns the value associated with a key, or the provided default when given.

---

### `dict.clear()`

```text
dict<K, V>.clear() -> void
```

Removes all entries.

---

### `dict.remove(key)`

```text
dict<K, V>.remove(key: K) -> void
```

Removes one key when present.

---

### `dict.items()`

```text
dict<K, V>.items() -> list<any>
```

Returns a list of key/value entries.

---

### `dict.is_empty()`

```text
dict<K, V>.is_empty() -> bool
```

Returns whether dictionary has no entries.

---

### `dict.size()`

```text
dict<K, V>.size() -> int
```

Returns number of entries.

---

### `dict.merge(other)`

```text
dict<K, V>.merge(other: dict<K, V>) -> dict<K, V>
```

Returns a merged dictionary value.

---

### `dict.put(key, value)`

```text
dict<K, V>.put(key: K, value: V) -> void
```

Sets key/value entry.

## 6. Built-ins by target

Lucia built-ins are compiled to each target with mostly equivalent behavior:

- Python target:
  - `print` -> `print`
  - `len` -> `len`
  - `input` -> `input`
  - `str` -> `str`
  - `int` -> `int`
  - `float` -> `float`
  - `bool` -> `bool`
  - `type_of` -> `__lucia_type_of(...)` helper
  - `abs` -> `abs`
  - `min` -> `min`
  - `max` -> `max`
  - `pow` -> `pow`
  - `round` -> `round`
  - `floor` -> `math.floor`
  - `ceil` -> `math.ceil`
  - `sqrt` -> `math.sqrt`
  - `log` -> `math.log`
  - `sin` -> `math.sin`
  - `cos` -> `math.cos`
  - `tan` -> `math.tan`
  - `random` -> `random.randint(min, max)`
  - `date` -> `datetime.date(year, month, day)`
  - `datetime` -> `datetime.datetime(year, month, day, hour, minute, second)`
  - `today` -> `datetime.date.today()`
  - `now` -> `datetime.datetime.now()`
  - string methods -> Python string operations (`upper`, `lower`, `strip`, `lstrip`, `rstrip`, `split`, `join`, `in`, `startswith`, `endswith`, `replace`, `find`, `rjust`, `ljust`, `int`, `float`, bool conversion helper, `count`, `capitalize`, `title`, `isnumeric`, `isalpha`, `isalnum`, repetition, slicing)
  - `append` -> `list.append`
  - `pop` -> `list.pop`
  - list `contains` -> `value in list`
  - `sort` -> `list.sort()`
  - `reverse` -> `list.reverse()`
  - list `indexOf` -> `list.index(...)` with not-found fallback
  - list `slice` -> Python slicing
  - `clear` -> `.clear()` for list/dict
  - list `insert` -> `list.insert(index, value)`
  - list `remove` -> remove if present
  - list `removeAt` -> `list.pop(index)`
  - list `extend` -> `list.extend(other)`
  - list `first` / `last` -> indexed access
  - list/dict `is_empty` -> `len(x) == 0`
  - list `copy` -> `list.copy()`
  - `keys` -> `dict.keys()`
  - `values` -> `dict.values()`
  - `contains_key` -> `key in dict`
  - `get` -> `dict.get(...)`
  - `items` -> `list(dict.items())`
  - `size` -> `len(dict)`
  - `merge` -> `dict1 | dict2`
  - `put` -> `dict.__setitem__(key, value)`

- JavaScript target:
  - `print` -> `console.log`
  - `len` -> `.length`
  - `input` -> `__lucia_input(...)` helper
  - `str` -> `String(...)`
  - `int` -> `Math.trunc(Number(...))`
  - `float` -> `Number(...)`
  - `bool` -> `Boolean(...)`
  - `type_of` -> `__lucia_type_of(...)` helper
  - `abs` -> `Math.abs(...)`
  - `min` -> `Math.min(...)`
  - `max` -> `Math.max(...)`
  - `pow` -> `Math.pow(...)`
  - `round` -> `Math.round(...)`
  - `floor` -> `Math.floor(...)`
  - `ceil` -> `Math.ceil(...)`
  - `sqrt` -> `Math.sqrt(...)`
  - `log` -> `Math.log(...)` (or `Math.log(value) / Math.log(base)`)
  - `sin` -> `Math.sin(...)`
  - `cos` -> `Math.cos(...)`
  - `tan` -> `Math.tan(...)`
  - `random` -> `Math.floor(Math.random() * ((max - min) + 1)) + min`
  - `date` -> `new Date(year, month - 1, day, 0, 0, 0)`
  - `datetime` -> `new Date(year, month - 1, day, hour, minute, second)`
  - `today` -> `Date` at local midnight
  - `now` -> `new Date()`
  - string methods -> JavaScript string operations (`toUpperCase`, `toLowerCase`, `trim`, `trimStart`, `trimEnd`, `split`, `join`, `includes`, `startsWith`, `endsWith`, `replace` pattern via split/join, `indexOf`, `padStart`, `padEnd`, `Number`, bool conversion helper, `capitalize` helper, `title` helper, regex checks, `repeat`, `slice`)
  - `append` -> `.push`
  - `pop` -> `.pop`
  - list `contains` -> `.includes(...)`
  - `sort` -> `.sort()`
  - `reverse` -> `.reverse()`
  - list `indexOf` -> `.indexOf(...)`
  - list `slice` -> `.slice(...)`
  - `clear` -> list length reset or dictionary key deletion
  - list `insert` -> `.splice(index, 0, value)`
  - list `remove` -> remove first matching item if present
  - list `removeAt` -> `.splice(index, 1)[0]`
  - list `extend` -> `.push(...other)`
  - list `first` / `last` -> indexed access
  - list/dict `is_empty` -> length/keys check
  - list `copy` -> `.slice()`
  - `keys` -> `Object.keys(...)`
  - `values` -> `Object.values(...)`
  - `contains_key` -> `Object.prototype.hasOwnProperty.call(...)`
  - `get` -> property access / fallback expression
  - `items` -> `Object.entries(...)`
  - `size` -> `Object.keys(...).length`
  - `merge` -> object spread merge
  - `put` -> assignment by key

Notes on cross-target differences:
- `dict.get(key)` when key is missing:
  - Python target returns `None` (native `dict.get` behavior).
  - JavaScript target currently returns `undefined` (property access behavior).
- `dict.get(key, default)` behaves consistently in both targets (returns default when key is missing).

## 7. Method chaining

Method calls can be chained arbitrarily:

```lucia
let words: list<string> = text.trim().split(" ");
let result: bool = text.trim().lower().contains("lucia");
let upper: string = text.trim().upper();
```

The receiver of each successive call is the return value of the previous one. All semantic validations apply to each step in the chain.

## 8. Notes and current limits

- Global built-ins are validated in semantic analysis and mapped in both code generators.
- Type-bound operations are implemented as methods for strings, lists, and dictionaries.
- Method calls can be chained using the `.method()` syntax on any expression that returns a valid receiver type.
- Additional built-ins should be added consistently in:
  - semantic analyzer (type rules and arity checks)
  - target code generators (Python and JavaScript mappings)
