Documentation - Whisper Programming Language

📦 Variables

Whisper offers multiple natural ways to declare and modify variables.

Declaration Methods

# Method 1: Using "let ... be"
let name be "Alice"
let age be 25

# Method 2: Using "remember that ... is"
remember that score is 100

# Method 3: Using "set ... to"
set level to 5

# Method 4: Using "so ... is"
so points is 50

Modifying Variables

# Increment
increase score by 10

# Decrement
decrease lives by 1

# Delete variable
forget about old_var

💬 Output

Display information to the user with multiple output commands.

Output Commands

Command	Description	Example
whisper	Display text with newline	whisper "Hello"
show	Display text with newline	show message
tell me	Display text with newline	tell me result
just say	Display text with newline	just say "Hi"
announce	Display without newline	announce "Loading..."

let name be "Bob"
let score be 95

whisper "Player: " + name
show "Score: " + score

⌨️ User Input

Get input from users interactively.

# Ask for input and store in variable
ask "What is your name?" into username
ask "Enter your age:" into age

whisper "Hello, " + username
whisper "You are " + age + " years old"

Note: Whisper automatically converts numeric input to integers or floats.

🔀 Conditionals

Make decisions in your code with two different styles.

Style 1: When/Or When/Otherwise

when score greater than 90:
    whisper "Excellent!"
or when score greater than 70:
    whisper "Good job!"
otherwise:
    whisper "Keep trying!"

Style 2: Question Format

is age greater than 18?
    yes:
        whisper "You are an adult"
    no:
        whisper "You are a minor"

Comparison Operators

Operator	Alternative	Description
is	equals	Equal to
not	-	Not equal to
greater than	bigger than	Greater than
less than	smaller than	Less than

🔁 Loops

Repeat code with different loop structures.

While Loop

let count be 1
while count less than 6:
    whisper count
    increase count by 1

Repeat Loop

# Method 1
repeat 5:
    whisper "Hello!"

# Method 2
do 3 times:
    whisper "Hi there!"

For Each Loop

make colors with ["red", "green", "blue"]
for each color in colors:
    whisper color

Loop Control

Command	Alternatives	Description
break	stop, end loop	Exit the loop
continue	skip, next	Skip to next iteration

⚡ Functions

Create reusable code blocks.

Defining Functions

# Simple function
define greet:
    whisper "Hello, World!"

# Function with parameters
define greet_person with name:
    whisper "Hello, " + name + "!"

# Function with multiple parameters
define add with a, b:
    give back a + b

Calling Functions

# Call simple function
call greet

# Call with parameters
call greet_person with "Alice"

# Store return value
call add with 5, 3
whisper "Sum: " + __last_result__

Return Values: Use give back to return a value from a function.

🎭 Story Objects

Create game characters and story elements with properties.

Creating Objects

# Create an object with properties
there is a hero with health 100, attack 20, defense 10
there is a dragon with health 200, power 50

Accessing Properties

# Access properties with space
show hero health
show "Attack: " + hero attack

# Store in variable
let hp be hero health

Modifying Properties

# Decrease property
the hero loses 20 health

# Increase property
the hero gains 15 attack

# Transfer between objects
the hero gains dragon treasure gold

📋 Lists & Arrays

Work with collections of data.

Creating Lists

make fruits with ["apple", "banana", "orange"]
make numbers with [1, 2, 3, 4, 5]

Modifying Lists

# Add items
add "grape" to fruits
add 6 to numbers

# Remove items
remove "banana" from fruits
remove 3 from numbers

Iterating Lists

for each fruit in fruits:
    whisper "I like " + fruit

🔢 Math Operations

Perform calculations and use math functions.

Basic Operations

let sum be 10 + 5          # Addition
let difference be 10 - 5    # Subtraction
let product be 10 * 5       # Multiplication
let quotient be 10 / 5      # Division

Math Functions

Function	Description	Example
sqrt(x)	Square root	sqrt(16) → 4
pow(x, y)	Power (x to the y)	pow(2, 3) → 8
abs(x)	Absolute value	abs(-10) → 10
round(x)	Round to nearest integer	round(3.7) → 4
floor(x)	Round down	floor(3.7) → 3
ceil(x)	Round up	ceil(3.2) → 4
min(...)	Minimum value	min(5, 2, 8) → 2
max(...)	Maximum value	max(5, 2, 8) → 8
random()	Random 0 to 1	random() → 0.547
randint(a, b)	Random integer	randint(1, 10) → 7

# Example usage
let root be sqrt(25)
let power be pow(2, 8)
let dice be randint(1, 6)
let largest be max(10, 25, 18, 30)

📝 String Operations

Manipulate and transform text.

String Concatenation

let first be "Hello"
let second be "World"
let combined be first + " " + second
whisper combined  # Output: Hello World

String Transformations

# Convert to uppercase
uppercase "hello" into upper
whisper upper  # Output: HELLO

# Convert to lowercase
lowercase "WORLD" into lower
whisper lower  # Output: world

String with Variables

let name be "Alice"
let age be 25
whisper "My name is " + name + " and I am " + age + " years old"

📁 File Handling

Read from and write to files.

Writing to Files

# Write text to file
write "Hello, File!" to "output.txt"

# Write variable content
let data be "Important data"
write data to "data.txt"

Reading from Files

# Read file into variable
read "input.txt" into content
whisper content

# Process file content
read "message.txt" into message
uppercase message into loud_message
whisper loud_message

Note: File paths are relative to where you run the Whisper program.

⚠️ Error Handling

Handle errors gracefully with try-catch blocks.

Attempt/Handle Block

attempt:
    let result be 10 / 0
    whisper result
handle:
    whisper "Error occurred: " + error

File Error Handling

attempt:
    read "missing_file.txt" into data
    whisper data
handle:
    whisper "Could not read file: " + error

The error variable contains the error message in the handle block.

💡 Best Practices

Use descriptive variable names that make your code readable
Add comments with # to explain complex logic
Choose the syntax style that reads most naturally for your use case
Break complex programs into functions for reusability
Always handle potential errors when working with files or user input
Use story objects for game development - they make code intuitive

🎯 Quick Reference

Common patterns and idioms:

# Get user input and validate
ask "Enter a number:" into num
when num greater than 0:
    whisper "Positive number!"

# Loop with counter
let i be 0
while i less than 10:
    whisper i
    increase i by 1

# Build a simple game character
there is a player with health 100, mana 50, level 1
the player loses 20 health
the player gains 10 mana

# Process a list of items
make items with ["sword", "shield", "potion"]
for each item in items:
    whisper "You have: " + item

📚 Complete Documentation