oraset/README.en_us.md

Oraset Programming Language

Oraset is a simple cross-platform programming language implemented in Python, supporting both Windows and Linux systems.

Features

• Cross-platform operation (Windows and Linux)
• Simple and easy-to-understand syntax
• Support for variable definition and assignment
• Support for expression evaluation (arithmetic, comparison, logical)
• Support for conditional statements (if, else if, else)
• Support for loop statements (while)
• Support for function definition and call
• Support for class definition
• Support for output functionality
• Support for comments

Quick Start

Runtime Environment

• Python 3.6+

How to Run

# Run .oas or .oraset file
python oraset.py <filename.oas|.oraset>

# Pack .oas or .oraset file into .osp file
python oraset.py pack <filename.oas|.oraset>

# Run .osp file
python oraset.py -osp <filename.osp>

Example

Create a file named hello.oas with the following content:

!! Output Hello, Oraset!
show(`Hello, Oraset!`);

!! Variable definition and calculation
x = 10;
y = 20;
sum = x + y;
show(`10 + 20 = `, sum);

!! Conditional statement
if (sum > 25) {
    show(`Sum is greater than 25`);
} else {
    show(`Sum is less than or equal to 25`);
}

!! Loop statement
i = 0;
while (i < 5) {
    show(`i = `, i);
    i = i + 1;
}

!! Function definition
def add(a, b) {
    return a + b;
}

!! Function call
result = add(5, 6);
show(`5 + 6 = `, result);

!! Class definition
class Calculator {
    def multiply(a, b) {
        return a * b;
    }
}

Run:

python oraset.py hello.oas

Syntax Guide

Comments

Use !! to start a single-line comment:

!! This is a comment

Use !* and *! to enclose multi-line comments:

!* This is a
multi-line comment *!

Built-in Library Functions

Oraset provides the following built-in library functions:

Math Functions

Function	Description	Example
abs(x)	Returns the absolute value of x	abs(-10) → 10
max(x, y)	Returns the maximum of x and y	max(10, 20) → 20
min(x, y)	Returns the minimum of x and y	min(10, 20) → 10
pow(x, y)	Returns x raised to the power of y	pow(2, 3) → 8
sqrt(x)	Returns the square root of x (integer part)	sqrt(16) → 4

String Functions

Function	Description	Example
len(s)	Returns the length of string s	len("Hello") → 5
upper(s)	Converts string s to uppercase	upper("Hello") → HELLO
lower(s)	Converts string s to lowercase	lower("HELLO") → hello
substring(s, start, end)	Returns the substring of s from start to end	substring("Hello", 0, 3) → Hel
startsWith(s, prefix)	Checks if string s starts with prefix	startsWith("Hello", "He") → 1
endsWith(s, suffix)	Checks if string s ends with suffix	endsWith("Hello", "lo") → 1
replace(s, old, new)	Replaces old with new in string s	replace("Hello", "He", "Hi") → Hiello
split(s, sep)	Splits string s by separator sep	split("a,b,c", ",") → ["a", "b", "c"]
trim(s)	Removes whitespace from both ends of string s	trim(" Hello ") → Hello

Array Functions

Function	Description	Example
array(...items)	Creates an array with the specified elements	array("a", "b", "c") → ["a", "b", "c"]
push(arr, item)	Adds an element to the array	push(["a", "b"], "c") → ["a", "b", "c"]
pop(arr)	Removes the last element from the array	pop(["a", "b", "c"]) → ["a", "b"]
indexOf(arr, item)	Returns the index of item in array arr, or -1 if not found	indexOf(["a", "b", "c"], "b") → 1

Type Check Functions

Function	Description	Example
is_number(x)	Checks if x is a number	is_number("123") → 1
is_string(x)	Checks if x is a string	is_string("Hello") → 1

Other Functions

Function	Description	Example
input(prompt)	Gets input from the user	input("Enter a value: ")
int(s)	Converts string s to an integer	int("123") → 123
str(x)	Converts x to a string	str(123) → "123"

File Operation Functions

Function	Description	Example
file_read(filename)	Reads file content	file_read("test.txt")
file_write(filename, content)	Writes content to file	file_write("test.txt", "Hello")
file_exists(filename)	Checks if file exists	file_exists("test.txt") → 1 (exists) or 0 (does not exist)

Time Functions

Function	Description	Example
time_now()	Gets current timestamp	time_now()
time_sleep(seconds)	Sleeps for specified seconds	time_sleep(2)

Random Functions

Function	Description	Example
random_int(min, max)	Generates random integer between min and max	random_int(1, 100)
random_float()	Generates random float between 0 and 1	random_float()

System Functions

Function	Description	Example
system(command)	Executes system command	system("dir")
get_env(var_name)	Gets environment variable	get_env("PATH")

Math Module

Note: Using math functions requires importing the math module first

import math

Function	Description	Example
abs(x)	Returns the absolute value of x	abs(-10) → 10.0
max(x, y)	Returns the maximum of x and y	max(10, 20) → 20.0
min(x, y)	Returns the minimum of x and y	min(10, 20) → 10.0
pow(x, y)	Returns x raised to the power of y	pow(2, 3) → 8.0
sqrt(x)	Returns the square root of x	sqrt(16) → 4.0
sin(x)	Returns the sine of x (in degrees)	sin(90) → 1.0
cos(x)	Returns the cosine of x (in degrees)	cos(0) → 1.0
tan(x)	Returns the tangent of x (in degrees)	tan(45) → 1.0
asin(x)	Returns the arcsine of x (in degrees)	asin(1) → 90.0
acos(x)	Returns the arccosine of x (in degrees)	acos(1) → 0.0
atan(x)	Returns the arctangent of x (in degrees)	atan(1) → 45.0
pi()	Returns the value of pi	pi() → 3.141592653589793
e()	Returns the value of e	e() → 2.718281828459045

Network Request Functions

Note: Using network request functions requires importing the http module first

import http

Function	Description	Example
http_get(url)	Sends an HTTP GET request and returns the response	http_get("http://example.com")
http_post(url, data)	Sends an HTTP POST request and returns the response	http_post("http://httpbin.org/post", "{\"name\": \"Oraset\", \"version\": \"1.0\"}")

Plugin System

Oraset supports user-defined plugins. You can place your extension functions in the includes folder.

Creating a Plugin

1. Create a file with .oraset extension in the includes folder
2. Define functions, classes, etc. in the file
3. Load the plugin using import plugin_name directive

Example

Create includes/math_utils.oraset file:

!! Math utilities plugin

def add(a, b) {
    return a + b;
}

def subtract(a, b) {
    return a - b;
}

Use it in your code:

import math_utils

result = add(10, 20);
show(`10 + 20 = `, result);

Variables

Variable definition and assignment:

x = 10;  // Integer
message = `Hello`;  // String

Data Types

• Integers: 10, 20, 30
• Strings: `Hello`, `World`

Strings support the following escape sequences:

Escape Sequence	Description
\n	Newline
\t	Tab
\r	Carriage return
\\	Backslash
\`	Backtick

Examples:

// Output multi-line text
show(`Line 1\nLine 2`);

// Output text with tabs
show(`Column 1\tColumn 2`);

// Output text with backslashes
show(`Path: C:\\Users\\Name`);

Operators

Arithmetic Operators

• +：Addition
• -：Subtraction
• *：Multiplication
• /：Division (integer division)

Comparison Operators

• ==：Equal to
• !=：Not equal to
• <：Less than
• <=：Less than or equal to
• >：Greater than
• >=：Greater than or equal to

Logical Operators

• &&：Logical AND
• ||：Logical OR

Assignment Operators

• =：Assignment
• +=：Add assignment
• -=：Subtract assignment
• *=：Multiply assignment
• /=：Divide assignment

Conditional Statements

if (condition) {
    // Code block
} else if (condition) {
    // Code block
} else {
    // Code block
}

Loop Statements

while (condition) {
    // Code block
}

Function Definition

def function_name(parameter1, parameter2, ...) {
    // Code block
    return value;
}

Function Call

result = function_name(arg1, arg2, ...);

Class Definition

class ClassName {
    def method_name(parameter1, parameter2, ...) {
        // Code block
        return value;
    }
}

Output

Use the show function to output content:

show(`Hello`);
show(`The value is `, x);

Example Code

Basic Example

// Variables and expressions
x = 10;
y = 20;
sum = x + y;
show(`Sum: `, sum);

// Conditional statements
if (sum > 25) {
    show(`Sum is greater than 25`);
} else if (sum == 25) {
    show(`Sum is exactly 25`);
} else {
    show(`Sum is less than 25`);
}

// Loop statements
i = 0;
while (i < 5) {
    show(`i = `, i);
    i += 1;
}

Function Example

// Function definition
def add(a, b) {
    return a + b;
}

def multiply(a, b) {
    return a * b;
}

// Function call
result1 = add(10, 20);
result2 = multiply(5, 6);
show(`10 + 20 = `, result1);
show(`5 * 6 = `, result2);

// Recursive function
def factorial(n) {
    if (n == 0 || n == 1) {
        return 1;
    }
    return n * factorial(n - 1);
}

result = factorial(5);
show(`Factorial of 5 is `, result);

Class Example

// Class definition
class Calculator {
    def add(a, b) {
        return a + b;
    }
    
    def subtract(a, b) {
        return a - b;
    }
    
    def multiply(a, b) {
        return a * b;
    }
    
    def divide(a, b) {
        return a / b;
    }
}

// Note: Class method calls need to be implemented through functions
// In the current version, class definitions are stored but not directly instantiated

Project Structure

Oraset/
├── oraset.py          # Core interpreter
├── examples/          # Example code
│   ├── hello.oas      # Basic example
│   ├── hello.osp      # Packed basic example
│   ├── functions.oas  # Function example
│   └── classes.oas    # Class example
├── README.md          # This tutorial (Chinese)
└── README.en_us.md    # This tutorial (English)

.osp File Description

.osp files are the packed file format for Oraset, generated by compressing and encoding .oas files. They have the following features:

• Encryption: .osp files use base64 encoding and zlib compression, making the source code not easily viewable directly
• Cross-platform: .osp files can be run directly on both Windows and Linux systems
• Convenience: .osp files are standalone files that can be easily distributed and used

Packing .oas Files

Use the pack command to pack .oas files into .osp files:

python oraset.py pack <filename.oas>

This will generate a file with the same name as the .oas file but with the .osp extension.

Running .osp Files

Use the -osp parameter to run .osp files:

python oraset.py -osp <filename.osp>

This will automatically decompress and execute the code in the .osp file.

Development Notes

Oraset is implemented in Python and mainly consists of the following components:

• Lexer: Lexical analyzer, responsible for converting source code into tokens
• Parser: Syntax analyzer, responsible for building abstract syntax tree (AST)
• Interpreter: Interpreter, responsible for executing AST and generating results

Future Plans

• Support more data types (floating-point numbers, booleans, etc.)
• Improve class instantiation and method calls
• Support module import
• Add standard library
• Optimize performance

License

GNU General Public License v3.0