Joseph HeckandCory Benfield
6b33489e64
This re-enables documentation lost during refactoring work, under the target _NIOFileSystem resolves #3474 ### Motivation: During the refactoring of NIOFileSystem and recent Swift updates, the mechanism to "shadow" symbols using `@_exported import` has stopped working for documentation and imports for symbols, which means that _NIOFileSystem is the target that needs to host the documentation for this (for now) ### Modifications: Moves DocC catalog into _NIOFileSystem target, and updates disambiguation hashes on overloaded symbols in order to verify no warnings are presented while generating documentation. Updates .spi.yml to present _NIOFileSystem instead of NIOFileSystem ### Result: Previous documentation should be available again, although at a slightly different URI structure within Swift Package Index. Co-authored-by: Cory Benfield <lukasa@apple.com>
2.2 KiB
_NIOFileSystem
A file system library for Swift.
Overview
This module implements a file system library for Swift, providing ways to interact with and manage
files. It provides a concrete FileSystem for interacting with the local file system in addition
to a set of protocols for creating other file system implementations.
_NIOFileSystem is cross-platform with the following caveats:
- Platforms don't have feature parity or system-level API parity. Where this is the case these implementation details are documented. One example is copying files, on Apple platforms files are cloned if possible.
- Features may be disabled on some systems. One example is extended attributes.
- Some types have platform specific representations. These include the following:
- File paths on Apple platforms and Linux (e.g.
"/Users/hal9000/") are different to paths on Windows ("C:\Users\hal9000"). - Information about files is different on different platforms. See
FileInfofor further details.
- File paths on Apple platforms and Linux (e.g.
A Brief Tour
The following sample code demonstrates a number of the APIs offered by this module:
@Snippet(path: "swift-nio/Snippets/NIOFileSystemTour")
In depth documentation can be found in the following sections.
Topics
Interacting with the Local File System
FileSystemFileHandleReadFileHandleWriteFileHandleReadWriteFileHandleDirectoryFileHandlewithFileSystem(numberOfThreads:_:)
File and Directory Information
FileInfoFileType
Reading Files
FileChunksBufferedReader
Writing Files
BufferedWriter
Listing Directories
DirectoryEntryDirectoryEntries
Errors
FileSystemError is the only top-level error type thrown by the package (apart from Swift's
CancellationError).
FileSystemErrorFileSystemError/SystemCallError
Creating a File System
Custom file system's can be created by implementing FileSystemProtocol which depends on a number
of other protocols. These include the following:
FileSystemProtocolFileHandleProtocolReadableFileHandleProtocolWritableFileHandleProtocolReadableAndWritableFileHandleProtocolDirectoryFileHandleProtocol