# FileKit
**Repository Path**: sunny_sun/FileKit
## Basic Information
- **Project Name**: FileKit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-16
- **Last Updated**: 2024-06-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
FileKit is a Swift framework that allows for simple and expressive file management.
Development happens in the
[`develop`](https://github.com/nvzqz/FileKit/tree/develop) branch.
## Installation
### Compatibility
- OS X 10.9+ / iOS 8.0+ / watchOS 2.0 / tvOS 9.0
- Xcode 7.1+, Swift 2.1+
### Install Using CocoaPods
[CocoaPods](https://cocoapods.org/) is a centralized dependency manager for
Objective-C and Swift. Go [here](https://guides.cocoapods.org/using/index.html)
to learn more.
1. Add the project to your [Podfile](https://guides.cocoapods.org/using/the-podfile.html).
```ruby
use_frameworks!
pod 'FileKit', '~> 5.0.0'
```
2. Run `pod install` and open the `.xcworkspace` file to launch Xcode.
3. Import the FileKit framework.
```swift
import FileKit
```
### Install Using Carthage
[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency
manager for Objective-C and Swift.
1. Add the project to your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#cartfile).
```
github "nvzqz/FileKit"
```
2. Run `carthage update` and follow [the additional steps](https://github.com/Carthage/Carthage#getting-started)
in order to add FileKit to your project.
3. Import the FileKit framework.
```swift
import FileKit
```
## Usage
### Paths
Paths are handled with the `Path` structure.
```swift
let home = Path("~")
let drive: Path = "/Volumes/Macintosh HD"
let file: Path = "~/Desktop/file\(1)"
```
#### Operations
##### New Files
A blank file can be written by calling `createFile()` on an `Path`.
```swift
try Path(".gitignore").createFile()
```
##### New Directories
A directory can be created by calling `createDirectory()` on an `Path`.
```swift
try Path("~/Files").createDirectory()
try Path("~/Books").createDirectory(withIntermediateDirectories: false)
```
Intermediate directories are created by default.
##### New Symlinks
A symbolic link can be created by calling `createSymlinkToPath(_:)` on an `Path`.
```swift
try Path("path/to/MyApp.app").symlinkFile(to: "~/Applications")
print(Path("~/Applications/MyApp.app").exists) // true
```
##### Finding Paths
You can find all paths with the ".txt" extension five folders deep into the
Desktop with:
```swift
let textFiles = Path.userDesktop.find(searchDepth: 5) { path in
path.pathExtension == "txt"
}
```
A negative `searchDepth` will make it run until every path in `self` is checked
against.
You can even map a function to paths found and get the non-nil results:
```swift
let documents = Path.userDocuments.find(searchDepth: 1) { path in
String(path)
}
```
##### Iterating Through Paths
Because `Path` conforms to `SequenceType`, it can be iterated through with a
`for` loop.
```swift
for download in Path.userDownloads {
print("Downloaded file: \(download)")
}
```
##### Current Working Directory
The current working directory for the process can be changed with `Path.Current`.
To quickly change the current working directory to a path and back, there's the
`changeDirectory(_:)` method:
```swift
Path.userDesktop.changeDirectory {
print(Path.current) // "/Users/nvzqz/Desktop"
}
```
##### Common Ancestor
A common ancestor between two paths can be obtained:
```swift
print(Path.root.commonAncestor(.userHome)) // "/"
print("~/Desktop" <^> "~/Downloads") // "~"
print(.UserLibrary <^> .UserApplicationSupport) // "/Users/nvzqz/Library"
```
##### `+` Operator
Appends two paths and returns the result
```swift
// ~/Documents/My Essay.docx
let essay = Path.userDocuments + "My Essay.docx"
```
It can also be used to concatenate a string and a path, making the string value
a `Path` beforehand.
```swift
let numberedFile: Path = "path/to/dir" + String(10) // "path/to/dir/10"
```
##### `+=` Operator
Appends the right path to the left path. Also works with a `String`.
```swift
var photos = Path.userPictures + "My Photos" // ~/Pictures/My Photos
photos += "../My Other Photos" // ~/Pictures/My Photos/../My Other Photos
```
##### `%` Operator
Returns the standardized version of the path.
```swift
let path: Path = "~/Desktop"
path% == path.standardized // true
```
##### `*` Operator
Returns the resolved version of the path.
```swift
let path: Path = "~/Documents"
path* == path.resolved // true
```
##### `^` Operator
Returns the path's parent path.
```swift
let path: Path = "~/Movies"
path^ == "~" // true
```
##### `->>` Operator
Moves the file at the left path to the right path.
`Path` counterpart: **`moveFile(to:)`**
`File` counterpart: **`move(to:)`**
##### `->!` Operator
Forcibly moves the file at the left path to the right path by deleting anything
at the left path before moving the file.
##### `+>>` Operator
Copies the file at the left path to the right path.
`Path` counterpart: **`copyFile(to:)`**
`File` counterpart: **`copy(to:)`**
##### `+>!` Operator
Forcibly copies the file at the left path to the right path by deleting anything
at the left path before copying the file.
##### `=>>` Operator
Creates a symlink of the left path at the right path.
`Path` counterpart: **`symlinkFile(to:)`**
`File` counterpart: **`symlink(to:)`**
##### `=>!` Operator
Forcibly creates a symlink of the left path at the right path by deleting
anything at the left path before creating the symlink.
##### Subscripting
Subscripting an `Path` will return all of its components up to and including
the index.
```swift
let users = Path("/Users/me/Desktop")[1] // /Users
```
##### `standardize()`
Standardizes the path.
The same as doing:
```swift
somePath = somePath.standardized
```
##### `resolve()`
Resolves the path's symlinks.
The same as doing:
```swift
somePath = somePath.resolved
```
### Files
A file can be made using `File` with a `DataType` for its data type.
```swift
let plistFile = File(path: Path.userDesktop + "sample.plist")
```
Files can be compared by size.
#### Operators
##### `|>` Operator
Writes the data on the left to the file on the right.
```swift
do {
try "My name is Bob." |> TextFile(path: Path.userDesktop + "name.txt")
} catch {
print("I can't write to a desktop file?!")
}
```
#### TextFile
The `TextFile` class allows for reading and writing strings to a file.
Although it is a subclass of `File`, `TextFile` offers some functionality
that `File` doesn't.
##### `|>>` Operator
Appends the string on the left to the `TextFile` on the right.
```swift
let readme = TextFile(path: "README.txt")
try "My Awesome Project" |> readme
try "This is an awesome project." |>> readme
```
#### NSDictionaryFile
A typealias to `File`.
#### NSArrayFile
A typealias to `File`
#### NSDataFile
A typealias to `File`
#### DataFile
The `DataFile` class allows for reading and writing `Data` to a file.
Although it is a subclass of `File`, `DataFile` offers some functionality
that `File` doesn't. You could specify `Data.ReadingOptions` and `Data.WritingOptions`
#### Encodable/Decodable
You can use any `Codable` object with `File`.
```swift
extension AnyCodableClass: JSONReadableWritable {} // if you want json encoding/decoding
let codableFile = File(path: path)
try codableFile.write(toEncode)
let decoded: AnyCodableClass = try codableFile.read()
```
Alternatively you can use utility methods
```swift
try FileKit.write(toEncode, to: path)
let decoded: AnyCodableClass = try FileKit.read(from: path)
```
### File Permissions
The `FilePermissions` struct allows for seeing the permissions of the current
process for a given file.
```swift
let swift: Path = "/usr/bin/swift"
print(swift.filePermissions) // FilePermissions[read, execute]
```
### Data Types
All types that conform to `DataType` can be used to satisfy the generic type for
`File`.
#### Readable Protocol
A `Readable` type must implement the static method `read(from: Path)`.
All `Readable` types can be initialized with `init(contentsOfPath:)`.
#### Writable Protocol
A `Writable` type must implement `write(to: Path, atomically: Bool)`.
Writing done by `write(to: Path)` is done atomically by default.
##### WritableToFile
Types that have a `write(toFile:atomically:)` method that takes in a `String`
for the file path can conform to `Writable` by simply conforming to
`WritableToFile`.
##### WritableConvertible
If a type itself cannot be written to a file but can output a writable type,
then it can conform to `WritableConvertible` and become a `Writable` that way.
### FileKitError
The type for all errors thrown by FileKit operations is `FileKitError`.
Errors can be converted to `String` directly for any logging. If only the error
message is needed, `FileKitError` has a `message` property that states why the
error occurred.
```swift
// FileKitError(Could not copy file from "path/to/file" to "path/to/destination")
String(FileKitError.copyFileFail(from: "path/to/file", to: "path/to/destination"))
```
## License
FileKit and its assets are released under the [MIT License](LICENSE.md). Assets
can be found in the [`assets`](https://github.com/nvzqz/FileKit/tree/assets)
branch.
