fun/spec/v0.2.md

# Fun Language Specification v0.2

**Fun (Fun Uses Nothing)** is a lightweight, multi-purpose programming language designed for clarity, safety, and—above all—fun.

This document defines the language syntax and semantics as of version 0.2.

## 1. Introduction

Fun is a scripting and systems programming language inspired by the best ideas from C, Lua, and Python—yet deliberately strict in its rules to ensure readability and consistency.

 - **Readable**: fixed indentation rules, no ambiguous syntax.
 - **Strict**: type safety, no implicit coercion, no silent shadowing.
 - **Hackable**: strong system integration with safe defaults.
 - **Fun**: simple enough to learn in a day, expressive enough for real work.

## 2. Lexical Structure

### Case Sensitivity

Fun is **case-sensitive**. `Hacker` and `hacker` are different identifiers.

### Identifiers

 - May contain `a–z`, `A–Z`, `0–9`, and `_`.
 - Must not start with a number.

### Keywords

Reserved words cannot be redefined:

`if`, `else`, `for`, `while`, `fun`, `global`, `private`, `return`, `true`, `false`.

### Comments

 - Single-line:

```fun
// This is a comment
```
 - Multi-line:

```fun
/*
This is a
multi-line comment
*/
```

### Whitespace

 - Indentation is exactly two spaces.
 - Tabs are forbidden.
 - Line breaks terminate statements (no semicolons).

## 3. Data Types

### Number

 - 64-bit signed integer.

```fun
number n = 42
```

#### More number like (int) data types

 - int8, uint8 (8bit signed and unsigned integer type)
 - int16, uint16 (16bit signed and unsigned integer type)
 - int32, uint32 (32bit signed and unsigned integer type)
 - int64, uint64 (current number stays as int64)

### Float

 - 64-bit IEEE floating point.

```fun
float pi = 3.14159
```

### String

 - Double or single quotes may be used.
 - ' has higher priority, so " can appear unescaped inside '...'.
 - To include ' inside '...', escape with \'.

```fun
string s1 = "Hello"
string s2 = 'World'
string s3 = 'He said: "Fun!"'
```

### Boolean

 - Canonical values: true, false.
 - 1 and 0 are accepted in conditionals.

```fun
boolean flag = true
```

### Byte

 - Raw byte value.

```fun
byte b1 = 0x23
byte b2 = 'A'
```

### Array

 - Declared using [ ... ].

```fun
array nums = [1, 2, 3]
```

#### Supported typed arrays:

```fun
array<number> nums = [1,2,3]
array<string> names = ["Alice","Bob"]
```

#### Multidimensional arrays:

```
array<number> matrix = [[1,2],[3,4]]
```

 - Arrays or dictionaries can hold different types, even if scalars are strictly typed (including objects later).

```fun
array mixed = [1, "two", true, [3,4], matrix]
```

## 4. Variables and Scope

 - Global variables: accessible everywhere.
 - Private variables: file-local, cannot be used outside the file.
 - Redefining globals or shadowing names is forbidden.

```fun
global string message = "Hello"
private number count = 42
number nothing = 23
```

### Dynamic variables

```fun
dynamic string x = 42
x = "Now I'm a string"
```

## 5. Operators

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

## 6. Control Flow

### If/Else

```fun
if(x != y)
  print(x)
else if(a == b || h != i)
  print(a + b)
else
  if(k < 1 && l > 1)
    print("Buh!")
```

### For Loops

```fun
for i in range(1, 10)
  print(i)
```

### While Loops

```fun
while x < 10
  print(x)
  x = x + 1
```

## 7. Functions

### Internal Functions

Provided by the runtime (cannot be redefined). Examples:
print, range, system, exec.

```fun
print(a)
number lemmy = range(a, b)
string result = exec("date")
```

### User-Defined Functions

Must be declared with the fun prefix.

```fun
fun add(a, b)
  return a + b
```

#### Functions support multiple return values:

```fun
fun divide(a, b)
  if b == 0
    return 0, "division by zero"
  return a / b, ""
```

### Return Values

 - Scalars: return a + b
 - Arrays: return [a, b, c]

## 8. Modules & Includes

### System Includes

Looked up in /var/lib/fun/, supporting .so (native) and .fun (Fun code).

```fun
#include crypt/md5
#include date
#include math
```

### Local Includes

From the current working directory:

```fun
#include utils/file.fun
```

### Absolute Includes

Full path:

```fun
#include /home/user/project/lib.fun
```

### Aliasing

```fun
#include math as m
print(m.sqrt(16))
```

```fun
#include /home/user/project/universe.fun as u
print(u.size())
```

## 9. Objects

The next step... ;)

## 10. Reflections

Return "number", "string", etc.

```fun
string the_type_is = typeof(x)
```

List callable methods

```fun
array these_are_callable = methods(object)
```

## 11. Internal functions

### Call Function (Dynamic Function Helper)

 - f can be any callable (another function, system call wrapper, etc.).
 - arg can be any type (number, string, array, object).
 - This function doesn’t care about the types, it just calls f(arg).
 - This function does not perform type checking on its arguments.

```fun
call(f, arg)
  return f(arg)
```

#### Example

```fun
fun add_one(x)
  return x + 1

fun shout(s)
  return s + "!!!"

print call(add_one, 41) // 42
print call(shout, "Hi") // "Hi!!!"
```

## 12. System Integration

### Blocking

#### exec(cmd)

Executes a command, returns stdout.

```fun
string result = exec("date")
```

#### system(cmd)

Executes a command, returns exit code.

```fun
system("ls -l")
```

### Non-Blocking

#### nexec(cmd)

Executes a command, returns a future-like object for async output retrieval:

```fun
object future = nexec("long_task")
result = read(future)
wait(future)
```

#### nspawn(cmd)

Executes a command asynchronously, returns process ID.

```fun
number pid = nspawn("sleep 10")
```

#### nsystem(cmd)

Executes a command, returns exit code.

```fun
number exit_code = nsystem("ls -l")
```

### Helpers

#### wait(pid)

Blocks until process finishes, returns exit code.

#### read(pid)

Returns captured stdout (for processes started with nexec).

#### kill(pid)

Terminates process.

## 13. Error Handling

 - No implicit type coercion.
 - Redefinition of globals is a compile-time error.
 - Internal/runtime functions cannot be shadowed.
 - Compile-time: undefined variables, illegal redefinitions, type mismatch.
 - Runtime: failed system calls, division by zero, etc.

## 14. Examples

### Hello World

```fun
print("Hello, World!")
```

### Loop with Range

```fun
for i in range(1, 5)
  print(i)
```

### User Function

```fun
fun greet(name)
  return "Hello " + name

print(greet("Fun"))
```

### System Call

```fun
string now = exec("date")
print("Current time: " + now)
```

## 15. License

This document and the Fun language reference are licensed under the Apache-2.0 License.