rock-n-code/playdate-kit
1
0
Fork 0
Code Issues Pull Requests Actions Releases 3 Activity

Tightened the source code and README documentations in the library.

Browse Source
This commit is contained in:
javier
2026-09-18 12:45:39 +02:00
parent c9f887bacb
commit 9ae10590cc
97 changed files with 854 additions and 1142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/PlaydateKit/File/Classes/Handle.swift
+12 -17
View File
@@ -1,15 +1,12 @@
internal import CPlaydate
extension File {
/// An open file. Wraps `SDFile`. The file is closed when the handle goes
/// out of scope, unless it was closed explicitly with `close()`.
///
/// The handle is non-copyable: it has a single owner, so it cannot be
/// used after `close()` and no heap allocation backs it.
/// An open file. Wraps `SDFile`. Non-copyable: closes when the handle goes out of
/// scope, or earlier via consuming `close()`. At most 64 files may be open.
public struct Handle: ~Copyable {
let pointer: UnsafeMutableRawPointer
/// Opens the file at `path`.
/// Opens the file at `path` in `mode`.
public init(path: String, mode: Options) throws(PlaydateError) {
let pointer = path.withCString {
fileAPI.pointee.open.unsafelyUnwrapped($0, mode.cValue)
@@ -23,8 +20,7 @@ extension File {
}
/// Closes the file, consuming the handle.
// `@export(interface)` lets `discard` compile in Embedded Swift with
// the 6.4 release toolchain; later toolchains accept it without.
// `@export(interface)` lets `discard` compile in Embedded Swift on the 6.4 toolchain.
@export(interface)
public consuming func close() throws(PlaydateError) {
let pointer = self.pointer
@@ -32,8 +28,7 @@ extension File {
if fileAPI.pointee.close.unsafelyUnwrapped(pointer) != 0 { throw lastFileError() }
}
/// Reads up to `buffer.count` bytes into `buffer`. Returns the number
/// of bytes read; 0 indicates end of file.
/// Reads up to `buffer.count` bytes; returns the count read, 0 at end of file.
public func read(into buffer: inout MutableSpan<UInt8>) throws(PlaydateError) -> Int {
let result = buffer.withUnsafeMutableBufferPointer { buffer in
fileAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress, UInt32(buffer.count))
@@ -42,7 +37,7 @@ extension File {
return Int(result)
}
/// Reads up to `length` bytes and returns them.
/// Reads up to `length` bytes; shorter near end of file, empty at it.
public func read(length: Int) throws(PlaydateError) -> [UInt8] {
try [UInt8](capacity: length) { output throws(PlaydateError) in
let result = output.withUnsafeMutableBufferPointer { buffer, initializedCount in
@@ -55,7 +50,7 @@ extension File {
}
}
/// Writes the bytes to the file. Returns the number of bytes written.
/// Writes `bytes`; returns the count written.
@discardableResult
public func write(_ bytes: Span<UInt8>) throws(PlaydateError) -> Int {
let result = bytes.withUnsafeBufferPointer { buffer in
@@ -65,7 +60,7 @@ extension File {
return Int(result)
}
/// Writes the bytes to the file. Returns the number of bytes written.
/// Writes `bytes`; returns the count written.
@discardableResult
public func write(_ bytes: [UInt8]) throws(PlaydateError) -> Int {
try bytes.withUnsafeBufferPointer { buffer throws(PlaydateError) in
@@ -73,7 +68,7 @@ extension File {
}
}
/// Writes the string's UTF-8 to the file. Returns the bytes written.
/// Writes `string` as UTF-8, without a NUL terminator; returns the count written.
@discardableResult
public func write(_ string: String) throws(PlaydateError) -> Int {
let result = string.withCString { cString in
@@ -83,7 +78,7 @@ extension File {
return Int(result)
}
/// Flushes buffered writes to disk. Returns the bytes written.
/// Flushes buffered writes; returns the count written.
@discardableResult
public func flush() throws(PlaydateError) -> Int {
let result = fileAPI.pointee.flush.unsafelyUnwrapped(pointer)
@@ -91,14 +86,14 @@ extension File {
return Int(result)
}
/// The current read/write offset.
/// The current read/write offset, in bytes.
public func tell() throws(PlaydateError) -> Int {
let result = fileAPI.pointee.tell.unsafelyUnwrapped(pointer)
if result < 0 { throw lastFileError() }
return Int(result)
}
/// Moves the read/write offset to `offset` relative to `origin`.
/// Moves the read/write offset to `offset` bytes from `origin`.
public func seek(to offset: Int, from origin: SeekOrigin = .start) throws(PlaydateError) {
if fileAPI.pointee.seek.unsafelyUnwrapped(pointer, Int32(offset), origin.rawValue) != 0 {
throw lastFileError()
Sources/PlaydateKit/File/Enumerations/SeekOrigin.swift
+1 -4
View File
@@ -1,11 +1,8 @@
extension File {
/// The origin used by `Handle.seek(to:from:)`.
/// Origin for `Handle.seek(to:from:)`: `SEEK_SET`, `SEEK_CUR`, `SEEK_END`.
public enum SeekOrigin: Int32, Sendable {
/// Relative to the beginning of the file.
case start = 0
/// Relative to the current offset.
case current = 1
/// Relative to the end of the file.
case end = 2
}
}
Sources/PlaydateKit/File/File.swift
+11 -14
View File
@@ -1,24 +1,22 @@
internal import CPlaydate
/// The cached `playdate->file` C API table.
/// Cached `playdate->file` table.
var fileAPI: UnsafePointer<playdate_file> { Playdate.fileAPI.unsafelyUnwrapped }
/// The most recent file system error as a thrown error.
/// The most recent file error, with the OS's description.
func lastFileError() -> PlaydateError {
PlaydateError(cString: fileAPI.pointee.geterr.unsafelyUnwrapped())
}
/// The file API: access to the game's Data directory and pdx contents.
///
/// Paths are relative to the game's Data directory (read/write) or the
/// game's pdx (read-only), depending on the mode used to open them.
/// The file API. Paths are relative to the Data directory (writable) or the pdx (read-only).
/// Every throwing API throws `PlaydateError` with the OS's description on failure.
public enum File {}
extension File {
// MARK: - Directory operations
/// Calls `each` with the name of every file in `path`. Subdirectory names
/// end in a slash. Throws if the directory does not exist.
/// Calls `each` with each entry name in `path`, non-recursively; directories end in `/`.
/// Skips `.`-prefixed names unless `showHidden`. Throws if `path` can't be opened.
public static func listFiles(at path: String, showHidden: Bool = false,
_ each: (String) -> Void) throws(PlaydateError) {
let result = withoutActuallyEscaping(each) { each in
@@ -36,7 +34,7 @@ extension File {
if result != 0 { throw lastFileError() }
}
/// Information about the file or directory at `path`.
/// Information about the file or directory at `path`; throws if it is missing.
public static func stat(_ path: String) throws(PlaydateError) -> Stat {
var stat = FileStat()
let result = path.withCString { fileAPI.pointee.stat.unsafelyUnwrapped($0, &stat) }
@@ -49,14 +47,13 @@ extension File {
hour: UInt8(stat.m_hour), minute: UInt8(stat.m_minute), second: UInt8(stat.m_second)))
}
/// Creates a directory (and intermediate directories) in the Data directory.
/// Creates directory `path` in the Data directory; does not create intermediate ones.
public static func mkdir(_ path: String) throws(PlaydateError) {
let result = path.withCString { fileAPI.pointee.mkdir.unsafelyUnwrapped($0) }
if result != 0 { throw lastFileError() }
}
/// Deletes the file or directory at `path`. Directories require
/// `recursive` to be deleted with their contents.
/// Deletes the file at `path`; with `recursive`, a directory and its contents.
public static func unlink(_ path: String, recursive: Bool = false) throws(PlaydateError) {
let result = path.withCString {
fileAPI.pointee.unlink.unsafelyUnwrapped($0, recursive ? 1 : 0)
@@ -64,8 +61,8 @@ extension File {
if result != 0 { throw lastFileError() }
}
/// Renames (moves) a file in the Data directory, overwriting any existing
/// file at the destination.
/// Moves `from` to `to` in the Data directory, overwriting `to`; does not create
/// intermediate directories.
public static func rename(from: String, to: String) throws(PlaydateError) {
let result = from.withCString { cFrom in
to.withCString { cTo in
Sources/PlaydateKit/File/Structures/Options.swift
+5 -5
View File
@@ -1,18 +1,18 @@
internal import CPlaydate
extension File {
/// How to open a file.
/// How to open a file. Wraps `FileOptions`.
public struct Options: OptionSet, Sendable {
public let rawValue: UInt32
public init(rawValue: UInt32) { self.rawValue = rawValue }
/// Read from the game pdx, then the Data directory.
/// Read from the pdx only; add `.readData` to search the Data directory first.
public static let read = Options(rawValue: UInt32(kFileRead.rawValue))
/// Read from the Data directory only.
/// Read from the Data directory.
public static let readData = Options(rawValue: UInt32(kFileReadData.rawValue))
/// Write to the Data directory, truncating an existing file.
/// Write to the Data directory, truncating.
public static let write = Options(rawValue: UInt32(kFileWrite.rawValue))
/// Write to the Data directory, appending to an existing file.
/// Write to the Data directory, appending.
public static let append = Options(rawValue: UInt32(kFileAppend.rawValue))
var cValue: FileOptions { FileOptions(FileOptions.RawValue(rawValue)) }
Sources/PlaydateKit/File/Structures/Stat.swift
+3 -4
View File
@@ -1,11 +1,10 @@
extension File {
/// Information about a file or directory, mirroring `FileStat`.
/// File or directory information. Mirrors `FileStat`.
public struct Stat: Sendable {
/// Whether the path is a directory.
public let isDirectory: Bool
/// The file's size, in bytes.
/// Size in bytes.
public let size: UInt32
/// The time the file was last modified.
/// Last modification time; `weekday` is 0 (unset).
public let modified: System.DateTime
}
}