jozefizso/swift-xattr

XAttr makes working with [Extended Attributes][wiki-xattr] a natural part of Foundation. Both `NSURL` and `NSFileHandle` objects gain the ability to read and write extended attributes using an API that fits right in with Cocoa. Add the power of metadata to your app!

Example

Here's a simple example of working with extended attributes using a file URL:

import XAttr

let myURL = URL(fileURLWithPath: "/path/to/file")

let data = "value".data(using: .utf8)!

// Set an attribute
try myURL.setExtendedAttribute(name: "com.example.attribute", value: data)
// List attributes
let names = try myURL.extendedAttributeNames()
// Get an attribute's value
let value = try myURL.extendedAttributeValue(forName: "com.example.attribute")
// Remove an attribute
try myURL.removeExtendedAttribute(forName: "com.example.attribute")

// Set multiple attributes
try myURL.setExtendedAttributes(attrs: ["com.example.attribute1": data, "com.example.attribute2": data])
// Get multiple attributes' values (all available)
let attrs = try myURL.extendedAttributeValues(forNames: nil)
// Remove multiple attributes (all)
try myURL.removeExtendedAttributes(forNames: nil)

Installation

Requires Swift 5.7.

Swift Package Manager

Add XAttr as a dependency to your project:

// Package.swift

import PackageDescription

let package = Package(
    name: "YourProjectName",
    dependencies: [
        .package(url: "https://github.com/jozefizso/swift-xattr", majorVersion: 3),
    ]
)

Usage

XAttr is easy to use. This section contains the all the basic information required. Be sure to check out the Quick Help in Xcode for more detail.

Methods

The following methods are available to both URL and FileHandle objects:

Retrieving an Attribute's Value

extendedAttributeValue(forName: String, options: XAttrOptions = []) throws -> Data

Retrieving Multiple Attributes' Values

extendedAttributeValues(forNames: [String]?, options: XAttrOptions = []) throws -> [String: Data]

Supply a list of names to retrieve, or nil to retrieve all available attributes.

Setting an Attribute's Value

setExtendedAttribute(name: String, value: Data, options: XAttrOptions = []) throws

Setting Multiple Attributes' Values

setExtendedAttributes(attrs: [String: Data], options: XAttrOptions = []) throws

Supply a dictionary of name:value pairs to be set on the target.

Listing Attribute Names

extendedAttributeNames(options: XAttrOptions = []) throws -> [String]

Removing an Extended Attribute

removeExtendedAttribute(forName: String, options: XAttrOptions = []) throws

Removing Multiple Extended Attributes

removeExtendedAttributes(forNames: [String]?, options: XAttrOptions = []) throws

Supply a list of names to remove, or nil to remove all existing attributes.

Options

XAttrOptions provides the following options:

| Option | Description | Get | Set | List | Remove | | ----------------- | ---------------------------------------------------- | :-: | :-: | :--: | :----: | | NoFollow | Do not follow symbolic links. | x | x | x | x | | CreateOnly | Fail if the named attribute already exists. | | x | | | | ReplaceOnly | Fail if the named attribute does not already exist. | | x | | | | ShowCompression | Show or remove HFS+ compression extended attributes. | x | | x | x |

Note: If neither CreateOnly nor ReplaceOnly are specified, the attribute will be created/updated regardless of its current status.

Errors

An NSError will be thrown if the system is not able to get/set/list/remove an extended attribute. The error will have the Foundation built-in domain NSPOSIXErrorDomain. The error's code property will represent the POSIX error code reported by the system, and the error's localizedDescription property will contain an explanation of the error.

Additionally, if the system was able to retrieve an attribute's name, but was not able to decode it, an NSError with the Foundation built-in domain NSCocoaErrorDomain and code NSFileReadInapplicableStringEncodingError will be thrown.

Finally, if an error is encountered while getting/setting/removing multiple extended attributes, the specific attribute that caused the error will be named in the error's userInfo dictionary, at the key ExtendedAttributeNameKey.

License

XAttr is licensed under the permissive [ISC License][license]. XAttr is a fork of [Foundation-XAttr][upstream] repository.

[wiki-xattr]: https://en.wikipedia.org/wiki/Extended_file_attributes [man-listxattr]: https://developer.apple.com/library/ios/documentation/System/Conceptual/ManPages_iPhoneOS/man2/listxattr.2.html [man-getxattr]: https://developer.apple.com/library/ios/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getxattr.2.html [man-setxattr]: https://developer.apple.com/library/ios/documentation/System/Conceptual/ManPages_iPhoneOS/man2/setxattr.2.html [man-removexattr]: https://developer.apple.com/library/ios/documentation/System/Conceptual/ManPages_iPhoneOS/man2/removexattr.2.html [license]: LICENSE.txt [upstream]: https://github.com/overbuilt/foundation-xattr

Package Metadata

Repository: jozefizso/swift-xattr

Default branch: main

README: README.md