chotulang 0.0.7
A custom interpreter for the Chotulang language.
Requires Python: >=3.7

# Chotulang Interpreter

This is the official interpreter for the Chotulang programming language.

## Installation

pip install chotulang

## Basic syntax

==========================================
CHOTULANG DEVELOPMENT GUIDE (Version 2.5.1)
==========================================

Chotulang is a dynamic, Python-compatible language that emphasizes clean, readable syntax and supports powerful functional features like pipes and lambdas.

----------------------------
MODULE 1: CORE FUNDAMENTALS
----------------------------

1. PRINTING AND VARIABLES
Use 'out' to print. Use 'var' to declare a variable.

var name = "Alex"      // String
var count = 5          // Number
var is_active = true   // Boolean

out "Hello,", name, "!"
out "The value is:", count

// User Input
out "Enter a number:"
var user_input = ask() // Reads a line of text
out "You entered:", user_input

2. COMMENTS
Use the '#' symbol for comments.

# This line is ignored by the interpreter

----------------------------
MODULE 2: OPERATOR PRECEDENCE
----------------------------

Understanding the order of operations ensures your calculations are correct.

| Precedence | Operator | Description | Example |
| :--- | :--- | :--- | :--- |
| Highest | () | Parentheses (Forces order) | `(5 + 2) * 3` |
| 2 | ** | Power/Exponent (Right-associative) | `2 ** 3 ** 2` is `2 ** (3 ** 2)` (512) |
| 3 | *, /, % | Multiplication, Division, Modulo | `10 / 2 * 5` (Left-to-right) |
| 4 | +, - | Addition, Subtraction | `3 + 4 - 1` (Left-to-right) |
| 5 | <, >, ==, !=| Comparison | `x > 5` |
| 6 | &&, || | Logical AND, OR | `true && false` |
| Lowest | =, +=, -=, *=, /= | Assignment | `x = 10` |

// Power Operator Example (Exponent)
var result_power = 8 ** 2
out "8 squared is:", result_power // 64

var complex_calc = 10 - 2 ** 3 * 2
// Order: 2**3 (8), then 8*2 (16), then 10-16 (-6)
out "Complex calculation:", complex_calc

----------------------------
MODULE 3: CONTROL FLOW & LOOP JUMPS
----------------------------

1. IF/ELSE STATEMENTS
Conditional execution blocks. The curly braces {} are mandatory.

var temperature = 30

if temperature > 25 {
    out "It is hot."
} else {
    out "It is mild."
}

2. LOOPS (ITERATION)

// The 'do' Loop (Similar to While)
var i = 0
do i < 3 {
    out "Do loop iteration:", i
    i += 1
}

// The 'for' Loop (Iterates over a list or range)
for number in 0..4 {
    out "Current number:", number
}

3. LOOP JUMP STATEMENTS

// WARNING: These must only be used **inside** a 'do' or 'for' loop!

// 'break'
// Stops the current loop entirely and execution continues after the loop.
do true {
    out "Running once..."
    break // Exits the 'do' loop
}

// 'next'
// Skips the rest of the code in the current loop body and starts the next iteration.
for i in 1..5 {
    if i == 3 {
        next // Skip printing 3, go straight to 4
    }
    out "Number:", i
}


----------------------------
MODULE 4: DATA STRUCTURES
----------------------------

1. LISTS (Ordered Collections)

var fruits = ["apple", "banana", "kiwi"]
out fruits[1]          // Access: banana
fruits.append("grape") // Add to end

2. DICTIONARIES (Key-Value Pairs)

var user = {
    "id": 101,
    "status": "online"
}

out user["status"]     // Access: online
user.set("city", "London") // Add/Update a key

----------------------------
MODULE 5: FUNCTIONS AND PIPES
----------------------------

1. STANDARD FUNCTIONS ('fn')
Use 'fn' for reusable code blocks. Use 'ret' to return a value.

fn multiply(x, y) {
    ret x * y
}

var product = multiply(8, 6)
out "Product:", product

2. LAMBDA FUNCTIONS (Anonymous Functions)

// Syntax: fn(params) => expression
var is_even = fn(n) => n % 2 == 0
out is_even(4) // true

3. THE PIPE OPERATOR (`|>`)
Pass the result of one expression as the first argument to the next function.

fn increment(x) { ret x + 1 }
fn double(x) { ret x * 2 }

var value = 10 |> increment |> double // (10 + 1) * 2 = 22
out value

----------------------------
MODULE 6: COMPLEX MATHEMATICAL OPERATIONS
----------------------------

1. USING THE PYTHON MATH LIBRARY
Import the standard Python 'math' module using the 'use' keyword.

use math

// Square Root
var root = math.sqrt(64)
out "Root of 64:", root

// Trigonometry and Constants
var angle = math.radians(45)
var sine_val = math.sin(angle)
out "Sine of 45 deg:", sine_val
out "Pi value:", math.pi // Access constant

2. COMPLEX CALCULATION WITH PIPES

fn area_calc(r) { ret math.pi * r ** 2 } // Using ** for r squared
fn round_2(n) { ret round(n, 2) }

var r = 5
var final_area = r |> area_calc |> round_2 // 5 -> area_calc -> round_2
out "Rounded Area:", final_area

----------------------------
PRACTICE PROJECTS
----------------------------

1. THE GUESSING GAME
Use the 'random' library (`use random`). Generate a random number. Use a 'do' loop and 'if/else' to let the user guess until correct, providing 'Too High' or 'Too Low' hints.

2. MATH & DATA PIPELINE
Create a list of numbers. Use `map` (or a loop) and a lambda to cube every number, then use the pipe operator to feed the resulting list to a function that calculates the sum of all elements.

3. GEOMETRY FUNCTION
Write a function that accepts two numbers (A and B). This function must check if A and B are positive numbers. If they are, it uses the 'math' library to calculate the perimeter of a rectangle (2A + 2B) and returns it. If not, it returns the string "Error: Invalid dimensions".