wren/manual_src/pages/api/os.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "os" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "os"}] %}
{% set prev_page = {"url": "api/crypto.html", "title": "crypto"} %}
{% set next_page = {"url": "api/env.html", "title": "env"} %}

{% block article %}
                <h1>os</h1>

                <p>The <code>os</code> module provides information about the operating system, platform, and current process.</p>

                <pre><code>import "os" for Platform, Process</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#platform-class">Platform Class</a></li>
                        <li><a href="#process-class">Process Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="platform-class">Platform Class</h2>

                <div class="class-header">
                    <h3>Platform</h3>
                    <p>Operating system and platform information</p>
                </div>

                <h3>Static Properties</h3>

                <div class="method-signature">
                    <span class="method-name">Platform.name</span> &#8594; <span class="type">String</span>
                </div>
                <p>The name of the operating system (e.g., "Linux", "macOS", "Windows", "FreeBSD").</p>
                <pre><code>System.print(Platform.name)  // Linux</code></pre>

                <div class="method-signature">
                    <span class="method-name">Platform.isPosix</span> &#8594; <span class="type">Bool</span>
                </div>
                <p>True if running on a POSIX-compatible system (Linux, macOS, BSD, etc.).</p>
                <pre><code>if (Platform.isPosix) {
    System.print("Running on a POSIX system")
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">Platform.isWindows</span> &#8594; <span class="type">Bool</span>
                </div>
                <p>True if running on Windows.</p>
                <pre><code>if (Platform.isWindows) {
    System.print("Running on Windows")
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">Platform.homePath</span> &#8594; <span class="type">String</span>
                </div>
                <p>The current user's home directory path.</p>
                <pre><code>System.print(Platform.homePath)  // /home/alice (Linux) or C:\Users\alice (Windows)</code></pre>

                <h2 id="process-class">Process Class</h2>

                <div class="class-header">
                    <h3>Process</h3>
                    <p>Current process information and arguments</p>
                </div>

                <h3>Static Properties</h3>

                <div class="method-signature">
                    <span class="method-name">Process.arguments</span> &#8594; <span class="type">List</span>
                </div>
                <p>Command-line arguments passed to the script (excludes the interpreter and script path).</p>
                <pre><code>// Running: wren_cli script.wren arg1 arg2
System.print(Process.arguments)  // [arg1, arg2]</code></pre>

                <div class="method-signature">
                    <span class="method-name">Process.allArguments</span> &#8594; <span class="type">List</span>
                </div>
                <p>All command-line arguments including the interpreter path and script path.</p>
                <pre><code>// Running: wren_cli script.wren arg1 arg2
System.print(Process.allArguments)  // [wren_cli, script.wren, arg1, arg2]</code></pre>

                <div class="method-signature">
                    <span class="method-name">Process.cwd</span> &#8594; <span class="type">String</span>
                </div>
                <p>The current working directory.</p>
                <pre><code>System.print(Process.cwd)  // /home/alice/projects</code></pre>

                <div class="method-signature">
                    <span class="method-name">Process.pid</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The process ID of the current process.</p>
                <pre><code>System.print(Process.pid)  // 12345</code></pre>

                <div class="method-signature">
                    <span class="method-name">Process.ppid</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The parent process ID.</p>
                <pre><code>System.print(Process.ppid)  // 12300</code></pre>

                <div class="method-signature">
                    <span class="method-name">Process.version</span> &#8594; <span class="type">String</span>
                </div>
                <p>The version string of the Wren-CLI runtime.</p>
                <pre><code>System.print(Process.version)  // 0.4.0</code></pre>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Process.exit</span>(<span class="param">code</span>)
                </div>
                <p>Terminates the process with the specified exit code.</p>
                <ul class="param-list">
                    <li><span class="param-name">code</span> <span class="param-type">(Num)</span> - Exit code (0 for success, non-zero for error)</li>
                </ul>
                <pre><code>if (hasError) {
    Process.exit(1)
}
Process.exit(0)</code></pre>

                <h2 id="examples">Examples</h2>

                <h3>Platform-Specific Behavior</h3>
                <pre><code>import "os" for Platform

var configPath
if (Platform.isWindows) {
    configPath = Platform.homePath + "\\AppData\\Local\\myapp\\config.json"
} else {
    configPath = Platform.homePath + "/.config/myapp/config.json"
}

System.print("Config path: %(configPath)")</code></pre>

                <h3>Processing Command-Line Arguments</h3>
                <pre><code>import "os" for Process

var args = Process.arguments

if (args.count == 0) {
    System.print("Usage: script.wren <command> [options]")
} else {
    var command = args[0]
    if (command == "help") {
        System.print("Available commands: help, version, run")
    } else if (command == "version") {
        System.print("Version 1.0.0")
    } else if (command == "run") {
        if (args.count > 1) {
            System.print("Running: %(args[1])")
        } else {
            System.print("Error: run requires a file argument")
        }
    } else {
        System.print("Unknown command: %(command)")
    }
}</code></pre>

                <h3>Script Information</h3>
                <pre><code>import "os" for Platform, Process

System.print("=== System Information ===")
System.print("Platform: %(Platform.name)")
System.print("POSIX: %(Platform.isPosix)")
System.print("Home: %(Platform.homePath)")
System.print("")
System.print("=== Process Information ===")
System.print("PID: %(Process.pid)")
System.print("Parent PID: %(Process.ppid)")
System.print("Working Directory: %(Process.cwd)")
System.print("Wren Version: %(Process.version)")
System.print("")
System.print("=== Arguments ===")
System.print("Arguments: %(Process.arguments)")</code></pre>

                <h3>Building File Paths</h3>
                <pre><code>import "os" for Platform, Process

var separator = Platform.isWindows ? "\\" : "/"

var dataDir = Process.cwd + separator + "data"
var configFile = Platform.homePath + separator + ".myapprc"

System.print("Data directory: %(dataDir)")
System.print("Config file: %(configFile)")</code></pre>

                <h3>Argument Parsing with Flags</h3>
                <pre><code>import "os" for Process

var verbose = false
var outputFile = "output.txt"
var inputFiles = []

var i = 0
var args = Process.arguments
while (i < args.count) {
    var arg = args[i]
    if (arg == "-v" || arg == "--verbose") {
        verbose = true
    } else if (arg == "-o" || arg == "--output") {
        i = i + 1
        if (i < args.count) {
            outputFile = args[i]
        }
    } else if (!arg.startsWith("-")) {
        inputFiles.add(arg)
    }
    i = i + 1
}

System.print("Verbose: %(verbose)")
System.print("Output: %(outputFile)")
System.print("Input files: %(inputFiles)")</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p><code>Process.arguments</code> returns only the user's arguments (after the script path), while <code>Process.allArguments</code> includes the full command line including the interpreter.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>Use <code>Platform.isPosix</code> to write cross-platform code that handles path separators, shell commands, and other platform-specific differences.</p>
                </div>
{% endblock %}