🌟 The Petroleum Coding Guide

This guide explains every step in simple words. You’ll learn what each piece of code does and why it behaves that way.

How a Petroleum program runs

▶

When you run a Petroleum file, the language looks for a function named main. If it exists, Petroleum calls it automatically. That’s why you don’t need to explicitly invoke main() yourself (after you've defined it, as you would for regular functions).

You can also call functions at the top level (outside of any function). Those lines run immediately as the file loads. This is handy for tiny scripts. For bigger programs, it’s cleaner to put your work inside main() so there’s one clear starting point.


# Style A: quick script — top-level call runs immediately when the file loads
def say_hello(person_name):
    print("Hello, " + person_name)

say_hello("Ava")   # runs right away


# Style B: structured app — Petroleum auto-calls main() first
def main():
    say_hello("Max")

Think of main() as the front door of your program. The computer walks through it first if it’s present.

Comments, printing, and indentation

▶

Comments are notes to yourself. Petroleum ignores them. Use # at the start of a line or after code.

Printing can show multiple things at once by separating them with commas.

Indentation shows which lines belong together, like inside a function. Petroleum treats indentation like Python does.


def main():
    # This is a comment. It helps you and future you.
    name = "Ava"  # Comments can go after code too
    age = 25
    
    # Print multiple things at once
    print("Name:", name, "Age:", age)
    
    # Keep the window open so you can see the output
    input("Press Enter to exit...")

Variables: giving names to values

▶

A variable is a name that remembers a value. Use clear names.


def main():
    player_name = "Ava"
    total_coins = 25
    print(player_name)
    print(total_coins)

Strings: text values with superpowers

▶

Use single '...', double "...", or triple quotes for multi-line text.

F-strings let you put values right inside text with {...}.


def main():
    name = "Ava"
    age = 25
    
    # Regular strings
    greeting = "Hello"
    question = 'How are you?'
    
    # F-strings - variables go inside {}
    personal_greeting = f"Hello {name}! You are {age} years old."
    
    # Multi-line strings
    poem = """Roses are red,
Violets are blue,
Petroleum is awesome,
And so are you!"""
    
    # Multi-line f-strings work too!
    info = f"""Welcome {name}!
Your age: {age}
Next year: {age + 1}"""
    
    print(personal_greeting)
    print(info)

Numbers and math

▶

Math works like you expect. // is whole-number division, ** is power.


def main():
    apples = 10
    friends = 3
    print(apples + friends)   # 13
    print(apples - friends)   # 7
    print(apples * friends)   # 30
    print(apples // friends)  # 3 (whole division)
    print(apples / friends)   # 3.333...
    print(apples % friends)   # 1 (remainder)
    print(apples ** 2)        # 100 (power)

Getting input: talking with your users

▶

Use input() to ask the user for information. The text you put inside becomes the prompt.

Pro tip: Add input("Press Enter to exit...") at the end of your main() so the window doesn’t close immediately.


def main():
    # Ask the user for their name
    name = input("What's your name? ")
    age = input("How old are you? ")
    
    # Use f-strings to create a personalized message
    message = f"Nice to meet you, {name}! At {age}, you're ready to code!"
    print(message)
    
    # Keep the window open
    input("Press Enter to exit...")

Functions: teaching the computer new tricks

▶

def creates a function. A function can take inputs (parameters) and give back a value with return.

You can call functions:

At the top level — runs as the file loads (good for tiny scripts).
Inside main() — recommended for full programs.


def make_greeting(person_name):
    # F-strings make this much cleaner!
    message = f"Hello, {person_name}! Welcome to Petroleum!"
    return message

# Top-level call (runs on load):
greeting_message = make_greeting("Ava")
print(greeting_message)

# Structured app entry point:
def main():
    name = input("Enter your name: ")
    other_message = make_greeting(name)
    print(other_message)
    input("Press Enter to exit...")

Scope: a variable created inside a function (like message) lives only inside that function.

Pets: friendly background helpers 🐕

▶

A pet runs a function in the background while your program continues. Start one with pet, get the result with await.


def slow_calculation(value):
    # Imagine this takes a long time
    result = value * value * value
    print(f"Calculated {value}^3 = {result}")
    return result

def main():
    print("Starting background calculations...")
    
    # Start two pets working at the same time
    helper_one = pet slow_calculation(5)
    helper_two = pet slow_calculation(10)
    
    print("Both pets are working! Let's wait for results...")
    
    # Get the results when they're done
    result_one = await helper_one
    result_two = await helper_two
    
    print("Results:", result_one, "and", result_two)
    input("Press Enter to exit...")

Use pets when tasks can happen at the same time (like downloading several pages).

Running your programs: the easy way

▶

Use petroleum run to compile and run your program in one step.


# Save this as hello.pet
def main():
    name = input("What's your name? ")
    print(f"Hello {name}! Welcome to Petroleum!")
    input("Press Enter to exit...")

Then in your terminal:


petroleum run hello.pet

Or compile to an executable:


petroleum compile hello.pet
./hello.exe

petroleum run compiles and runs immediately (perfect for testing!). petroleum compile creates an executable file you can share.

Mini-project: Personal Greeting Generator

▶

Combine functions, f-strings, user input, and multiple-argument printing to create a friendly greeting program.


def create_greeting(name, age, hobby):
    # Use f-strings to create a personalized message
    greeting = f"""🌟 Welcome to Petroleum, {name}!
    
At {age} years old, you're at a perfect age to learn programming!
I see you enjoy {hobby} - that's awesome!
    
Petroleum will help you build amazing things. Let's code together!"""
    return greeting

def main():
    # Get information from the user
    print("Let's create a personalized greeting for you!")
    name = input("What's your name? ")
    age = input("How old are you? ")
    hobby = input("What's your favorite hobby? ")
    
    # Create and show the greeting
    personal_message = create_greeting(name, age, hobby)
    print(personal_message)
    
    # Show some info using multiple argument printing
    print("Summary - Name:", name, "Age:", age, "Hobby:", hobby)
    
    input("Press Enter to exit...")

Save this as greeting.pet and run it with petroleum run greeting.pet

You’re ready to build!

Now you know what each piece does and why it works. Start small, have fun, and let your pets help you build amazing things.

Back to Home