ILMA Docs — Language Reference

Getting Started

ILMA is a programming language designed for children ages 3 and up. It uses plain English keywords, compiles to C, and produces native binaries. Every ILMA program is a plain text file with the .ilma extension.

Hello World

Create a file called hello.ilma and write:

say "Hello, World!"

Run it with:

ilma hello.ilma

Compile to binary

To compile your program into a standalone executable:

ilma build hello.ilma -o hello

ILMA uses indentation (4 spaces) to define code blocks, similar to Python. Tabs are also accepted but spaces are recommended.

Keywords

ILMA uses original English keywords that children can understand. Here is the complete list:

Keyword	Purpose	Equivalent
say	Print output to the screen	print
remember	Declare/assign a variable	let / var
ask	Read input from the user	input
if	Conditional branch	if
otherwise	Else branch	else
otherwise if	Else-if branch	elif / else if
repeat	Loop a fixed number of times	for i in range
while	Loop while condition is true	while
for each	Iterate over a collection	for...in
recipe	Define a function	def / function
give back	Return a value from a function	return
bag	Ordered list/array	list / array
notebook	Key-value collection	dict / map
blueprint	Define a class	class
create	Constructor method	__init__
me	Reference to current instance	self / this
inherits	Class inheritance	extends
try	Begin error handling block	try
when wrong	Catch an error	except / catch
use	Import a module	import
yes	Boolean true	True / true
no	Boolean false	False / false
empty	Null/none value	None / null
and	Logical AND	and / &&
or	Logical OR	or / \|\|
not	Logical NOT	not / !
is	Equality comparison	==
is not	Inequality comparison	!=
stop	Break out of a loop	break
skip	Skip to next iteration	continue

Types

ILMA is dynamically typed. Variables can hold any type and change type during execution.

Numbers

Both integers and decimals are supported. Arithmetic follows standard precedence.

remember age = 10
remember price = 3.99
remember total = price * 5

Text (Strings)

Text is enclosed in double or single quotes. Concatenate with +.

remember greeting = "Salaam"
remember name = "Amira"
say greeting + ", " + name

Booleans

Use yes for true and no for false.

remember is_ready = yes
remember is_done = no

Empty

The empty keyword represents the absence of a value (like null).

remember result = empty

Variables

Variables are declared with remember. Names can contain letters, numbers, and underscores. ILMA supports full Unicode, so Arabic and Urdu variable names work too.

remember score = 100
remember player_name = "Yusuf"
remember is_winner = yes

Reassignment

Once declared, you can update a variable by assigning a new value:

remember count = 0
count = count + 1
say count  # prints 1

Variable names are case-sensitive. Score and score are different variables.

I/O (Input and Output)

Output with say

The say keyword prints a value to the screen, followed by a newline.

say "Hello!"
say 42
say "The answer is: " + 42

Input with ask

The ask keyword prompts the user for input and returns a text value.

remember name = ask "What is your name? "
say "Hello, " + name

The ask keyword always returns text. Use number() to convert it to a number: remember age = number(ask "Age? ")

Control Flow

if / otherwise if / otherwise

Conditional branching uses if, otherwise if, and otherwise. Each block is indented.

remember score = 85

if score >= 90:
    say "Excellent!"
otherwise if score >= 70:
    say "Good job!"
otherwise:
    say "Keep trying!"

Comparison operators

is or == — equality
is not or != — inequality
>, <, >=, <= — numeric comparisons
and, or, not — logical operators

repeat

Run a block a fixed number of times:

repeat 5:
    say "ILMA is fun!"

while

Loop while a condition is true:

remember count = 0
while count < 3:
    say count
    count = count + 1

for each

Iterate over items in a bag or characters in text:

remember colors = bag["red", "green", "blue"]
for each color in colors:
    say color

stop and skip

Use stop to break out of a loop and skip to jump to the next iteration:

repeat 10:
    if i == 5:
        stop
    say i

Functions (Recipes)

Functions are called "recipes" in ILMA. Define them with recipe and return values with give back.

Defining a recipe

recipe greet(name):
    say "Salaam, " + name

greet("Amira")   # prints: Salaam, Amira

Returning values

recipe add(a, b):
    give back a + b

remember sum = add(3, 7)
say sum   # prints: 10

Multiple parameters

recipe calculate_area(width, height):
    give back width * height

say calculate_area(5, 10)   # prints: 50

Recipes must be defined before they are called. ILMA does not hoist function definitions.

Collections

Bags (Lists)

A bag is an ordered collection of items. Create one with bag[...].

remember fruits = bag["apple", "banana", "cherry"]
say fruits[0]       # prints: apple
say fruits.length   # prints: 3

Notebooks (Dictionaries)

A notebook is a collection of key-value pairs. Create one with notebook{...}.

remember student = notebook{"name": "Ali", "age": 12}
say student["name"]   # prints: Ali

Nested collections

remember classroom = bag[
    notebook{"name": "Ali", "grade": "A"},
    notebook{"name": "Sara", "grade": "B"}
]

Blueprints (Classes)

Blueprints define reusable templates for objects. They support constructors, methods, and inheritance.

Basic blueprint

blueprint Animal:
    create(name, sound):
        me.name = name
        me.sound = sound

    recipe speak():
        say me.name + " says " + me.sound

remember cat = Animal("Whiskers", "Meow")
cat.speak()   # prints: Whiskers says Meow

Inheritance

Use inherits to create a blueprint that extends another:

blueprint Cat inherits Animal:
    create(name):
        me.name = name
        me.sound = "Meow"

    recipe purr():
        say me.name + " purrs..."

remember kitty = Cat("Luna")
kitty.speak()   # inherited: Luna says Meow
kitty.purr()    # Luna purrs...

The me keyword inside a blueprint always refers to the current instance, like self in Python or this in JavaScript.

Error Handling

Use try and when wrong to catch and handle errors gracefully.

try:
    remember result = 10 / 0
when wrong error:
    say "Something went wrong: " + error

The when wrong block receives a variable containing the error message. You can name it anything you want.

try:
    remember data = read_file("data.txt")
    say data
when wrong e:
    say "Could not read file"

Modules

ILMA ships with built-in knowledge modules. Import them with use.

use finance
use science

finance

Financial calculations for teaching money management.

use finance

say finance.zakat(10000)           # 250
say finance.compound(1000, 0.05, 10) # compound interest
say finance.profit_margin(50, 80)  # profit margin %

time

Date and calendar operations including Hijri calendar.

use time

say time.today()        # current Gregorian date
say time.hijri_today()  # current Hijri date

quran

Search and read Quran verses.

use quran

say quran.ayah(1, 1)           # Al-Fatiha, verse 1
say quran.search("mercy")      # search for keyword

science

Physics and science formulas.

use science

say science.gravity(10)         # weight from mass
say science.celsius_to_f(100)  # 212
say science.kinetic(5, 10)     # kinetic energy

body

Health and fitness calculations.

use body

say body.bmi(70, 1.75)     # BMI calculation
say body.water(70)         # daily water intake (ml)

trade

Commerce and business calculations.

use trade

say trade.profit(50, 80)    # profit amount
say trade.loss(80, 50)      # loss amount

number

Math functions, number theory, and conversions. See the full Number Module reference.

use number

say number.sqrt(144)        # 12
say number.is_prime(17)     # yes
say number.fibonacci(10)    # 55
say number.to_binary(42)    # "101010"

think

Critical thinking and reflection prompts.

use think

say think.reflect()     # random reflection question
say think.decide(bag["study", "play", "rest"])

draw

SVG canvas, shapes, and Islamic geometric patterns. See the full Draw Module reference.

use draw

remember canvas = draw.canvas(400, 400)
canvas = draw.islamic_star(canvas, 200, 200, 150, 8, "#534AB7")
draw.save(canvas)

String Methods

Text values have built-in methods for manipulation.

remember text = "Hello, World!"

say text.length          # 13
say text.upper()         # "HELLO, WORLD!"
say text.lower()         # "hello, world!"
say text.contains("World") # yes
say text.replace("World", "ILMA") # "Hello, ILMA!"
say text.split(", ")     # bag["Hello", "World!"]
say text.trim()          # removes leading/trailing spaces
say text.starts_with("He") # yes
say text.ends_with("!")  # yes
say text.slice(0, 5)     # "Hello"

String methods do not modify the original string. They return a new string.

Bag Methods

Bags (lists) have built-in methods for adding, removing, and transforming items.

remember items = bag["apple", "banana"]

items.add("cherry")        # append to end
items.remove("banana")     # remove first match
say items.length            # 2
say items.contains("apple") # yes
say items.index_of("apple") # 0

Sorting and reversing

remember nums = bag[3, 1, 4, 1, 5]

say nums.sort()      # bag[1, 1, 3, 4, 5]
say nums.reverse()   # bag[5, 4, 3, 1, 1]
say nums.join(", ") # "3, 1, 4, 1, 5"

Slicing

remember letters = bag["a", "b", "c", "d", "e"]
say letters.slice(1, 3)  # bag["b", "c"]
say letters.first()     # "a"
say letters.last()      # "e"

Most bag methods modify the bag in place. Methods like sort(), reverse(), and slice() return a new bag.

Draw Module

Create SVG graphics and Islamic geometric art.

use draw

Functions

Function	Purpose
canvas(width, height)	Create a new SVG canvas
circle(canvas, cx, cy, r, color)	Draw a circle
rect(canvas, x, y, w, h, color)	Draw a rectangle
line(canvas, x1, y1, x2, y2, color)	Draw a line
text(canvas, x, y, content, color)	Draw text on the canvas
polygon(canvas, points, color)	Draw a polygon from a list of points
islamic_star(canvas, cx, cy, r, points, color)	Draw an Islamic star pattern
save(canvas)	Save the canvas to an SVG file

Example

use draw
remember canvas = draw.canvas(400, 400)
canvas = draw.islamic_star(canvas, 200, 200, 150, 8, "#534AB7")
canvas = draw.circle(canvas, 200, 200, 60, "#0F6E56")
draw.save(canvas)

The draw module produces SVG files. Use islamic_star() to create beautiful geometric patterns commonly found in Islamic art and architecture.

Number Module

Math functions, number theory, and conversions.

use number

Functions

Function	Purpose
sqrt(n)	Square root of n
abs(n)	Absolute value of n
floor(n)	Round down to nearest integer
ceil(n)	Round up to nearest integer
round(n)	Round to nearest integer
power(base, exp)	Raise base to exponent
random()	Random number between 0 and 1
is_prime(n)	Check if n is prime
fibonacci(n)	Get the nth Fibonacci number
to_binary(n)	Convert to binary string
to_hex(n)	Convert to hexadecimal string
pi()	Returns the value of pi
e()	Returns Euler's number

Example

use number
say number.sqrt(144)
say number.is_prime(17)
say number.fibonacci(10)
say number.to_binary(42)

The number module covers everything from basic math to number theory. Use is_prime() and fibonacci() to explore mathematical patterns.

File I/O

Read and write files.

Built-in Functions

Function	Purpose
read_file(path)	Read the contents of a file
write_file(path, content)	Write content to a file
file_exists(path)	Check if a file exists (returns yes/no)

Example

write_file("hello.txt", "Bismillah")
remember content = read_file("hello.txt")
say content
say file_exists("hello.txt")

File I/O functions are built-in and do not require a use statement. Use try / when wrong to handle errors when reading files that may not exist.