XAttr

3.0.0

Extended Attribute handlers for URL and FileHandle objects, for iOS, macOS, watchOS and tvOS. Written in Swift!
jozefizso/swift-xattr

What's New

XAttr v3.0.0

2023-04-04T12:18:17Z

Manage extended attributes on files.

Changes

  • Project targets platforms supported by Xcode 14.2 on macOS 11 with Swift 5.7.
  • Added support for FilePath objects
  • NSURL was replaced by modern URL class
  • NSData was replaced by modern Data class

Usage

Add dependency to this package with majorVersion set to 3:

// Package.swift
import PackageDescription

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

XAttr

XAttr makes working with Extended Attributes 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!

Works with iOS, macOS, watchOS and tvOS.

For more info on Darwin's extended attribute APIs – which underlie this module – see Apple's man pages for listxattr, getxattr, setxattr, and removexattr.

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.
XAttr is a fork of Foundation-XAttr repository.

Copyright (c) 2016, Justin Pawela and contributors Copyright 2023 Cisco Systems, Inc.

Description

  • Swift Tools 5.7.0
View More Packages from this Author

Dependencies

Last updated: Wed Sep 11 2024 23:12:33 GMT-0900 (Hawaii-Aleutian Daylight Time)