API Reference

Complete reference guide for SAPL's built-in functions, standard library modules, and APIs.

This reference covers all built-in functions and standard library modules available in SAPL. Use the navigation to quickly find the functions you need.

Built-in Functions

These functions are always available in SAPL without requiring any imports. They provide essential functionality for input/output, type conversion, and basic operations.

Input/Output Functions

አሳይ()

Built-in

Prints values to the console with optional formatting and separators.

Syntax

አሳይ(value1, value2, ..., sep=' ', end='\n')

sapl

Parameters

value1, value2, ... - Values to print
sep - Separator between values (default: space)
end - String appended after the last value (default: newline)

Examples

# Basic printing
አሳይ("Hello, World!")

# Multiple values
አሳይ("Name:", "Alice", "Age:", 25)

# Custom separator
አሳይ("A", "B", "C", sep="-")  # Output: A-B-C

# Custom ending
አሳይ("Loading", end="...")
አሳይ("Done!")  # Output: Loading...Done!

# Printing variables
name = "Bob"
score = 95
አሳይ("Student:", name, "Score:", score)

sapl

ያስገባ()

Built-in

Reads a line of input from the user and returns it as a string.

Syntax

ያስገባ(prompt="")

sapl

Parameters

prompt - Optional message to display to the user

Returns

String containing the user's input (without the trailing newline)

Examples

# Basic input
name = ያስገባ("Enter your name: ")
አሳይ("Hello,", name)

# Input validation
እስከ እውነት:
    age_str = ያስገባ("Enter your age: ")
    ሞክር:
        age = ቁጥር(age_str)
        እንደሆነ age >= 0:
            አቋርጥ
        ካልሆነ:
            አሳይ("Age must be positive!")
    ያዝ ValueError:
        አሳይ("Please enter a valid number!")

አሳይ("Your age is:", age)

sapl

Standard Library Modules

SAPL's standard library provides additional functionality through modules that need to be imported before use. These modules extend the language's capabilities for specific domains.

To use standard library modules, import them using the አስመጣ (import) statement at the beginning of your program.

ሒሳብ (Math) Module

Provides mathematical functions and constants for advanced mathematical operations.

አስመጣ ሒሳብ

sapl

Constants

ሒሳብ.ፓይ

Mathematical constant π (pi) ≈ 3.14159

ሒሳብ.ኢ

Mathematical constant e ≈ 2.71828

ሒሳብ.ታው

Mathematical constant τ (tau) = 2π

Trigonometric Functions

ሒሳብ.ሲን(x)

Sine of x (in radians)

ሒሳብ.ኮስ(x)

Cosine of x (in radians)

ሒሳብ.ታን(x)

Tangent of x (in radians)

Example Usage

አስመጣ ሒሳብ

# Using constants
circle_area = ሒሳብ.ፓይ * radius * radius
አሳይ("Circle area:", circle_area)

# Trigonometric calculations
angle = ሒሳብ.ፓይ / 4  # 45 degrees in radians
አሳይ("sin(45°):", ሒሳብ.ሲን(angle))
አሳይ("cos(45°):", ሒሳብ.ኮስ(angle))
አሳይ("tan(45°):", ሒሳብ.ታን(angle))

# Logarithmic functions
አሳይ("Natural log of e:", ሒሳብ.ሎግ(ሒሳብ.ኢ))
አሳይ("Log base 10 of 100:", ሒሳብ.ሎግ10(100))

# Power and exponential
አሳይ("e^2:", ሒሳብ.ኤክስፕ(2))
አሳይ("2^10:", ሒሳብ.ኃይል(2, 10))

sapl

File I/O Operations

SAPL provides built-in functions for reading from and writing to files, enabling your programs to persist data and interact with the file system.

Opening and Closing Files

# Open file for reading
file = ክፈት("data.txt", "r")
content = file.አንብብ()
file.ዝጋ()

# Open file for writing
file = ክፈት("output.txt", "w")
file.ጻፍ("Hello, World!")
file.ዝጋ()

# Using with statement (recommended)
ከ ክፈት("data.txt", "r") እንደ file:
    content = file.አንብብ()
    አሳይ(content)
# File is automatically closed

sapl

Reading Files

# Read entire file
ከ ክፈት("story.txt", "r") እንደ file:
    content = file.አንብብ()
    አሳይ("File content:", content)

# Read line by line
ከ ክፈት("names.txt", "r") እንደ file:
    ለእያንዳንዱ line_number, line በ enumerate(file.መስመሮች(), 1):
        አሳይ("Line", line_number, ":", line.strip())

# Read specific number of characters
ከ ክፈት("data.txt", "r") እንደ file:
    first_100_chars = file.አንብብ(100)
    አሳይ("First 100 characters:", first_100_chars)

# Read all lines into a list
ከ ክፈት("config.txt", "r") እንደ file:
    lines = file.አንብብ_መስመሮች()
    ለእያንዳንዱ line በ lines:
        አሳይ("Config line:", line.strip())

sapl

Writing Files

# Write string to file
ከ ክፈት("output.txt", "w") እንደ file:
    file.ጻፍ("Hello, SAPL!
")
    file.ጻፍ("This is a new line.
")

# Write multiple lines
lines = ["First line", "Second line", "Third line"]
ከ ክፈት("multi_line.txt", "w") እንደ file:
    ለእያንዳንዱ line በ lines:
        file.ጻፍ(line + "
")

# Append to existing file
ከ ክፈት("log.txt", "a") እንደ file:
    file.ጻፍ("New log entry
")

# Write formatted data
data = [
    {"name": "Alice", "age": 25, "city": "Addis Ababa"},
    {"name": "Bob", "age": 30, "city": "Bahir Dar"}
]

ከ ክፈት("people.txt", "w") እንደ file:
    ለእያንዳንዱ person በ data:
        line = "Name: {}, Age: {}, City: {}
".format(
            person["name"], person["age"], person["city"]
        )
        file.ጻፍ(line)

sapl

File Operations with Error Handling

# Safe file reading
ተግባር read_file_safely(filename):
    ሞክር:
        ከ ክፈት(filename, "r") እንደ file:
            return file.አንብብ()
    ያዝ FileNotFoundError:
        አሳይ("Error: File '{}' not found".format(filename))
        return None
    ያዝ PermissionError:
        አሳይ("Error: Permission denied to read '{}'".format(filename))
        return None
    ያዝ:
        አሳይ("Error: Could not read file '{}'".format(filename))
        return None

# Safe file writing
ተግባር write_file_safely(filename, content):
    ሞክር:
        ከ ክፈት(filename, "w") እንደ file:
            file.ጻፍ(content)
            return እውነት
    ያዝ PermissionError:
        አሳይ("Error: Permission denied to write '{}'".format(filename))
        return ሐሰት
    ያዝ:
        አሳይ("Error: Could not write to file '{}'".format(filename))
        return ሐሰት

# Usage examples
content = read_file_safely("important_data.txt")
እንደሆነ content:
    አሳይ("File content loaded successfully")
    # Process the content
    processed = content.upper()
    
    success = write_file_safely("processed_data.txt", processed)
    እንደሆነ success:
        አሳይ("Processed data saved successfully")
    ካልሆነ:
        አሳይ("Failed to save processed data")

sapl

Best Practice: Always use the ከ...እንደ (with) statement when working with files. It automatically handles closing the file, even if an error occurs.

Version History

Track changes and additions to the SAPL API across different versions.

SAPL 2.1.0

Latest

+Added ፊደል.ኢሜይል_ነው() and ፊደል.ስልክ_ነው() validation functions
+Enhanced ጊዜ module with Ethiopian calendar support
~Improved error messages for type conversion functions
!Fixed issue with ዘፈቀዳዊ.ቀላቅል() not working with strings

SAPL 2.0.0

+Added exception handling with ሞክር/ያዝ/በመጨረሻ
+Introduced ስርዓት module for system operations
+Added file I/O operations with ክፈት() function
~Breaking: Changed loop syntax from ለ to ለእያንዳንዱ

SAPL 1.5.0

+Added ሒሳብ module with trigonometric functions
+Introduced ዘፈቀዳዊ module for random number generation
+Added list comprehension support

Control Flow Examples