cuba / diskkit

A swift framework for storing files in disk and iCloud

DiskKit

• Features
• Installation
• Usage
• Credits
• License

Features

• Store any file type
• Easy integration
• Suppports Document Packages
• Suppports Codable protocol

Installation

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate DiskKit into your Xcode project using Carthage, specify it in your Cartfile:

github "cuba/DiskKit"

Run carthage update to build the framework and drag the built DiskKit.framework into your Xcode project.

Usage

Supported files

Codable

struct TestCodable: Codable {
    var id = UUID().uuidString
    
    init(id: String) {
        self.id = id
    }
}

DiskCodable

DiskCodable gives you some extra flexability with the types of files you can store.

struct TestDiskCodable: DiskCodable {
    var id = UUID().uuidString
    
    init(id: String) {
        self.id = id
    }
    
    init(_ data: Data) throws {
        id = String(data: data, encoding: .utf8)!
    }
    
    func encode() throws -> Data {
        return id.data(using: .utf8)!
    }
}

File

File is just a wrapper around a file. It allows you to easily save and load objects of a specific type. It also is a great way to support polimorphyc file types useful when saving and getting data from a directly that contains mixed file types.

It supports the files above plus some convenient extras such as String.

Storing files

Store a single file like this:

let filename = "example.json"
let testFile = TestCodable(id: "ABC")

do {
  EncodableDisk.store(testFile, to: .documents, as: filename)
} catch {
  // Handle error
}

Loading files

You can load a single file like this:

do {
  let loadedFile: TestCodable = try EncodableDisk.file(withName: filename, in: .documents)
} catch {
  // Handle error
}

or you can load all the files in the directory like this:

do {
  let loadedFiles: [TestCodable] = try EncodableDisk.files(in: .documents)
} catch {
  // Handle error
}

Document Packages

You may also store Document Packages. You just need to implement the Directory protocol:

Packages also support nested packages which need to extend the Directory protocol.

struct TestPackage: Package {
    static let typeIdentifier = "com.example.myproject.package"
    
    var codable: TestCodable
    var diskCodable: TestDiskCodable
    
    init(codable: TestCodable, diskCodable: TestDiskCodable) {
        self.codable = codable
        self.diskCodable = diskCodable
    }
    
    init(directory: Directory) throws {
        self.codable = try map.file("codable.json")
        self.diskCodable = try map.file("disk_codable.json")
    }
    
    func fill(directory: Directory) throws {
        try map.add(codable, name: "codable.json")
        try map.add(diskCodable, name: "disk_codable.json")
    }
}

Saving Packages

let testFile = TestPackage(
  codable: TestCodable(id: "CODABLE_ABC"),
  diskCodable: TestDiskCodable(id: "DISK_CODABLE_ABC")
)

let filename = "example.package"

do {
  try PackagableDisk.store(testFile, to: .documents, as: filename)
} catch {
  // Handle error
}

Loading packages

do {
    let url = Disk.Directory.documents.baseUrl
    let directory: TestPackage = try PackagableDisk.package(in .documents, withName: filename)
} catch {
    // Handle error
}

Note: You need to provide additional information about your directory type (and extension) in your applications Info.plist file. You can get more information about Document Packages here.

Without this additional information, your directory will not be found.

Directories

You can query entire directories with all of its contents

Directory supported types

Directory supports the following types:

• Directory class
• Codable types
• Codable arrays (i.e. [T] where T: Codable) These will be stored in auto-generated file names
• DiskCodable types
• DiskCodable arrays (i.e. [T] where T: DiskCodable) These will be stored in auto-generated file names
• File class
• File arrays (i.e. [File]) These will be stored in auto-generated file names
• UIImage types
• String types
• Data types

Using File

File is a helper class that lets you parse your files after retrieving them. This is useful when you're not sure what kind of file you are expected to recieve. It is also used inside packages as it may contain a variety of different file types.

Creating File objects

let filename = "example.json"
let testFile = TestCodable(id: "ABC")
let file = try File(file: testFile, name: filename)

File supports both Codable and DiskCodable files.

Storing File objects:

try Disk.create(path: "some_folder", in: .documents)
try Disk.store(file, to: .documents, path: "some_folder")

Loading File objects:

let loadedDiskData = try Disk.file(withName: filename, in: .documents, path: "some_folder")

Loading multiple File objects:

let loadedDiskDataArray = try Disk.filesArray(in: .documents, path: "some_folder")

Parsing a file from a File object:

let loadedFile: TestCodable = try loadedDiskData.decode()

Subdirectories

You may also provide a subdirectory (path) for your file. Ensure that your path does not begin with a /

First you will have to create your subdirectory like this:

try Disk.create(path: "some_folder", in: .documents)

try EncodableDisk.store(testFile, to: .documents, as: "example.json", path: "some_folder")

Other useful functionality

In addition to the standard storing and loading methods on files and packages, you may also do the following:

Clear the contents of a directory

try Disk.clear(.documents)

Create a subdirectory

try Disk.create(path: "some_folder", in: .documents)

Delete a subdirectory

try Disk.remove(path: "some_folder", in: .documents)

Dependencies

DiskKit has no dependencies

Credits

DiskKit is owned and maintained by Jacob Sikorski.

License

DiskKit is released under the MIT license. See LICENSE for details