A basic wrapper around common Swift file/folder/query operations

Furl – basic file URL operations

Why?

I found myself re-writing common file/folder access/info routines. While the Cocoa apis are very capable, sometimes getting basic information is quite tedious.

This is a micro-framework of basic file/folder and Spotlight query operations.

Basic example

// Create a temporary folder to work in
let tempFolder = Folder.Temporary(create: true)

// Generate a new file within the folder, but don't create it
let workingFile = try tempFolder.file("output.txt")

// Write some text into the file
try "hello".write(to: workingFile.fileURL, atomically: true, encoding: .utf8)

// Check that we are a file
assert(workingFile.isFile)

// Grab the file's UTI
let uti = try workingFile.typeIdentifier()  // should be "public.plain-text"

// Lock the file
workingFile.isLocked = true

// Generate a child folder (note, this by default does not create it)
let childFolder = try tempFolder.subFolder("child")

// Make the folder on disk. Note this creates the folder if it doesn't already exist
try childFolder.actualize()

// And finally remove our temporary folder
try tempFolder.delete()

API

Location

A Location is the common sub-unit of a File and a Folder. It contains routines that are common to both files and folders.

You never explicitly create a Location, rather you will work with File and Folder.

Attributes

API Description
basename The location’s name including the extension
name The location’s name without the extension
displayName The location’s display name
extension The location’s extension
parent The location’s containing folder
state The location’s state (folder, file, unknown)
exists Does the location exist on disk?
doesNotExist Does the location not yet exist on disk?
isFolder Is this an existing folder?
isFile Is this an existing file?
isAlias Is this an alias file?
isSymlink Is this a symbolic link?
creationDate The location’s creation date
modificationDate The location’s modification date
isExtensionHidden Is the location’s extension hidden? (read/write)
isLocked Is the location locked? (read/write)
attributes The location’s attributes

Basic permissions

API Description
isReadable The location can be read
isWritable The location can be written to
isExecutable The location can be executed
isDeletable The location is deletable

Universal Type Identifier

API Description
contentType() The UTI for the location (if it exists)
typeIdentifier() The type identifier for the location
conformsTo() Does this location conform to the specified UTI

Operations

API Description Notes
move() Move the file/folder to a new location
copy() Copy the file/folder to a new location
rename() Rename the file/folder
delete() Remove the file/folder from disk
moveToTrash() Move the file/folder to the trash macOS only
revealInFinder() Reveal the file/folder in the Finder macOS only

Symlinks and Aliases

API Description Notes
resolvingSymLinks() Resolve any symlinks within the location
createSymLink() Create a symlink
resolvingAlias() Resolves the destination of the alias file macOS only
createAlias() Create a file/folder alias macOS only

File

A File object represents a file. The file may or may exist yet.

let file = File(fileURL: <some url>)
guard file.exists else { .... }
let fileSize = file.fileSize
let modificationDate = file.modificationDate
let uti = try file.contentType()

try file.moveToTrash()

General

API Description
fileSize The file’s size in bytes
standardized Returns a File with a standardised file path
actualize() If the file doesn’t exist, create the file on disk

Temporary files

API Description
File.Temporary() Returns a temporary file

Folder

A Folder object represents a folder. The representation may or may not yet exist on disk

Temporary folders

API Description
Folder.Temporary() Returns a temporary folder
createUniqueFile() Create a unique file within this folder
createUniqueSubfolder() Create a unique subfolder within this folder
createUniqueDatedSubfolder() Create a unique subfolder within this folder of the form <identifier>/<date>

Locating files

API Description
contains() Does this folder contain a location with the specified name
containsFolder() Does this folder contain a subfolder with the specified name
containsFile() Does this folder contain a file with the specified name

Generating files/folders

API Description
subfolder() A subfolder in this folder with a specified name
file() A file in this folder with a specified name
writeDataToFile() Write data to a file in this folder

Folder Content

API Description Notes
isEmpty() Is this folder empty?
enumerateContent() Enumerate the contents of this folder Optionally recursive
allContent() Returns all the locations in this folder Optionally recursive
allSubfolders() Returns just the subfolders of this folder Optionally recursive
allFiles() Returns just the files contained in this folder Optionally recursive

Common folder locations

API Description Notes
Folder.current() The process’ current working folder
Folder.userHomeFolder() User’s home folder
Folder.userDocumentsFolder() User’s documents folder
Folder.userDesktopFolder() User’s desktop folder
Folder.userCachesFolder() User’s caches folder
Folder.userDownloadsFolder() User’s downloads folder
Folder.userLibraryFolder() User’s library folder
Folder.userTemporaryFolder() User’s temporary folder
Folder.userTrashFolder() User’s trash folder macOS only

Location Query (macOS only)

LocationQuery is a basic wrapper around Spotlight search with a callback syntax

let q = LocationQuery()
q.searchScopes = [try Folder.userLibraryFolder()]
q.predicate = NSPredicate(format: "%K ENDSWITH '.txt'", NSMetadataItemFSNameKey)
q.start { foundItems in 
	// `foundItems` is an array of found metadata items
}
API Description
searchScopes The search scopes for the query (URL, String or Folder)
predicate The query predicate (Syntax)
start() Start the query, providing a completion handler to receive the results
stop() Stop a running query

License

MIT License

Copyright (c) 2023 Darren Ford

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

GitHub

View Github