Waddle_Language/README.md

# Waddle Programming Language

## Overview

Waddle is a modern, expressive programming language designed to be intuitive, readable, and powerful. It combines elements of object-oriented and functional programming with a focus on clarity and developer productivity.

## Key Features

### Language Characteristics
- Strong, static typing
- Object-oriented with interface support
- Functional programming constructs
- Explicit error handling
- Concise syntax

### Core Design Principles
- Readability first
- Explicit over implicit
- Minimal cognitive overhead
- Flexible type system

## Basic Syntax

### Type Declaration

#### Basic type definition
```waddle
Animal {
    // Type implementation
}
```
#### Inheritance
```waddle
Animal/Dog {
    // Dog-specific implementations
}
```

#### Interface definition
```waddle
@Mammal {
    // Interface methods
}
```

#### Interface implementation
```waddle
Animal/Dog -> [Mammal, Domesticated] {
    // Multiple interface support
}
```

### Variables

Variables are always Protected scoped. 
There is no way to make them Public or Private. 
This is by design.

#### Variable Declaration

##### Declare Now, Set later
```waddle
Integer num;

fn on_create(Integer my_num) -> [None] {
    my.num.set(my_num);
}
```

##### Declare and Set at same time
```waddle
Integer num.set(1000);
```

### Functions

#### Function declaration

##### Public function (+fn)
```waddle
+fn calculateArea(Integer width, Integer height) -> [Integer] {
    rtn width.multiply(height);
}
```

##### Protected Function (fn)
```waddle
fn calculateArea(Integer width, Integer height) -> [Integer] {
    rtn width.multiply(height);
}
```

##### Private Function (-fn)
```waddle
-fn calculateArea(Integer width, Integer height) -> [Integer] {
    rtn width.multiply(height);
}
```

#### Default Values
```waddle
fn calculateArea(Integer width.default(0), Integer height.default(0)) -> [Integer] {
    rtn width.multiply(height);
}
```

##### Lambda expression
```waddle
areaCalculator = fn(Integer width, Integer height) -> [Integer] {
    rtn width.multiply(height);
}
```

#### Concurrency Function (async)
```waddle
+proc fetchData(String url) -> [String] {
    rtn my.network.get(url);
}

proc fetchData(String url) -> [String] {
    rtn my.network.get(url);
}

-proc fetchData(String url) -> [String] {
    rtn my.network.get(url);
}
```
### Error Handling
#### Try/Catch (attempt->[ok, error])
```waddle
result = riskyOperation().attempt {
    ok {
        // Successful execution
        my.output.print("Operation successful");
    }
    
    ValueError {
        // Handle specific value errors
        my.logger.log(error.getMessage());
    }
    
    error {
        // Catch-all error handling
        my.criticalLogger.alert("Unexpected error");
    }
}

```
#### Custom error type declaration
```waddle
MathError {
    message: String;
    errorCode: Integer;
}
```
#### Function with explicit error handling
```waddle
+fn divide(Integer a, Integer b) -> [Decimal] fails with MathError {
    if (b.eq(0)) {
        my.error.fail(MathError("Division by zero", 1));
    }
    rtn a.divide(b);
}
```

### Resource Management / Context Management
```waddle
using DatabaseConnection db.set(connectionString) {
    db.execute(query);
}
```

### Iteration

#### Forward iteration
```waddle
loop(i, 0->10) {
    my.output.print(i);
}
```

#### Foward iteration, with step
```waddle
loop(i, 0->10, 2) {
    my.output.print(i); // outputs 0, 2, 4, 6, 8, 10
}
```

#### Reverse iteration
```waddle
rloop(i, 10->0) {
    my.output.print(i);
}
```

#### Reverse iteration, with step
```waddle
rloop(i, 10->0, 2) {
    my.output.print(i); // outputs 10, 8, 6, 4, 2, 0
}
```

#### Foreach loop on arrays
```waddle
Integer<> nums.set(<1, 2, 3, 4>);

nums.each(
    i -> {
        if(i.mod(2).eq(0)){
            my.output.print(i); // outputs 2, 4
        }
    }
);

```

### Boolean Expressions
#### Explicit Boolean Checks
```waddle
result = Boolean.and(
    my.age.gt(18), 
    my.status.is(Verified)
);
```
#### Object Method Boolean Checks
```waddle
if(my.age.gt(18).and(my.status.is(Verified))){
    // Pass check
}
```

### Explicit Type Conversion
```waddle
String myString.set(my.number.set(42).as(String));
```

## Type System

### Primitive Types
 - `String`
 - `Integer`
 - `Decimal`
 - `Boolean`

### Advanced Types
 - Arrays: `Type<>`
 - Custom types
 - Interface types

## Unique Language Constructs

### Dot Notation Methods
 - All objects have built-in methods
 - Chainable method calls
 - Explicit operations

```waddle
my.text.set("Hello")
    .concat(" World")
    .length();
```

### Object Lifecycle
 - Explicit constructors: `on_create`
 - Explicit destructors: `on_destroy`

### Planned Features
 - Enhanced concurrency support
 - Expanded standard library
 - Advanced module system

## Installation
_Detailed installation instructions will be added as the language develops_

## Contribution
Interested in contributing to Waddle?
 - Report issues on this repository
 - Submit pull requests
 - Provide feedback and suggestions

## License
Read the LICENSE.md file

## Current Status
Waddle is currently in active development.
The language specification and implementation are evolving.