fun/spec/v0.4.md

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:

if (x != y)
  print(x)
else if (a == b)
  print(a + b)
else
  print("Else")

While:

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:

try
  risky()
catch err
  print(err)
finally
  cleanup()

---

7) Functions and Nested Functions

User-defined functions:

fun add(a, b)
  return a + b

Nested Functions (New in v0.4): Functions can be defined within other functions to encapsulate logic.

fun outer(x)
  fun inner(y)
    return x + y
  return inner(10)

---

8) Classes and Objects

Definition:

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:

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.