system_library.md

System Library & Interop

The sys namespace provides essential system operations including I/O, time, process control, and foreign function interface capabilities.

Basic I/O

• sys::Print(msg: String): Void - Prints a string to standard output
• sys::PrintLine(msg: String): Void - Prints a string followed by a newline
• sys::ReadLine(): String - Reads a line from standard input, returns null on EOF
• sys::ReadChar(): Char - Reads a single character from standard input, returns null on EOF

Time and Date Operations

Unix Time Functions

• sys::UnixTime(): Int - Returns current Unix timestamp (seconds since epoch)
• sys::UnixTimeMs(): Int - Returns current Unix timestamp in milliseconds
• sys::UnixTimeNs(): Int - Returns current Unix timestamp in nanoseconds
• sys::NanoTime(): Int - Returns high-resolution monotonic time in nanoseconds

Date/Time Formatting

• sys::FormatDateTime(timestamp: Int, format: String): String - Formats Unix timestamp using format string
• sys::ParseDateTime(dateString: String, format: String): Int - Parses date string to Unix timestamp

Common Format Specifiers

• %Y - 4-digit year (e.g., 2024)
• %m - Month (01-12)
• %d - Day of month (01-31)
• %H - Hour (00-23)
• %M - Minute (00-59)
• %S - Second (00-59)
• %s - Unix timestamp

File Operations

File System Operations

• sys::FileExists(path: String): bool - Checks if file exists
• sys::DirectoryExists(path: String): bool - Checks if directory exists
• sys::CreateDirectory(path: String): bool - Creates directory, returns false on error
• sys::DeleteFile(path: String): bool - Deletes file, returns false on error
• sys::DeleteDirectory(path: String): bool - Deletes empty directory, returns false on error
• sys::MoveFile(source: String, destination: String): bool - Moves/renames file
• sys::CopyFile(source: String, destination: String): bool - Copies file

Directory Operations

• sys::ListDirectory(path: String): StringArray? - Lists directory contents, returns null on error
• sys::GetCurrentDirectory(): String? - Returns current working directory
• sys::ChangeDirectory(path: String): bool - Changes current directory, returns false on error
• sys::GetAbsolutePath(path: String): String? - Returns absolute path, or null on error

Process Control

• sys::Sleep(ms: Int): Void - Sleeps for specified milliseconds
• sys::SleepNs(ns: Int): Void - Sleeps for specified nanoseconds
• sys::Exit(code: Int): Never - Terminates the process with exit code
• sys::GetProcessId(): Int - Returns current process ID
• sys::GetEnvironmentVariable(name: String): String? - Gets environment variable value
• sys::SetEnvironmentVariable(name: String, value: String): bool - Sets environment variable

Random Number Generation

• sys::Random(): Int - Returns random 64-bit integer
• sys::RandomRange(min: Int, max: Int): Int - Returns random integer in range [min, max)
• sys::RandomFloat(): Float - Returns random float in range [0.0, 1.0)
• sys::RandomFloatRange(min: Float, max: Float): Float - Returns random float in range [min, max)
• sys::SeedRandom(seed: Int): Void - Seeds the random number generator

Memory and Performance

• sys::GetMemoryUsage(): Int - Returns current memory usage in bytes
• sys::GetPeakMemoryUsage(): Int - Returns peak memory usage in bytes
• sys::ForceGarbageCollection(): Void - Forces garbage collection
• sys::GetProcessorCount(): Int - Returns number of available CPU cores

System Information

• sys::GetOsName(): String - Returns operating system name
• sys::GetOsVersion(): String - Returns operating system version
• sys::GetArchitecture(): String - Returns CPU architecture (e.g., "x64", "arm64")
• sys::GetUserName(): String - Returns current username
• sys::GetHomeDirectory(): String - Returns user's home directory

Foreign Function Interface (FFI)

• sys::Interope(dllName: String, functionName: String, input: ByteArray, output: ByteArray): Int
  • All interop calls are unsafe.
  • Returns 0 on success, non-zero error code on failure
  • input contains parameters to pass to the function
  • output buffer receives the function's return value

Usage Examples

Date/Time Operations

// Get current time in different formats
val unixTime: Int = sys::UnixTime()
val unixTimeMs: Int = sys::UnixTimeMs()
val unixTimeNs: Int = sys::UnixTimeNs()

// Format current time
val formatted: String? = sys::FormatDateTime(unixTime, "%Y-%m-%d %H:%M:%S")
if (formatted != null) {
    sys::PrintLine("Current time: " + formatted)
}

// High-precision timing
val start: Int = sys::NanoTime()
// ... do some work ...
val end: Int = sys::NanoTime()
val duration: Int = end - start
sys::PrintLine("Operation took " + duration.ToString() + " nanoseconds")

File Operations

val path : String = "TEMP_OVUM_FILE.txt"
val copyPath : String = "COPY_TEMP_OVUM_FILE.txt"
val content : String = "quidquid id est, timeo Danaos et dona ferentes."
val contentBytes : ByteArray = content.ToUtf8Bytes()
contentBytes.RemoveAt(-1) // circular indexing

var file : File = File()
file.Open(path, "w")
file.WriteLine(content)
file.Close()

var readFile : File = File()
readFile.Open(path, "r")
val extractedContent : String = readFile.ReadLine()
readFile.Close()
sys::PrintLine(extractedContent)

sys::CopyFile(path, copyPath)

var copyFile : File = File()
copyFile.Open(path, "r")
var extractedBytes : ByteArray = copyFile.Read(content.Length())
copyFile.Close()

System Information

// Get system information
sys::PrintLine("OS: " + sys::GetOsName() + " " + sys::GetOsVersion())
sys::PrintLine("Architecture: " + sys::GetArchitecture())
sys::PrintLine("CPU cores: " + sys::GetProcessorCount().ToString())
sys::PrintLine("Memory usage: " + sys::GetMemoryUsage().ToString() + " bytes")

// Environment variables
val path: String? = sys::GetEnvironmentVariable("PATH")
if (path != null) {
    sys::PrintLine("PATH: " + path)
}

Note: All function names use PascalCase (e.g., Print, UnixTime, OpenFile). The namespace remains sys.