/ 
Mac-Finder-Tags-0.02
River stage zero No dependents
/ Mac::Finder::Tags

NAME

Mac::Finder::Tags - Access macOS file tags (aka Finder labels)

VERSION

version 0.02

SYNOPSIS

my $ft = Mac::Finder::Tags->new();

# optional caching of all tagged files on startup
my $ft = Mac::Finder::Tags->new( caching => 1 );

# manually choose an implementation variant
my $ft = Mac::Finder::Tags->new( impl => 'mdls' );
my $ft = Mac::Finder::Tags->new( impl => 'xattr' );

# read tags from a file
my @tags = $ft->get_tags( $path );

# obtain tag details
my $name  = $tag->name;
my $color = $tag->color;
my $flags = $tag->flags;  # Finder label flags (numeric color code)
my $emoji = $tag->emoji;  # an Emoji approximating the color
my $is_legacy  = $tag->legacy_label;   # legacy Finder label
my $is_guessed = $tag->color_guessed;  # color is uncertain or
                                       # undetermined (mdls only)

# modify tags of a file
my $tag1 = $ft->tag( 'Important', 'orange' );
my $tag2 = $ft->tag( 'Client 276' );
$ft->set_tags( $path, @tags );
$ft->add_tags( $path, @tags );
$ft->remove_tags( $path, @tags );

# list all tags defined on the system
my @tags = $ft->all_tags();

# search entire system for files by tag
my @files = $ft->find_files_all( @tags );
my @files = $ft->find_files_any( @tags );

DESCRIPTION

This class offers methods to read and write macOS file system tags (the feature that replaced Mac OS Finder labels from OS X 10.9).

This software has pre-release quality. There is little documentation and no schedule for further development.

PERFORMANCE CONSIDERATIONS

The implementation based on mdls is much faster than the one based on xattr. However, mdls doesn't provide the color of tags for files that have multiple tags. This issue is mitigated to some extent when caching is enabled.

When caching is enabled, all tags on the entire system will be cached using mdfind at object creation time (however, files in locations not indexed by Spotlight are skipped). get_tags() will then only perform lookups in this cache, which is extremely fast. You should consider caching whenever you intend to look up more than maybe a hundred or so files; however, if your system has an extremely large number of tagged files or a large number of different tags, cache creation may cause a significant delay. You may wish to run your own performance tests for your environment.

By default, this module will use mdls when caching is disabled, and xattr when caching is enabled (in which case the speed difference doesn't matter as much).

BUGS

The semantics of tags without color (legacy Finder labels flag 0) and tags with no defined color (because it is undetermined or unknown) are not yet clearly differentiated.

The following methods are unimplemented in this version:

  • add_tags

  • set_tags

  • find_files_all

  • find_files_any

  • remove_tags

This software may not work on other filesystems than HFS+ or APFS. It has not been tested on all macOS versions.

AUTHOR

Arne Johannessen <ajnn@cpan.org>

If you contact me by email, please make sure you include the word "Perl" in your subject header to help beat the spam filters.

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022-2023 by Arne Johannessen.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.