wren/manual_src/pages/api/io.html

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

{% set page_title = "io" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "io"}] %}
{% set prev_page = {"url": "api/timer.html", "title": "timer"} %}
{% set next_page = {"url": "api/pathlib.html", "title": "pathlib"} %}

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

                <p>The <code>io</code> module provides file and directory operations, as well as stdin/stdout handling.</p>

                <pre><code>import "io" for File, Directory, Stdin, Stdout, Stat</code></pre>

                <h2>File Class</h2>

                <div class="class-header">
                    <h3>File</h3>
                    <p>File operations</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">File.read</span>(<span class="param">path</span>) → <span class="type">String</span>
                </div>
                <p>Reads the entire contents of a file.</p>
                <pre><code>var content = File.read("config.txt")
System.print(content)</code></pre>

                <div class="method-signature">
                    <span class="method-name">File.write</span>(<span class="param">path</span>, <span class="param">content</span>)
                </div>
                <p>Writes content to a file (creates or overwrites).</p>
                <pre><code>File.write("output.txt", "Hello, World!")</code></pre>

                <div class="method-signature">
                    <span class="method-name">File.exists</span>(<span class="param">path</span>) → <span class="type">Bool</span>
                </div>
                <p>Returns true if the file exists.</p>
                <pre><code>if (File.exists("config.txt")) {
    System.print("Config found")
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">File.delete</span>(<span class="param">path</span>)
                </div>
                <p>Deletes a file.</p>

                <div class="method-signature">
                    <span class="method-name">File.size</span>(<span class="param">path</span>) → <span class="type">Num</span>
                </div>
                <p>Returns the size of a file in bytes.</p>

                <div class="method-signature">
                    <span class="method-name">File.copy</span>(<span class="param">source</span>, <span class="param">dest</span>)
                </div>
                <p>Copies a file from source to destination.</p>

                <div class="method-signature">
                    <span class="method-name">File.rename</span>(<span class="param">oldPath</span>, <span class="param">newPath</span>)
                </div>
                <p>Renames a file within the same filesystem.</p>

                <div class="method-signature">
                    <span class="method-name">File.move</span>(<span class="param">source</span>, <span class="param">dest</span>)
                </div>
                <p>Moves a file from source to destination. Uses libuv's async rename operation.</p>
                <pre><code>File.move("old/location/file.txt", "new/location/file.txt")</code></pre>

                <h2>Directory Class</h2>

                <div class="class-header">
                    <h3>Directory</h3>
                    <p>Directory operations</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Directory.list</span>(<span class="param">path</span>) → <span class="type">List</span>
                </div>
                <p>Lists the contents of a directory.</p>
                <pre><code>var files = Directory.list(".")
for (file in files) {
    System.print(file)
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">Directory.exists</span>(<span class="param">path</span>) → <span class="type">Bool</span>
                </div>
                <p>Returns true if the directory exists.</p>

                <div class="method-signature">
                    <span class="method-name">Directory.create</span>(<span class="param">path</span>)
                </div>
                <p>Creates a directory.</p>

                <div class="method-signature">
                    <span class="method-name">Directory.delete</span>(<span class="param">path</span>)
                </div>
                <p>Deletes an empty directory.</p>

                <h2>Stdin Class</h2>

                <div class="class-header">
                    <h3>Stdin</h3>
                    <p>Standard input</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Stdin.readLine</span>() → <span class="type">String</span>
                </div>
                <p>Reads a line from standard input.</p>
                <pre><code>System.write("Enter your name: ")
var name = Stdin.readLine()
System.print("Hello, %(name)!")</code></pre>

                <div class="method-signature">
                    <span class="method-name">Stdin.read</span>() → <span class="type">String</span>
                </div>
                <p>Reads all available data from stdin.</p>

                <h2>Stdout Class</h2>

                <div class="class-header">
                    <h3>Stdout</h3>
                    <p>Standard output</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Stdout.flush</span>()
                </div>
                <p>Flushes the stdout buffer.</p>

                <h2>Stat Class</h2>

                <div class="class-header">
                    <h3>Stat</h3>
                    <p>File metadata and statistics</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Stat.path</span>(<span class="param">path</span>) &#8594; <span class="type">Stat</span>
                </div>
                <p>Returns a Stat object for the specified path.</p>
                <pre><code>var stat = Stat.path("/etc/hosts")
System.print("Size: %(stat.size) bytes")</code></pre>

                <h3>Properties</h3>

                <div class="method-signature">
                    <span class="method-name">size</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The size of the file in bytes.</p>

                <div class="method-signature">
                    <span class="method-name">isFile</span> &#8594; <span class="type">Bool</span>
                </div>
                <p>True if the path is a regular file.</p>

                <div class="method-signature">
                    <span class="method-name">isDirectory</span> &#8594; <span class="type">Bool</span>
                </div>
                <p>True if the path is a directory.</p>

                <div class="method-signature">
                    <span class="method-name">mtime</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The modification time as a Unix timestamp (seconds since epoch).</p>
                <pre><code>var stat = Stat.path("file.txt")
System.print("Modified: %(stat.mtime)")</code></pre>

                <div class="method-signature">
                    <span class="method-name">atime</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The access time as a Unix timestamp.</p>

                <div class="method-signature">
                    <span class="method-name">ctime</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The change time (inode change) as a Unix timestamp.</p>

                <div class="method-signature">
                    <span class="method-name">mode</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The file permission mode.</p>

                <div class="method-signature">
                    <span class="method-name">inode</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The inode number.</p>

                <div class="method-signature">
                    <span class="method-name">device</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The device ID containing the file.</p>

                <div class="method-signature">
                    <span class="method-name">linkCount</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The number of hard links to the file.</p>

                <div class="method-signature">
                    <span class="method-name">user</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The user ID of the file owner.</p>

                <div class="method-signature">
                    <span class="method-name">group</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The group ID of the file.</p>

                <div class="method-signature">
                    <span class="method-name">blockSize</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The preferred block size for I/O operations.</p>

                <div class="method-signature">
                    <span class="method-name">blockCount</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The number of blocks allocated for the file.</p>

                <h2>Examples</h2>

                <h3>Reading and Writing Files</h3>
                <pre><code>import "io" for File

var content = File.read("input.txt")
var processed = content.replace("old", "new")
File.write("output.txt", processed)</code></pre>

                <h3>Working with JSON Files</h3>
                <pre><code>import "io" for File
import "json" for Json

var config = Json.parse(File.read("config.json"))
config["updated"] = true
File.write("config.json", Json.stringify(config, 2))</code></pre>

                <h3>Processing Directory Contents</h3>
                <pre><code>import "io" for File, Directory

var files = Directory.list("./data")
for (file in files) {
    if (file.endsWith(".txt")) {
        var path = "./data/%(file)"
        var size = File.size(path)
        System.print("%(file): %(size) bytes")
    }
}</code></pre>

                <h3>Interactive Input</h3>
                <pre><code>import "io" for Stdin

System.write("Username: ")
var username = Stdin.readLine()

System.write("Age: ")
var age = Num.fromString(Stdin.readLine())

System.print("Hello %(username), you are %(age) years old")</code></pre>

                <h3>File Backup</h3>
                <pre><code>import "io" for File
import "datetime" for DateTime

var backup = Fn.new { |path|
    if (!File.exists(path)) return

    var timestamp = DateTime.now().format("\%Y\%m\%d_\%H\%M\%S")
    var backupPath = "%(path).%(timestamp).bak"
    File.copy(path, backupPath)
    System.print("Backed up to %(backupPath)")
}

backup.call("important.txt")</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>File operations are synchronous but use libuv internally for async I/O. The fiber suspends during I/O operations.</p>
                </div>
{% endblock %}