# Fun Language Specification v0.4

This document describes Fun (Fun Uses Nothing) as of version 0.4. It supersedes v0.3 by formalizing nested functions, refining modules, and updating system integrations.

---

## 1) Overview and Goals

- Readable: strict, indentation-based syntax (2 spaces), no semicolons.
- Safe: explicit types, no implicit numeric coercions, bounds-checked operations, controlled side effects.
- Hackable: pragmatic stdlib, process I/O, sockets, threads, and now nested functions for better encapsulation.

What’s new in v0.4 (high level):
- Nested Functions: functions can now be declared inside other functions.
- Enhanced CI integration for standard library and examples.
- Refinement of optional extensions (removal of obsolete/unmaintained integrations like libsql, tcltk, notcurses).

---

## 2) Lexical Structure

- Case-sensitive identifiers: letters, digits, `_`; must not start with a digit.
- Comments:
  - Single-line: `// comment`
  - Multi-line: `/* ... */`
- Whitespace and newlines:
  - Indentation is exactly 2 spaces; tabs are forbidden.
  - Newline terminates statements; no semicolons.

Reserved keywords (cannot be redefined):
- `if`, `else`, `for`, `while`, `break`, `continue`
- `fun`, `return`
- `class`, `extends`
- `global`, `private`
- `true`, `false`
- `try`, `catch`, `finally`

---

## 3) Types

Scalar types:
- `number`: 64-bit signed integer.
- `float`: 64-bit IEEE-754 floating point.
- `string`
- `boolean`: `true` / `false`.
- `byte`: 8-bit value.

Fixed-width integers (signed/unsigned):
- `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`

Aggregate types:
- `array` and typed arrays: `array<T>`
- `map<K, V>` (dictionary / associative array)
- `object` (instances of `class`)

---

## 4) Variables and Scope

- `global` variables are visible program-wide.
- `private` variables are file-local (module private).
- Local variables are scoped to the function or block.
- Rebinding a global or shadowing a name is a compile-time error.

---

## 5) Operators and Builtins

Arithmetic: `+`, `-`, `*`, `/`, `%`
Comparison: `==`, `!=`, `>`, `<`, `>=`, `<=`
Boolean: `&&`, `||`, `!`
Assignment: `=`

Bitwise helpers (functions):
- `band(a, b)`, `bor(a, b)`, `bxor(a, b)`, `bnot(a)`, `shl(a, n)`

---

## 6) Control Flow

If/Else:
```fun
if (x != y)
  print(x)
else if (a == b)
  print(a + b)
else
  print("Else")
```

While:
```fun
while i < 10
  i = i + 1
  if i == 5
    continue
  if i > 8
    break
```

For:
- Range: `for i in range(0, 5)`
- Array: `for x in arr`
- Map keys: `for k in keys(m)`

Try/Catch/Finally:
```fun
try
  risky()
catch err
  print(err)
finally
  cleanup()
```

---

## 7) Functions and Nested Functions

User-defined functions:
```fun
fun add(a, b)
  return a + b
```

Nested Functions (New in v0.4):
Functions can be defined within other functions to encapsulate logic.
```fun
fun outer(x)
  fun inner(y)
    return x + y
  return inner(10)
```

---

## 8) Classes and Objects

Definition:
```fun
class Point(x, y)
  x = 0
  y = 0
  fun _construct(this, x, y)
    this.x = x
    this.y = y
  fun move(this, dx, dy)
    this.x = this.x + dx
    this.y = this.y + dy
```

Inheritance:
```fun
class Child(x, y) extends Point
  fun describe(this)
    return "Child at " + to_string(this.x)
```

---

## 9) Modules and Includes

- System: `#include <utils/math.fun>`
- Local: `#include "./local.fun"`
- Namespaced: `#include <math.fun> as m`

---

## 10) Collections

- Arrays: `[1, 2, 3]`, `push(arr, val)`, `join(arr, sep)`
- Maps: `{ "key": "value" }`, `has(m, key)`, `keys(m)`

---

## 11) Concurrency (Threads)

- `thread_spawn(fn, args)`
- `thread_join(id)`
- `sleep(ms)`

---

## 12) System and Networking

- Processes: `exec(cmd)`, `system(cmd)`, `nexec(cmd)`, `wait(pid)`
- Environment: `env(NAME)`, `argv()`
- Networking: `tcp_connect(host, port)`, `sock_send(fd, data)`, `sock_recv(fd, nbytes)`

---

## 13) Error Handling and Type Safety

- No implicit type coercion.
- Overflow on fixed-width types is an error.
- Shadowing internal functions is forbidden.

---

## 14) Changelog (from v0.3 to v0.4)

- Added: Nested functions support (functions within functions).
- Added: Enhanced CI workflow for testing examples and stdlib.
- Removed: `libsql`, `tcltk`, `notcurses`, and `libressl` optional extensions to streamline the core.
- Fixed: Various bugs in parser and line number reporting.

---

## 15) Versioning

- v0.4 continues the 0.x.y semantic development phase.
- Backward compatibility with v0.3 is maintained except for removed optional extensions.