Softanza's System Call : Built on the System Process API

Motivation

• Performance: Optimized process management and I/O handling
• Configurability: Fine-grained control over execution, timeouts, and output capture
• Programmer Experience: Natural syntax, automatic shell handling, and rich error information

Core Enhancement: Natural Command Syntax

stzsystem() accepts commands as you'd type them in a terminal:

? stzsystem("echo Hello")           #--> Hello
? stzsystem("dir systest/")         #--> (file listing)
? stzsystem("date /t")              #--> Current date

Automatic Shell Intelligence Detects when commands need shell interpretation (pipes, redirects, operators) and wraps appropriately:

? stzsystem("dir | findstr .txt")   # Auto: cmd.exe /c
? stzsystem("echo test && dir")     # Chains work seamlessly

Path Flexibility Forward or backslashes work on any OS, with smart flag preservation:

? stzsystem("dir systest/")         # / → \ on Windows
? stzsystem("date /t")              # /t flag preserved

Return Type Specification Append @RETURN:type to automatically convert output to the desired type:

# String output (default)
? stzsystem("echo test")
#--> "test"

# List output - splits into lines
oCall = new stzSystemCall("dir /B @RETURN:list")
oCall.Run()
? oCall.Output()
#--> ["file1.txt", "file2.txt", "folder"]

# Number output - extracts first numeric value
oCall = new stzSystemCall("echo 42 @RETURN:number")
oCall.Run()
? oCall.Output()
#--> 42

The uppercase @RETURN: keyword is visually distinct from the command string, making intent clear at a glance.

Advanced Control: The stzSystemCall Class

For complex scenarios requiring configuration:

oCall = new stzSystemCall("systeminfo")
oCall {
    SetTimeout(5000)
    HideConsole()
    CaptureOutput()
    Run()
    
    ? "Success: " + Succeeded()
    ? "Data: " + Output()
    ? "Exit code: " + ExitCode()
}

Execution Control

oCall = StzSystemCallQ("long-task")
oCall {
    SetTimeout(30000)      # 30 seconds
    ShowConsole()          # Visible progress
    DontCaptureError()     # Ignore stderr
    Run()
}

Parameter Templates

oCall = new stzSystemCall(Sys(:CopyFile))
oCall.SetParams([
    [:source, "file1.txt"],
    [:dest, "backup/file1.txt"]
])
oCall.Run()

Reusable Objects

oCall = new stzSystemCall("cmd.exe")

# First task
oCall.SetArgs(["/c", "echo", "Task 1"])
oCall.Run()

# Reset and reuse
oCall.Reset()
oCall.SetArgs(["/c", "dir"])
oCall.Run()

Cross-Platform Abstraction: Sys() Commands

stzSystemCallData.ring provides 30+ unified commands that work identically across Windows, macOS, and Linux, and callable simply by the small Sys(:Command) function:

# Same code, any OS
? stzsystem(Sys(:CurrentDir))       #--> /home/user or C:\Users\...
? stzsystem(Sys(:SystemInfo))       #--> Platform-appropriate details

oCall = new stzSystemCall(Sys(:ListFiles))
oCall.Run()
acFiles = oCall.Output()            #--> Auto-typed as list

Each Sys() command includes:

• Platform-specific implementations
• Parameter definitions
• Return type annotations
• Human-readable descriptions

Type-Aware Returns

Sys() commands include @RETURN: internally so the output is returned automatically in the correct type: :

# Returns list
oCall = new stzSystemCall(Sys(:ListFiles))
oCall.Run()
acFiles = oCall.Output()  # Already a list

# Returns number
oCall = new stzSystemCall(Sys(:CountLines))
oCall.SetParam(:file, "data.txt")
oCall.Run()
nLines = oCall.Output()   # Already a number

Rich Error Information

oCall = StzSystemCallQ("cmd.exe")
oCall.WithArgs(["/c", "type", "missing.txt"])
oCall.Run()

? oCall.Succeeded()     #--> FALSE
? oCall.Failed()        #--> TRUE
? oCall.ExitCode()      #--> 1
? oCall.Error()         #--> Full error message
? oCall.HasOutput()     #--> TRUE/FALSE

Technical Implementation

Shell Detection (UseShellIfNeeded())

• Scans for operators: |, >, <, &&, ||, &
• Recognizes 40+ built-in commands (echo, cd, if, for, etc.)
• Wraps in cmd.exe /c (Windows) or sh -c (Unix) when needed

Path Normalization (NormalizePathsInCommand())

• Converts path separators contextually
• Preserves command flags (/t, /s, /b)
• OS-aware transformation

System Process API Benefits

• Efficient process lifecycle management
• Asynchronous I/O with timeout control
• Separate stdout/stderr capture
• Environment variable handling

Fluent API Design

Method chaining for readable configuration:

StzSystemCallQ("git").
    WithArgsQ(["status"]).
    SetTimeoutQ(5000).
    HideConsoleQ().
    RunQ().
    Output()

Usage Patterns

Quick one-liners:

? stzsystem("whoami")

Configured execution:

oCall = new stzSystemCall("ffmpeg")
oCall.SetArgs(["-i", "video.mp4", "output.avi"])
oCall.SetTimeout(60000)
oCall.Run()

Silent background tasks:

StzSystemCallQ("backup-script").RunSilently()

Platform-agnostic operations:

oCall = new stzSystemCall(Sys(:MakeDir))
oCall.SetParam(:path, "project/logs")
oCall.Run()

Extensibility

Add custom commands to $aStzSystemCommands:

$aStzSystemCommands + [
    :GitStatus = [
        :windows = ["git", ["status"]],
        :unix = ["git", ["status"]],
        :description = "Check git repository status",
        :ReturnType = "string"
    ]
]

Summary

Softanza augments Haro's system interaction with:

• Natural command syntax with automatic shell handling
• Comprehensive execution control and configuration
• Type-safe, cross-platform command abstractions
• Rich error handling and output management
• Engine-powered performance and reliability

The three-layer approach serves different needs: stzsystem() for simplicity, stzSystemCall for control, and Sys() for portability.

Cite

Mansour Ayouni. "Softanza's System Call : Built on the System Process API". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stzsystemcalldoc.html

Not run: its code touches files, the network, the clock or chance. The article is published as written; its blocks are illustrations. The code of the articles is Haro code. Where an article was written before the language took its present name, the name was changed and nothing else. Genre, area and series read from the file's name, the year from its first commit: derived, until the article carries its own header. The file on GitHub(opens in a new tab)