fun/spec/v0.1.md

# Fun Language Specification v0.1

**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.1.

## 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**. `Fun` and `fun` 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`, `fi`, `f`, `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
```

### 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]
```

## 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
```

## 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 "Hello, Fun!"
```

### User-Defined Functions

Must be declared with the fun prefix.

```fun
fun add(a, b)
  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
```

## 9. 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 stdout.

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

#### nspawn(cmd)

Executes a command asynchronously, returns process ID.

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

#### nsystem(cmd)

Executes a command, returns exit code.

```fun
system("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.

## 10. Error Handling

 - No implicit type coercion.
 - Redefinition of globals is a compile-time error.
 - Using undefined variables or functions is an error.
 - Internal/runtime functions cannot be shadowed.

## 11. 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
```

## 12. License

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