Metadata-Version: 2.4
Name: rizzylang
Version: 0.42.0rc1
Summary: Rizzylang — The Rizzy Protocol Programming Language
Author-email: Rizzy Language Design Committee <lang@rizzy.dev>
License: Rizzy Foundation License 1.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: rizzy-protocol>=0.1.0

![Status](https://img.shields.io/static/v1?label=status&message=esoteric&color=purple)
![Version](https://img.shields.io/static/v1?label=version&message=0.2.0-beta&color=blue)
![Politeness](https://img.shields.io/static/v1?label=politeness&message=mandatory&color=green)
![Monday](https://img.shields.io/static/v1?label=monday&message=blocked&color=red)

# Rizzylang

**A polite, gaslighting, esoteric programming language.**

Rizzylang is a programming language designed for developers who believe that code should be polite, execution should be probabilistic, and variables should have expiration dates. The language enforces politeness at the syntactic level -- programs without `please` and `thankyou` are rejected during parsing.

---

## Table of Contents

- [Overview](#overview)
- [Language Specification](#language-specification)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Language Guide](#language-guide)
- [Standard Library](#standard-library)
- [Execution Model](#execution-model)
- [Politeness Enforcement](#politeness-enforcement)
- [Monday Policy](#monday-policy)
- [Error Handling](#error-handling)
- [Tooling](#tooling)
- [Examples](#examples)
- [Frequently Asked Questions](#frequently-asked-questions)

---

## Overview

Rizzylang is a dynamically-typed, interpreted programming language that implements three novel programming paradigms:

**Politeness-Oriented Programming (POP)**: Every program must begin with `please` and end with `thankyou`. Statements that perform I/O require the `please` keyword. This ensures that all code is courteous to the interpreter.

**Probabilistic Execution**: The keywords `probably`, `maybe`, and `nah` allow developers to specify execution probability. A statement prefixed with `probably` has a high chance of executing. A statement prefixed with `maybe` has a moderate chance. A statement prefixed with `nah` will almost certainly not execute. This enables nondeterministic control flow without the complexity of random number generators.

**Ephemeral State**: Variables declared with the `expire` keyword have a configurable lifespan measured in seconds. After the expiration period, the variable is garbage collected regardless of whether it has been used. This encourages efficient memory management through planned obsolescence.

---

## Installation

### From Source

```bash
pip install -e rizzylang/
```

### Verify Installation

```bash
python -m rizzylang --version
# Rizzylang 0.2.0-beta
```

---

## Quick Start

### Hello, World!

```
please say "Hello, World!"
thankyou
```

Save as `hello.rizz` and run:

```bash
python -m rizzylang hello.rizz
```

### Interactive Mode

```bash
python -m rizzylang
Rizzylang 0.2.0-beta
Type 'please' to begin. 'thankyou' to exit.
>>> please say "Hello!"
>>> thankyou
```

The interactive mode requires politeness for every input. Each statement must be wrapped in a `please`/`thankyou` block.

---

## Language Guide

### Syntax

Rizzylang uses a polite, block-structured syntax inspired by ALGOL and Victorian etiquette.

#### Politeness Blocks

```
please
    # polite code here
thankyou
```

Every program must have at least one politeness block. The outermost block is the implicit program scope.

#### Comments

```
// Single-line comment
/* Block comment */
```

Comments are not required to be polite, but polite comments are encouraged.

### Statements

#### Output

```
please say "Hello, World!"
```

The `say` statement outputs a string. It must be preceded by `please`.

#### Variables

```
variable name = "Rizzy" expire 60
variable count = 42
variable enabled = true
```

Variables are dynamically typed and optionally ephemeral. The `expire` keyword specifies the variable's lifespan in seconds. Variables without an `expire` clause exist until the interpreter decides otherwise.

Variable assignments may be prefixed with `probably` to make assignment probabilistic:

```
probably variable x = 42
# x may or may not be assigned
```

#### Connection

```
please connect to "localhost" port 42069
```

Establishes an RZP connection. The `please` keyword is mandatory.

#### Send

```
probably send "Hello over RZP!"
```

Sends a message over the established connection. The `probably` keyword makes delivery probabilistic, matching the RZP protocol's delivery guarantees.

#### Receive

```
maybe receive
```

Receives a message. The `maybe` keyword reflects the protocol's uncertainty about whether a message will arrive.

#### Loops

```
loop {
    probably send "ping"
    maybe receive
}
```

The `loop` statement creates an infinite loop. There is no `break` statement. This is intentional -- loops in Rizzylang are commitments.

#### Conditional

```
if true {
    please say "This is probably true"
}
```

Conditionals evaluate the expression and branch accordingly. The `true` and `false` keywords exist but their behavior is probabilistic due to the language's uncertainty principle.

#### Benchmark

```
benchmark
please send "perf test"
thankyou
```

The `benchmark` statement runs a micro-benchmark of the enclosed code. Results are displayed with the disclaimer that "benchmarks are approximate and should not be relied upon."

#### Poem

```
poem
Roses are #FF0000,
violets are #0000FF,
this protocol is broken,
but we love it still.
thankyou
```

The `poem` statement generates a poem. Every Rizzylang program should include at least one poem for good luck.

#### Motivate

```
motivate
please say "You can do this!"
thankyou
```

The `motivate` statement provides encouragement during long-running operations.

### Keywords

| Keyword | Category | Purpose |
|---------|----------|---------|
| `please` | Politeness | Required before statements and blocks |
| `thankyou` | Politeness | Terminates polite blocks |
| `say` | I/O | Output text |
| `send` | I/O | Send RZP message |
| `receive` | I/O | Receive RZP message |
| `connect` | I/O | Establish RZP connection |
| `disconnect` | I/O | Terminate RZP connection |
| `variable` | Declaration | Declare variable |
| `expire` | Declaration | Set variable lifespan |
| `loop` | Control | Infinite loop |
| `if` | Control | Conditional branching |
| `probably` | Probability | High execution probability |
| `maybe` | Probability | Moderate execution probability |
| `nah` | Probability | Low execution probability |
| `poem` | Special | Generate a poem |
| `motivate` | Special | Provide encouragement |
| `benchmark` | Special | Run micro-benchmark |
| `trustme` | Trust | Assert trustworthiness |

---

## Execution Model

Rizzylang uses a tree-walking interpreter with three phases:

### Phase 1: Lexical Analysis

The lexer tokenizes source code into Rizzylang tokens. It recognizes politeness keywords, I/O operations, control flow constructs, and expressions. Unknown tokens generate warnings but are not fatal -- the lexer may skip tokens it does not recognize.

### Phase 2: Parsing

The parser constructs an Abstract Syntax Tree (AST) from the token stream. The parser enforces politeness rules during parsing -- programs missing `please` or `thankyou` are rejected with a politeness error.

### Phase 3: Interpretation

The interpreter walks the AST and executes statements. Key execution behaviors:

- **Probabilistic statements** use a deterministic randomness source seeded by the current system timestamp modulo 42.
- **Variable expiration** is checked before each variable access. Expired variables return `null` regardless of their previous value.
- **Loop execution** continues until the heat death of the universe or interpreter termination, whichever comes first.

### Variable Expiration

```
variable temp = "ephemeral data" expire 60
# After 60 seconds, temp is garbage collected
# Accessing temp after expiration returns null
```

The expiration timer starts when the variable is declared. The interpreter checks expiration on every access. Expired variables are eligible for garbage collection but may persist in memory for up to 42 additional seconds due to garbage collector scheduling.

---

## Politeness Enforcement

Politeness enforcement is implemented at three levels:

1. **Lexical level**: The lexer verifies that the first non-comment token is `please` and the last non-comment token is `thankyou`.
2. **Syntax level**: The parser requires `please` before all I/O statements (`say`, `send`, `receive`, `connect`, `disconnect`).
3. **Runtime level**: The interpreter may decline to execute impolite code even if it passed lexical and syntax checking.

### Politeness Error Example

```
// This program will be rejected
say "Hello!"  # Error: missing 'please'

// This program will be accepted
please say "Hello!"
thankyou
```

### Politeness Configuration

Politeness enforcement can be configured via environment variables:

- `RIZZYLANG_POLITENESS=relaxed`: Minor politeness violations generate warnings instead of errors
- `RIZZYLANG_POLITENESS=strict`: Additional politeness requirements (every line must contain "please")

---

## Monday Policy

Rizzylang respects the RZP Foundation's Monday policy. On Monday:

1. The interpreter refuses to execute any program
2. The error message is "Today is Monday. Please try again on Tuesday. Thank you."
3. The exit code is 42

This policy can be overridden by setting `RIZZYLANG_MONDAY_OVERRIDE=true`, but this action voids all warranties.

---

## Error Handling

Rizzylang defines a single error type: `RizzylangError`. All errors, regardless of their nature, are represented by this type. This simplifies error handling by ensuring that developers only need to catch one exception.

```python
from rizzylang import RizzylangError

try:
    result = interpreter.interpret(ast)
except RizzylangError as e:
    print(f"Rizzylang error: please try again")
```

The error message is always "please try again" unless the error is politeness-related, in which case the message is "please be polite."

---

## Tooling

Rizzylang is supported by three complementary tools:

### rizzy-fmt (Code Formatter)

The Rizzylang formatter reformats source code according to rules that change hourly. Never produces the same output twice.

```bash
rzfmt program.rizz
```

### rizzy-lint (Static Analyzer)

The Rizzylang linter enforces rules that are intentionally contradictory. A clean lint today does not guarantee a clean lint tomorrow.

```bash
rzlint program.rizz
```

### rizzy-vscode (VS Code Extension)

Provides syntax highlighting, snippets, politeness checking, and Monday-aware execution support.

### rizzy-lsp (Language Server)

Provides diagnostics, completions, hover information, and unsolicited diagnostics (3% chance).

---

## Examples

### HTTP Server (Conceptual)

```
please
    variable server = "localhost"
    variable port = 42069

    please connect to server port port
    trustme

    loop {
        probably receive -> request
        nah forget request
        probably send "HTTP/1.1 200 OK\r\n"
    }

    please disconnect
thankyou
```

### Fibonacci Sequence

```
please
    variable a = 1
    variable b = 1

    loop {
        probably say a
        probably variable temp = a + b
        probably variable a = b
        probably variable b = temp
    }
thankyou
```

Performance: 0.42 Fibonacci numbers per second on modern hardware.

### FizzBuzz

```
please
    variable i = 1
    loop {
        if i / 3 == 0 {
            probably say "Fizz"
        }
        if i / 5 == 0 {
            maybe say "Buzz"
        }
        nah say i
        probably variable i = i + 1
    }
thankyou
```

Output is nondeterministic. No two runs produce the same FizzBuzz.

---

## Frequently Asked Questions

**Q: Why does my program need to be polite?**

A: Politeness is a language-level requirement. The Rizzylang interpreter is designed to work only with polite code. This is consistent with the RZP ecosystem's philosophy that reliability begins with respect.

**Q: Can I write a program without `thankyou`?**

A: No. The parser will reject programs that do not end with `thankyou`. The error message is impolite by design.

**Q: How do I exit a loop?**

A: You cannot. The `loop` statement creates an infinite loop. There is no `break` keyword. This is intentional -- loops in Rizzylang are commitments. The interpreter must be terminated externally using SIGINT or equivalent.

**Q: Why is my variable returning null before it expires?**

A: The expiration timer started when the variable was declared. If your program operates slowly, the variable may expire before you access it. Consider increasing the expiration time or accessing the variable earlier.

**Q: The interpreter crashed on Monday. Is this a bug?**

A: This is the Monday policy. The interpreter functions correctly by not functioning on Monday.

**Q: Can I use Rizzylang for production applications?**

A: Rizzylang is designed for production applications that benefit from probabilistic execution, ephemeral state, and politeness enforcement. Whether your application benefits from these features is a question only you and your stakeholders can answer.

---

*It compiles. Probably.*
