Swiftpack.co - Package - JohnSundell/Files

“Files”

BuddyBuild CocoaPods Carthage Swift Package Manager Twitter: @johnsundell

Welcome to Files, a compact library that provides a nicer way to handle files and folders in Swift. It’s primarily aimed at Swift scripting and tooling, but can also be embedded in applications that need to access the file system. It's essentially a thin wrapper around the FileManager APIs that Foundation provides.

Features

  • [X] Modern, object-oriented API for accessing, reading and writing files & folders.
  • [X] Unified, simple do, try, catch error handling.
  • [X] Easily construct recursive and flat sequences of files and folders.

Examples

Iterate over the files contained in a folder:

for file in try Folder(path: "MyFolder").files {
    print(file.name)
}

Rename all files contained in a folder:

try Folder(path: "MyFolder").files.enumerated().forEach { (index, file) in
    try file.rename(to: file.nameWithoutExtension + "\(index)")
}

Recursively iterate over all folders in a tree:

Folder.home.subfolders.recursive.forEach { folder in
    print("Name : \(folder.name), parent: \(folder.parent)")
}

Create, write and delete files and folders:

let folder = try Folder(path: "/users/john/folder")
let file = try folder.createFile(named: "file.json")
try file.write("{\"hello\": \"world\"}")
try file.delete()
try folder.delete()

Move all files in a folder to another:

let originFolder = try Folder(path: "/users/john/folderA")
let targetFolder = try Folder(path: "/users/john/folderB")
try originFolder.files.move(to: targetFolder)

Easy access to system folders:

Folder.current
Folder.root
Folder.library
Folder.temporary
Folder.home
Folder.documents

Installation

Files can be easily used in either a Swift script, a command line tool, or in an app for iOS, macOS, tvOS or Linux.

Using the Swift Package Manager (preferred)

To install Files for use in a Swift Package Manager-powered tool, script or server-side application, add Files as a dependency to your Package.swift file. For more information, please see the Swift Package Manager documentation.

.package(url: "https://github.com/JohnSundell/Files", from: "4.0.0")

Using CocoaPods or Carthage

Please refer to CocoaPods’ or Carthage’s own documentation for instructions on how to add dependencies using those tools.

As a file

Since all of Files is implemented within a single file, you can easily use it in any project by simply dragging the file Files.swift into your Xcode project.

Backstory

So, why was this made? As I've migrated most of my build tools and other scripts from languages like Bash, Ruby and Python to Swift, I've found myself lacking an easy way to deal with the file system. Sure, FileManager has a quite nice API, but it can be quite cumbersome to use because of its string-based nature, which makes simple scripts that move or rename files quickly become quite complex.

So, I made Files, to enable me to quickly handle files and folders, in an expressive way. And, since I love open source, I thought - why not package it up and share it with the community? :)

Questions or feedback?

Feel free to open an issue, or find me @johnsundell on Twitter.

Github

link
Stars: 1706

Dependencies

Releases

Files 4.1.1 - 2020-01-06 22:00:17

This release restores Files' compatibility with Mac Catalyst.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 4.1.0 - 2020-01-01 22:30:33

  • On macOS, files can now be opened within the OS by calling open() on them (by @Amzd).
  • Fixed a bug that could cause nameExcludingExtension to return an empty string.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 4.0.2 - 2019-09-27 12:27:50

This release contains patches for two bugs:

  • When calling the createFileIfNeeded set of APIs, the content passed as any newly created file's content was previously ignored. That has now been fixed.
  • When accessing the parent of any folder contained within the file system's root folder, the actual root folder is now correctly returned. Thanks to @MaximeLM for implementing that fix.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 4.0.1 - 2019-09-24 22:23:31

This patch restores the copy API to again return the new file/folder that was copied.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 4.0 - 2019-09-07 12:26:44

Files 4.0 brings a brand new, streamlined implementation, improved error handling, more thorough documentation, and a more modern API. Since it's a new major release, some breaking API changes have been made. Here's everything that's new:

  • The FileSystem class has been removed. To perform operations relative to the root of the file system, use the new Folder.root API instead. To use a custom FileManager, call managedBy() on any File or Folder.
  • FileSystem.Item has been replaced by the Location protocol, and FileSystem.Item.Kind has been replaced by LocationKind.
  • You can now consistently use either a name or path when using any API for creating or referring to files and subfolders within a folder.
  • Methods accepting a path now use the simplified at: label, rather than atPath:.
  • External argument labels have been removed for APIs that write new contents to a file. So write(string:) and write(data:) are now two overloads of the same method: write(_:).
  • All of the APIs for creating files now only accept Data as a file's initial contents. To write strings to a file, first create the file and then call file.write(string) on it.
  • File now has a creationDate property.
  • Folder now has static properties for accessing the current user's Library and Documents folders.
  • Error handling has been improved to now use a unified FilesError type, that always contains the path at which the error occurred, as well as a Reason - which can either be for locations, writes, or reads. See the LocationError, WriteError and ReadError type aliases for the three types of errors that Files can throw.
  • Computed properties that don't have O(1) time complexity have now been changed into methods instead. That includes name(), count(), and last() on file/folder sequences, since computing those requires enumerating the sequence. The time complexity of each sequence operation is now also documented.
  • FileSystemSequence is now Folder.ChildSequence, and each sequence can now easily be turned into a recursive one by accessing the recursive property. The same is also true for including hidden files, which is now done by accessing the includingHidden property on a sequence. The makeFileSequence(...) and makeSubfolderSequence(...) APIs have been removed in favor of constructing customized sequences using those new computed properties.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 3.1.0 - 2019-04-05 21:57:20

  • Both File and Folder now have a path(relativeTo:) API, which makes it easy to calculate a given item's path relative to one of its parent folders.
  • FileSystem.documentFolder and FileSystem.libraryFolder are now only available on macOS.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 3.0.0 - 2019-03-26 12:51:10

Files now uses Swift 5.0, which makes it incompatible with toolchains with versions lower than 4.2.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.3.0 - 2019-03-15 13:08:38

  • New APIs have been added to check whether a given folder contains either another folder or a file (thanks @clayellis!)
  • The old, long since deprecated creatingSubfolderFailed error has now been fully removed.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.2.1 - 2018-04-10 16:15:34

This patch makes Files backwards compatible with Swift 4.0. Thanks @iainsmith 🙌

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.2.0 - 2018-04-01 19:59:10

This release bumps Files' Swift version to 4.1. Thanks @krzyzanowskim! 👍

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.1.0 - 2018-03-27 20:55:26

This release of Files contains great improvements from the community! 🎉

  • Fix for invalid paths generated by moving a folder (by @clayellis)
  • You now get a much better debug description from a file or folder sequence (by @gwikiera)
  • You can now append data to a file (by @ikhsan)

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.0.1 - 2017-11-05 19:41:41

Files now uses the Swift 4 version of the Swift Package Description API.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 2.0.0 - 2017-11-04 13:15:30

  • Files now uses Swift 4 (thanks @artemnovichkov!)
  • Errors now have much nicer descriptions when printed (thanks @VFUC!)
  • You can now modify a folder that you are iterating over, and the changes will propagate to the iteration (thanks @LarsJK!)

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 1.12.0 - 2017-09-23 10:07:44

This release adds an API for copying files/folders (thanks @artemnovichkov!)

Files 1.11.0 - 2017-08-15 20:31:38

You can now include hidden files/folders when moving the contents of a folder to another (thanks @clayellis!)

Files 1.10.0 - 2017-07-10 11:32:36

  • You can now create a file with string content directly using: folder.createFile(named: "File", content: "Hello world")
  • Iterating over files and folders recursively is now done in the same order on all supported operating systems.

View build details and download artifacts on buddybuild: Files (iOS, Files-iOS)

Files 1.9.0 - 2017-06-03 18:38:57

  • Files now has Continuous Integration for all its supported platforms.
  • Both File and Folder now has a modificationDate property.
  • FileSystem now has a createFileIfNeeded() method (thanks @cojoj!).

See build details and artifacts at buddybuild: https://dashboard.buddybuild.com/apps/5932f7d9b0c2b000015d6b79/build/59330242c5a55b00016d6165

Files 1.8.0 - 2017-04-30 17:45:17

This new version of Files adds new APIs for accessing the current, home and temporary folders using Folder.current, Folder.home and Folder.temporary. Thanks to @yageek for implementing this! 🚀

Files 1.7.0 - 2017-04-17 18:50:21

This version of Files makes it easier to check if a folder contains a given file or subfolder, by introducing two new APIs on Folder:

folder.containsFile(named: "File")

and

folder.containsSubfolder(named: "Subfolder")

Files 1.6.2 - 2017-04-02 14:55:38

This release of Files patches a bug that would cause files created using FileSystem.createFile(at:) to get an invalid name. Thanks to @pixyzehn for fixing this 🎉

Files 1.6.1 - 2017-03-24 18:07:29

Files now correctly handles paths that contains parent references, by expanding those references into absolute paths.

So ../file is expanded to <currentFolderParent>/file.

Files 1.6.0 - 2017-03-20 19:10:00

This release of Files brings everything from the 1.5.x releases and more to make handling files & folders even easier 🚀

You can now...

  • Return either an existing subfolder or file for a given name, or create one if missing - using folder.createSubfolderIfNeeded(withName:) and folder.createFileIfNeeded(withName:contents:).
  • Easily access a folder deeper within a parent folder's tree, by calling try folder.subfolder(atPath: "A/B/C").
  • Easily access a file at a path relative to a folder using folder.file(atPath: "A/B/C.txt").
  • Read a file either as a String or an Int, using readAsString() and readAsInt().
  • Access the current folder using FileSystem().currentFolder.
  • Create a file directly using a path, and create any intermediate parent folders if they don't exist - using FileSystem().createFile(at:).

Also...

  • When accessing the current folder, it now has a trailing / in its path like all other folders.
  • A bug was fixed that would previously cause tildes (~) not to be expanded when used for the path when creating a folder using FileSystem.createFolder(at:).

Files 1.5.5 - 2017-03-12 13:23:21

  • When using the methods that only create a file/folder when needed, you no longer get a warning if you don't use the result.
  • When accessing the current folder, it now has a trailing / in its path like all other folders.
  • You can now access the current folder using FileSystem().currentFolder.

Files 1.5.4 - 2017-03-11 23:03:29

This release is a bug fix that would previously cause tildes (~) not to be expanded when used for the path when creating a folder using FileSystem.createFolder(at:).

Files 1.5.3 - 2017-03-11 21:15:48

  • You can now read a file either as a String or an Int, using readAsString() and readAsInt().
  • You can now easily access a file at a path relative to a folder using folder.file(atPath:).
  • You can now create a file only if it's missing using folder.createFileIfNeeded(withName:contents:).

Files 1.5.2 - 2017-03-10 16:20:49

You can now easily access a folder deeper within a parent folder's tree, by calling:

try folder.subfolder(atPath: "A/B/C")

instead of having to retrieve all the intermediate folders.

Files 1.5.1 - 2017-03-07 21:36:49

You can now either return an existing subfolder for a given name, or create one if missing - using Folder.createSubfolderIfNeeded(withName:).

Files 1.5.0 - 2017-03-07 18:16:18

  • You can now either return an existing folder for a given path, or create one if missing - using FileSystem.createFolderIfNeeded(at:).
  • You can now move the entire contents of a folder to a new parent folder using Folder.moveContents(to:).

Files 1.4.0 - 2017-02-19 15:23:58

  • You can now retrieve the current user's Document folder, and the Library folder using FileSystem. Thanks to @onurersel for implementing this!
  • When emptying a folder, you can now choose to include hidden (dot) files.
  • You can now create a path of folders directly (with intermediate folders) using FileSystem.

⚠️ Deprecations:

  • This release deprecates Folder.Error.creatingSubfolderFailed in favor of Folder.Error.creatingFolderFailed. The old symbol will be removed in Files 1.5.0.

Files 1.3.1 - 2017-02-01 18:22:26

You can now reference a file or folder using either a relative path, or using a tilde to represent the current user's home folder.