Getting started

Experimental

The Swift binding is unreleased and experimental. Build from source before following this guide — see Overview for build steps.

Your first program

This program creates an in-memory operator, writes bytes to a path, and reads them back. No credentials or network access needed.

import OpenDAL

// Create an operator backed by the in-memory service.
let op = try Operator(scheme: "memory")

// Write bytes to a path.
var data = Data("Hello, World!".utf8)
try op.blockingWrite(&data, to: "hello.txt")

// Read them back.
let result = try op.blockingRead("hello.txt")
print("read \(result.count) bytes")
print(String(data: result, encoding: .utf8)!)

Operator.init(scheme:options:) throws OperatorError on failure. Both blockingWrite and blockingRead also throw OperatorError; wrap calls in do/catch for production code.

Passing options

Service configuration is passed as a [String: String] dictionary. For example, to pin a root path on the memory service:

import OpenDAL

let op = try Operator(
    scheme: "memory",
    options: ["root": "/myroot"]
)

var data = Data("hello".utf8)
try op.blockingWrite(&data, to: "file.txt")

let bytes = try op.blockingRead("file.txt")
print(String(data: bytes, encoding: .utf8)!) // hello

Pointing at a real backend

Only the scheme and options change; the write/read calls are identical. The keys for each service are listed on /services.

import OpenDAL

// S3 example — fill in real values.
let op = try Operator(
    scheme: "s3",
    options: [
        "bucket": "my-bucket",
        "region": "us-east-1",
        "access_key_id": "...",
        "secret_access_key": "...",
    ]
)

var payload = Data("hello from S3".utf8)
try op.blockingWrite(&payload, to: "hello.txt")

Error handling

Both Operator.init and the blocking operations throw OperatorError:

import OpenDAL

do {
    let op = try Operator(scheme: "memory")
    let _ = try op.blockingRead("/does-not-exist")
} catch let err as OperatorError {
    print("OpenDAL operation failed: \(err)")
} catch {
    print("unexpected error: \(error)")
}

Note: OperatorError has code (UInt32) and message (Data) fields internally, but they are not declared public and cannot be accessed from consuming packages. Until they are exposed, use the error's string representation via \(err) or err.localizedDescription.