package Mac::Pasteboard;

use 5.006002;

use strict;
use warnings;

use Carp;
use Exporter;

our @ISA = qw{ Exporter };

use constant CAN_USE_UNICODE	=> "$]" >= 5.008004;

BEGIN {
    # Not
    # use if CAN_USE_UNICODE, 'Encode'
    # because that does an import.
    CAN_USE_UNICODE
	and require Encode;
}

BEGIN {
    $ENV{DEVELOPER_DEBUG} and Carp->import ('verbose');
}

use constant CODE_REF	=> ref sub {};

{
    my @const = qw{
        defaultFlavor defaultEncode
	kPasteboardClipboard kPasteboardFind kPasteboardUniqueName
	badPasteboardSyncErr badPasteboardIndexErr badPasteboardItemErr
	    badPasteboardFlavorErr duplicatePasteboardFlavorErr
	    notPasteboardOwnerErr noPasteboardPromiseKeeperErr
	kPasteboardModified kPasteboardClientIsOwner
	kPasteboardFlavorNoFlags kPasteboardFlavorSenderOnly
	    kPasteboardFlavorSenderTranslated
	    kPasteboardFlavorNotSaved
	    kPasteboardFlavorRequestOnly
	    kPasteboardFlavorSystemTranslated
	    kPasteboardFlavorPromised
	};
    my @funcs = qw{
	pbcopy pbcopy_find
	pbencode pbencode_find
	pbflavor pbflavor_find
	pbpaste pbpaste_find
    };

    our @EXPORT_OK = (@const, @funcs, qw{coreFoundationUnknownErr});

    our %EXPORT_TAGS = (
	all => \@EXPORT_OK,
	const => \@const,
    );

    # We have a functional interface, and at this point no longer
    # exporting it by default would be a change in the public
    # interface. So we disable Perl::Critic.
    our @EXPORT = @funcs;	## no critic (ProhibitAutomaticExportation)
}

our $VERSION = '0.014_01';
our $XS_VERSION = $VERSION;
our $ALPHA_VERSION = $VERSION;
$VERSION =~ s/_//g;

require XSLoader;
XSLoader::load( 'Mac::Pasteboard', $XS_VERSION);

# This global and its associated environment variable are UNDOCUMENTED
# and subject to change or retraction without notice.
our $USE_PBCOPY = $ENV{MAC_PASTEBOARD_USE_PBCOPY};

BEGIN {
    eval {
	require Scalar::Util;
	Scalar::Util->import (qw{dualvar});
	1;
    } or do {
	*dualvar = sub {$_[0]};
    };

    # Mac::Errors is optional. We load it by file name to try to avoid
    # prereq_matches_use problems in the Kwalitee Game.
    eval {	## no critic (RequireCheckingReturnValueOfEval)
##	require Mac::Errors;	# Optional
	require 'Mac/Errors.pm';	## no critic (RequireBarewordIncludes)
	1;
    };
}

my %attr = (
    default_flavor	=> 1,	# read/write
    encode	=> 1,	# read/write
    fatal => 1,		# read/write
    id => sub {		# read/write. This is the mutator.
	if (defined $_[2]) {
	    if ($_[2] eq 'undef') {
		$_[2] = undef;
	    } else {
		$_[2] =~ m/\D/
		    and croak "The $_[1] attribute must be numeric or undef";
	    }
	}
	$_[2];
    },
    missing_ok => 1,	# read/write
    name => 0,		# read only
    requested_name => 0, # read only
    status => sub {	# read/write. This is the mutator.
	$_[2] =~ m/^[+\-]?\d+$/
	    or croak "Status value must be an integer";
	_error ($_[2]);
    },
);

my %static = (
    fatal => 1,
);

sub new {
    my ( $class, @arg ) = @_;
    my $name = @arg % 2 ? shift @arg : kPasteboardClipboard();
    defined $name or $name = kPasteboardClipboard();
    $ENV{DEVELOPER_DEBUG}
	and warn __PACKAGE__, "->new() creating $name";
    my $self = bless {
	default_flavor	=> defaultFlavor(),
	encode		=> defaultEncode(),
	fatal		=> 1,
	id		=> undef,
	missing_ok	=> 0,
	name		=> $name,
	requested_name	=> $name,
    }, ref $class || $class;
    @arg and $self->set( @arg );
    my ($status, $pbref, $created_name) = xs_pbl_create ($self->{name});
    __PACKAGE__->_check ($status) and return;
    $created_name and $self->{name} = $created_name;
    $self->{pbref} = $pbref;
    $self->{status} = $static{status};
    return $self;
}

sub clear {
    my ($self) = @_;
    return $self->_check (xs_pbl_clear ($self->{pbref}));
}

sub clone {
    my ($self) = @_;
    my $clone = {%$self};	# Works as long as we're a simple hash.
    if (defined (my $pbref = $self->{pbref})) {
	xs_pbl_retain ($pbref);
    }
    return bless $clone, ref $self;
}

sub copy {
    my ($self, $data, $flavor, $flags) = @_;
    if ( $USE_PBCOPY ) {
	my @arg;
	kPasteboardFind() eq $self->get( 'requested_name' )
	    and push @arg, qw{ -pboard find };
	open my $fh, '|-', 'pbcopy', @arg,
	    or croak "Unable to open pipe to pbcopy: $!";
	# FIXME this branch of the condidion is to go away. If I need it
	# to work in the interim I need to import _my_binmode from
	# inc/My/Module/Test.pm so I can properly encode the data.
	print { $fh } $data;
	close $fh;
	return $? ? coreFoundationUnknownError() : !1;
    } else {
	defined $flavor
	    and $flavor ne ''
	    or $flavor = $self->{default_flavor};
	defined $flags or $flags = kPasteboardFlavorNoFlags ();
	return $self->_check (
	    xs_pbl_copy (
		$self->{pbref},
		$self->_xlate( encode => $data, $flavor ),
		( defined $self->{id} ? $self->{id} : 1 ),
		$flavor,
		$flags,
	    )
	);
    }
}

{
    my %encoding = (
	'public.utf8-plain-text'	=> 'UTF-8',
	'public.utf16-plain-text'	=> 'UTF-16LE',
	'public.utf16-external-plain-text'	=> 'UTF-16',
    );

    sub flavor_encoding {
	my ( $self, $flavor ) = @_;
	defined $flavor
	    and $flavor ne ''
	    or $flavor = $self->get( 'default_flavor' );
	return $encoding{$flavor};
    }
}

sub flavors {
    my ($self, $conforms_to) = @_;
    my ($status, @data) = xs_pbl_all (
	$self->{pbref}, $self->{id}, 0, $conforms_to);
    $self->_check ($status) and return;
    return wantarray ? @data : \@data;
}

{
    my %flavors = (
	kPasteboardFlavorSenderOnly => kPasteboardFlavorSenderOnly (),
	kPasteboardFlavorSenderTranslated =>
		kPasteboardFlavorSenderTranslated (),
	kPasteboardFlavorNotSaved => kPasteboardFlavorNotSaved (),
	kPasteboardFlavorRequestOnly => kPasteboardFlavorRequestOnly (),
	kPasteboardFlavorSystemTranslated =>
		kPasteboardFlavorSystemTranslated (),
	kPasteboardFlavorPromised => kPasteboardFlavorPromised (),
    );
    sub flavor_flag_names {
	my $flavor = pop;
	my @rslt;
	foreach my $name (sort keys %flavors) {
	    $flavor & $flavors{$name} or next;
	    push @rslt, $name;
	}
	@rslt or push @rslt, 'kPasteboardFlavorNoFlags';
	return wantarray ? @rslt : join ', ', @rslt;
    }
}

sub flavor_tags {
    my $flavor = pop;
    my $hash = xs_pbl_uti_tags ($flavor);
    return wantarray ? %$hash : $hash;
}

sub get {
    my ($self, $name) = @_;
    exists $attr{$name}
	or croak "No such attribute as '$name'";
    return ref $self ? $self->{$name} : $static{$name};
}

sub paste {
    my ($self, $flavor) = @_;
    defined $flavor
	and $flavor ne ''
	or $flavor = $self->{default_flavor};
    my ($status, $data, $flags) = xs_pbl_paste (
	$self->{pbref}, $self->{id}, $flavor );
    $self->_check ($status);
    $data = $self->_xlate( decode => $data, $flavor );
    return wantarray ? ($data, $flags) : $data;
}

sub paste_all {
    my ($self, $conforms_to) = @_;
    my ($status, @data) = xs_pbl_all (
	$self->{pbref}, $self->{id}, 1, $conforms_to);
    $self->_check ($status) and return;
    foreach my $datum ( @data ) {
	$datum->{data} = $self->_xlate(
	    decode => $datum->{data}, $datum->{flavor} );
    }
    return wantarray ? @data : \@data;
}

sub pbcopy (;$$$) {		## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardClipboard ();
    goto &_pbcopy;
}

sub pbcopy_find (;$$$) {	## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardFind ();
    goto &_pbcopy;
}

sub pbencode (;$) {		## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardClipboard ();
    goto &_pbencode;
}

sub pbencode_find (;$) {	## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardFind ();
    goto &_pbencode;
}

sub pbflavor (;$) {		## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardClipboard ();
    goto &_pbflavor;
}

sub pbflavor_find (;$) {	## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardFind ();
    goto &_pbflavor;
}

sub pbpaste (;$) {		## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardClipboard ();
    goto &_pbpaste;
}

sub pbpaste_find (;$) {		## no critic (ProhibitSubroutinePrototypes)
    unshift @_, kPasteboardFind ();
    goto &_pbpaste;
}

sub set {
    my ($self, @args) = @_;
    my $hash = ref $self ? $self : \%static;
    while (@args) {
	my $name = shift @args;
	exists $attr{$name}
	    or croak "No such attribute as '$name'";
	$attr{$name}
	    or croak "Attribute '$name' is read-only";
	my $ref = ref $attr{$name};
	if ( CODE_REF eq $ref ) {
	    $hash->{$name} = $attr{$name}->($self, $name, shift @args);
	} else {
	    $hash->{$name} = shift @args;
	}
    }
    return $self;
}

sub synch {
    my ($self) = @_;
    return xs_pbl_synch ($self->{pbref});
}

{
    my %flags = (
	kPasteboardModified => kPasteboardModified (),
	kPasteboardClientIsOwner => kPasteboardClientIsOwner (),
    );
    sub synch_flag_names {
	my $flag = pop;
	my @rslt;
	foreach my $name (sort keys %flags) {
	    $flag & $flags{$name} or next;
	    push @rslt, $name;
	}
	return wantarray ? @rslt : join ', ', @rslt;
    }
}

{
    my %errtxt = (
	0 => '',
	badPasteboardSyncErr() => {
	    sym => 'badPasteboardSyncErr',
	    desc => 'The pasteboard has been modified and must be synchronized before use',
	},
	badPasteboardIndexErr() => {
	    sym => 'badPasteboardIndexErr',
	    desc => 'The specified pasteboard item index does not exist',
	},
	badPasteboardItemErr() => {
	    sym => 'badPasteboardItemErr',
	    desc => 'The item reference does not exist',
	},
	badPasteboardFlavorErr() => {
	    sym => 'badPasteboardFlavorErr',
	    desc => 'The item flavor does not exist',
	},
	coreFoundationUnknownErr() => {
	    type => 'Mac OS',
	    sym => 'coreFoundationUnknownErr',
	    desc => 'The unknown error',
	},
	duplicatePasteboardFlavorErr() => {
	    sym => 'duplicatePasteboardFlavorErr',
	    desc => 'The item flavor already exists',
	},
	notPasteboardOwnerErr() => {
	    sym => 'notPasteboardOwnerErr',
	    desc => 'The application did not clear the pasteboard before attempting to add flavor data',
	},
	noPasteboardPromiseKeeperErr() => {
	    sym => 'noPasteboardPromiseKeeperErr',
	    desc => 'The application attempted to add promised data without previously registering a promise keeper callback',
	},
    );

    sub _error {
	my $val = pop;
	if (!$val) {
	    return dualvar (0, '');
	} elsif (my $err = $Mac::Errors::MacErrors{$val}) {
	    return dualvar ($val,
		sprintf ('Mac OS error %d (%s): %s',
		    $err->number, $err->symbol, $err->description));
	} elsif (exists $errtxt{$val}) {
	    return dualvar ($val,
		sprintf ('%s error %d (%s): %s',
		    $errtxt{$val}{type} || 'Pasteboard', $val,
		    $errtxt{$val}{sym}, $errtxt{$val}{desc}));
	} else {
	    return dualvar ($val, "Unknown error ($val)");
	}
    }

    sub _check {
	my ($self, $error) = @_;
	my $hash = ref $self ? $self : \%static;
	$hash->{status} = my $dual = _error ($error);
	if ($error == -25133 && $hash->{missing_ok}) {
	    return $dual;
	} elsif ($error && $hash->{fatal}) {
	    croak $dual;
	} else {
	    return $dual;
	}
    }
}

sub _xlate {
    my ( $self, $function, $data, $flavor ) = @_;
    CAN_USE_UNICODE
	or return $data;
    $self->get( 'encode' )
	or return $data;
    defined( my $encoding = $self->flavor_encoding( $flavor ) )
	or return $data;
    my $code = Encode->can( $function )
	or confess "Programming error - Encode can not $function()";
    return $code->( $encoding, $data );
}

{

    my %cache;	# So we don't have to keep instantiating pasteboards.

    sub _pbobj {
	my ( $name ) = @_;
	return $cache{$name} ||= __PACKAGE__->new( $name )->set(
	    id => undef,	# should be undef anyway, but ...
	    missing_ok => 1,	# no exception for missing data ...
	);
    }

}

sub _pbcopy {
    my ( $name, @args ) = @_;
    my $pb = _pbobj( $name );
    @args or push @args, $_;
    $pb->clear ();
    return $pb->copy (@args);
}

sub _pbencode {
    my ( $name, $encode ) = @_;
    my $pb = _pbobj( $name );
    my $old = $pb->get( 'encode' );
    defined $encode
	and $encode ne ''
	and $pb->set( encode => $encode );
    return $old;
}

sub _pbflavor {
    my ( $name, $flavor ) = @_;
    my $pb = _pbobj( $name );
    my $old = $pb->get( 'default_flavor' );
    defined $flavor
	and $flavor ne ''
	and $pb->set( default_flavor => $flavor );
    return $old;
}

sub _pbpaste {
    my ( $name, @args ) = @_;
    return _pbobj( $name )->paste( @args );
}

sub DESTROY {
    my ($self) = @_;
    $self->{pbref} and xs_pbl_release ($self->{pbref});
    return;
}

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__

=head1 NAME

Mac::Pasteboard - Manipulate Mac OS X clipboards/pasteboards.

=head1 SYNOPSIS

To acquire text from the system clipboard, replacing it with your own:

  use Mac::Pasteboard;
  my $old_text = pbpaste();
  pbcopy ("Hello, sailor!\n");

or equivalently, using the object-oriented interface,

  use Mac::Pasteboard;
  my $pb = Mac::Pasteboard->new ();
  my $old_text = $pb->paste ();
  $pb->clear ();
  $pb->copy ("Hello, sailor!\n");

=head1 CAVEATS

Beginning with Mac OS 10.6 Snow Leopard, pasteboards could contain
multiple items. Until I upgrade, this package can only access the first
item. If your interest is in writing a droplet (that is, an application
that processes files which are dropped on it), see
L<the droplet documentation|Mac::Pasteboard::Droplet>.

This module is in general ignorant of the semantics implied by the
system-declared flavors, and makes no attempt to enforce them. In
plainer English, it is up to the user of this module to ensure that the
specified flavor is actually appropriate to the data it is used to
describe. For example, if you store some data on the pasteboard as
flavor 'public.jpeg', it is up to you to make sure that the data are, in
fact, a valid JPEG image.

On the other hand, it is (or at least may be) convenient to get the text
types encoded and decoded properly off the pasteboard. This is what the
L<encode|/encode (boolean)> attribute is for. It is false by default
because it appears not to work as one would hope under older versions of
Mac OS. It also does not cover C<com.apple.traditional-mac-plain-text>
because the encoding of this appears to change, and I have been unable
to find documentation (or to figure out on my own) which encoding to
expect.  B<Caveat user>.

Any functionality that involves any character set other than the
system's native character set is disabled on versions of Perl before
5.8.4.

=head1 DESCRIPTION

This XS module accesses Mac OS X pasteboards, which can be thought of as
clipboards with bells and whistles. Under Mac OS X, the system clipboard
is simply a special case of a pasteboard. In the following
documentation, 'clipboard' refers to the system clipboard, and
'pasteboard' refers to pasteboards in general.

This module uses the Pasteboard interface, which was introduced in Mac
OS 10.3 (a.k.a. 'Panther'), so it requires Mac OS 10.3 or better to run.

The simple case of placing plain text onto and reading it from the
system clipboard is accomplished by subroutines pbcopy() and pbpaste()
respectively. These correspond roughly to the command-line executables
of the same name, and are exported by default. If this is all you are
interested in, you can stop reading here. The rest of this section
describes the bells and whistles associated with a Mac OS X pasteboard.

A Mac OS X pasteboard contains zero or more data items, each of which is
capable of holding one or more flavors of data. The system defines a
couple pasteboards, including the system clipboard, named
'com.apple.pasteboard.clipboard'. The system clipboard is the default
taken if new() is called without arguments.

Data items are identified by an item id which is provided by the creator
of the item, and which (the documentation says) should only be
interpreted by the creator. Item flavors may be duplicated between items
but not within items. The item L<id|/id (integer)> is an attribute of
the Mac::Pasteboard object, with the default chosen so that you should
not need to worry about it unless you explicitly want more than one item
on a pasteboard.

A flavor is a Uniform Type Identifier which describes the semantics of
the data with which it is associated. In practice any string can be
used, but you probably want to stick to the system-declared flavors if
it is important to you that other software understand your data. The
L</SEE ALSO> section contains a link to a reference for Uniform Type
Identifiers which includes a description of all the system-declared
UTIs. All methods (or subroutines) that place data on or retrieve data
from a pasteboard take the flavor as an argument. This argument defaults
to 'com.apple.traditional-mac-plain-text'.

Data may be placed on a pasteboard only by the owner of that pasteboard.
Ownership is acquired by clearing the pasteboard. In general, the owner
of a pasteboard may either place data directly on to it, or place a
promise of data to be generated when the data are actually requested.
This module does not support placing a promise onto the pasteboard.
It will retrieve data promised by another application, but can not
specify a paste location for that data; it is simply returned verbatim.

=head1 METHODS

Some of the methods are documented as returning a status. This status is
a dualvar, whose numeric value is the Mac OS error encountered, and
whose string value is a description of the error similar to that
produced by the Mac::Error 'macerror' script. Errors other than the
documented pasteboard error will be described as 'Unknown error' unless
Mac::Error is installed and the error is known to that module.

Note, however, that by default the L<fatal|/fatal (boolean)> attribute
is true, which means an error will result in an exception. If
L<fatal|/fatal (boolean)> is false, the status will be false for success
and true for failure.

The following methods are provided:

=head2 $pb = Mac::Pasteboard->new ($name)

This method creates a new pasteboard object, connected to the pasteboard
of the given name, creating the pasteboard if necessary. If called with
no argument, you get the system clipboard, a.k.a.
L</kPasteboardClipboard>, a.k.a.  'com.apple.pasteboard.clipboard'.
Passing undef to new() is B<not> equivalent to calling it with no
arguments at all, since undef is the encoding for
L</kPasteboardUniqueName>.

Note that an error in creating a new pasteboard B<will> cause an
exception, since the L<fatal|/fatal (boolean)> attribute defaults to 1.
If you want to get a status back, you will need to call

 Mac::Pasteboard->set (fatal => 0);

If the attempt to instantiate an object fails, the status is available
from

 Mac::Pasteboard->get ('status');

Starting with version C<0.012_01> you can pass desired attributes as
arguments -- the same name/value pairs that get passed to C<set()>.
These come after the pasteboard name if any, but there is no need to
specify an explicit C<undef> if you want to default the name but specify
attributes; C<new()> will figure it out based on whether the number of
arguments is odd or even.

=head2 $status = $pb->clear ()

This method clears the pasteboard. You must clear the pasteboard before
adding data to it.

=head2 $clone = $pb->clone ()

This method clones the pasteboard object.

=head2 $status = $pb->copy ($data, $flavor, $flags)

This method puts the given data on the pasteboard, identifying it as
being of the given flavor, and assigning the given pasteboard flags,
which are the bitwise 'or' (a.k.a. the '|' operator) of the individual
L<flavor flags|/Flavor flags>. If $flags is omitted,
L<kPasteboardFlavorNoFlags|/kPasteboardFlavorNoFlags> is used. If
$flavor is omitted, undefined, or the empty string, the L<default
flavor|/defaultFlavor> is used.

The pasteboard is B<not> cleared prior to this operation; any other data
of other flavors remain on the pasteboard.

If the L<id|/id (integer)> attribute is undef, the data are placed in
the item whose id is 1. Otherwise, the data are placed in the item with
the given id.  It is an error to attempt to place a given flavor in a
given item more than once.

=head2 $encoding = $pb->flavor_encoding( $flavor );

This method returns the Unicode encoding of the given flavor, or the
default flavor if no flavor is given. If the encoding is unknown, it
returns C<undef>.

You can actually call this as a static method, but if you do so you
B<must> provide a defined and non-empty value for C<$flavor>.

In fact, this is driven by a table of flavors for which the flavors are
known. This table is given under L<encode|/encode (boolean)>, below.

=head2 @names = $pb->flavor_flag_names ($flags)

This method (or subroutine) interprets its last argument as flavor
flags, and returns the names of the flags set. If no recognized flags
are set, you get an empty list.

If called in scalar context you get back the names joined with ', ', or
'kPasteboardFlavorNoFlags' if there are none.

=head2 %tags = $pb->flavor_tags ($flavor)

This method (or subroutine) interprets its last argument as a flavor
name, and returns the preferred tags associated with the flavor in a
hash. The hash will have zero or more of the following keys:

 extension: the preferred file name extension for the flavor;
 mime: the preferred MIME type for the flavor;
 pboard: the preferred NSPBoard type for the flavor;
 os: the preferred 4-byte Mac OS document type for the flavor.

If called in scalar context, you get back a reference to the hash.

=head2 @flavors = $pb->flavors ($conforms_to)

This method returns the list of data flavors conforming to the given
flavor currently on the pasteboard. If $conforms_to is omitted or undef,
you get all flavors. If the L<id|/id (integer)> attribute is defined,
you get only flavors from the corresponding pasteboard item; otherwise
you get all conforming flavors. If you turn off the L<fatal|/fatal
(boolean)> attribute, you will get an empty list if an error occurs, and
you will need to check the L<status|/status (dualvar)> attribute so see
if the operation actually succeeded.

The return is a list of anonymous hashes, each containing the following
keys:

 flags: the flavor flags;
 flavor: the flavor name;
 id: the pasteboard item ID.

If called in scalar context, you get a reference to the list.

The L</SEE ALSO> section has a link to the I<Uniform Type Identifiers
Overview>, which deals with the notion of type conformance.

=head2 $value = $pb->get ($name)

This method returns the value of the given L<attribute|/ATTRIBUTES>. An
exception is thrown if the attribute does not exist.

This method can also be called statically (that is, as
Mac::Pasteboard->get ($name)), in which case it returns the static value
of the attribute, if any.

=head2 ($data, $flags) = $pb->paste ($flavor)

If the L<id|/id (integer)> attribute is defined, this method returns the
data of the given flavor from that pasteboard id, and the associated
L<flavor flags|/Flavor flags>; otherwise it returns the data from the
last instance of that flavor found, and the associated flavor flags. If
no such flavor data is found, an exception is thrown if the
L<missing_ok|/missing_ok (boolean)> attribute is false, or undef is
returned for $data if L<missing_ok|/missing_ok (boolean)> is true.

You test the $flags value for individual flags by using the bitwise
'and' operator ('&'). For example:

 $flags & kPasteboardFlavorSystemTranslated
   and print "This data provided by Translation Services\n";

If called in scalar context, you get $data.

=head2 @data = $pb->paste_all ($conforms_to)

This method returns all flavors of data on the pasteboard which conform
to the given flavor. If $conforms_to is omitted or undef, all flavors of
data are returned. If the L<id|/id (integer)> attribute is defined, only
data from that pasteboard item are returned; otherwise everything
accessible is returned.

The return is a list of anonymous hashes, each having the following
keys:

 data: the flavor data;
 flags: the flavor flags;
 flavor: the flavor name;
 id: the pasteboard item ID.

If called in scalar context, you get a reference to the list.

The L</SEE ALSO> section has a link to the I<Uniform Type Identifiers
Overview>, which deals with the notion of type conformance.

=head2 pbcopy ($data, $flavor, $flags)

This convenience subroutine (B<not> method) clears the system clipboard
and then copies the given data to it. All three arguments are optional
(the prototype being (;$$$). If $data is undef, the value of $_ is used.
If $flavor is undef, the L<default flavor|/defaultFlavor> is used. If
$flags is undef, L<kPasteboardFlavorNoFlags|/kPasteboardFlavorNoFlags>
is used.

In other words, this subroutine is more-or-less equivalent to the
'pbcopy' executable.

=head2 pbcopy_find ($data, $flavor, $flags)

This convenience subroutine (B<not> method) clears the 'find' pasteboard
and then copies the given data to it. All three arguments are optional
(the prototype being (;$$$). If $data is undef, the value of $_ is used.
If $flavor is undef, the L<default flavor|/defaultFlavor> is used. If
$flags is undef, L<kPasteboardFlavorNoFlags|/kPasteboardFlavorNoFlags>
is used.

In other words, this subroutine is more-or-less equivalent to

 $ pbcopy -pboard find

=head2 $encode = pbencode ();

=head2 $old_encode = pbencode ( $new_encode );

this convenience subroutine (b<not> method) returns the encode setting
for the system pasteboard. if the argument is defined and not c<''>, the
argument becomes the new encode setting and the old encode setting is
returned.

=head2 $encode = pbencode_find ();

=head2 $old_encode = pbencode_find ( $new_encode );

this convenience subroutine (b<not> method) returns the encode setting
for the 'find' pasteboard. if the argument is defined and not c<''>, the
argument becomes the new encode setting and the old encode setting is
returned.

=head2 $default_flavor = pbflavor ();

=head2 $old_default_flavor = pbflavor ( $new_default_flavor );

this convenience subroutine (b<not> method) returns the default data
flavor for the system pasteboard. if the argument is defined and not
c<''>, the argument becomes the new default flavor and the old default
flavor is returned.

=head2 $default_flavor = pbflavor_find ();

=head2 $old_default_flavor = pbflavor_find ( $new_default_flavor );

this convenience subroutine (b<not> method) returns the default data
flavor for the 'find' pasteboard. if the argument is defined and not
c<''>, the argument becomes the new default flavor and the old default
flavor is returned.

=head2 ($data, $flags) = pbpaste ($flavor)

This convenience subroutine (B<not> method) retrieves the given flavor
of data from the system clipboard, and its associated flavor flags. The
flavor is optional, the default being the L<default
flavor|/defaultFlavor>. If the given flavor is not found undef is
returned for $data.

The functionality is equivalent to calling paste() on an object whose
L<id|/id (integer)> attribute is undef.

If called in scalar context, you get $data.

In other words, this subroutine is more-or-less equivalent to the
'pbpaste' executable.

=head2 ($data, $flags) = pbpaste_find ($flavor)

This convenience subroutine (B<not> method) retrieves the given flavor
of data from the 'find' pasteboard, and its associated flavor flags. The
flavor is optional, the default being the L<default
flavor|/defaultFlavor>. If the given flavor is not found undef is
returned for $data.

The functionality is equivalent to calling paste() on an object whose
L<id|/id (integer)> attribute is undef.

If called in scalar context, you get $data.

In other words, this subroutine is more-or-less equivalent to

 $ pbpaste -pboard find

=head2 $pb = $pb->set ($name => $value ...)

This method sets the values of the given L<attributes|/ATTRIBUTES>. More
than one attribute can be set at a time. An exception is thrown if the
attribute does not exist, or if the attribute is read-only. The object
is returned, so that calls can be chained.

This method can also be called statically (that is, as
Mac::Pasteboard->set ($name => $value ...)). If an attribute does
something useful when set statically, its description will say so.
Setting other attributes statically is unsupported, at least in the
sense that the author makes no representation what will happen if you do
set them, and does not promise that whatever happens when you do this
will not change in the future.

=head2 $flags = $pb->synch ()

This method synchronizes the local copy of the pasteboard with the
global pasteboard, and returns the L<synchronization
flags|/Synchronization flags>. This B<should> be called on your behalf
when needed, but it is exposed because one of the flags returned says
whether the calling process owns the pasteboard.  For example:

 $pb->synch & kPasteboardClientIsOwner
     or $pb->clear ();

to take ownership of the pasteboard (by clearing it) if it is not
already owned by the process. Note that
L<kPasteboardClientIsOwner|/kPasteboardClientIsOwner> is not imported by
default.

=head2 @names = $pb->synch_flag_names ($flags)

This method (or subroutine) interprets its last argument as
synchronization flags (i.e. as the return from the synch() method), and
returns the names of the flags set. If none are set, you get an empty
list.

If called in scalar context you get back the names joined with ', ', or
an empty string if there are none, since there is no manifest constant
for synchronization flags that corresponds to
'kPasteboardFlavorNoFlags'.

=head1 ATTRIBUTES

The types of the attributes are specified in parentheses after their
names. Boolean attributes are interpreted in the Perl sense - that is,
C<undef>, C<0> and C<''> are false, and anything else is true.

This class supports the following attributes:

=head2 encode (boolean)

This attribute specifies whether or not certain flavors are to be
encoded into and decoded from the pasteboard. Supported flavors and the
encodings used are:

    public.utf8-plain-text           UTF-8
    public.utf16-plain-text          UTF-16LE
    public.utf16-external-plain-text UTF-16

Flavor C<com.apple.traditional-mac-plain-text> (the initial default
flavor) is not supported by this attribute because the normal encoding
is undocumented (ASCII? MacRoman? MacSomething depending on locale?).
When it has wide characters to handle it seems to get upgraded to
UTF-16LE, but how to tell when this is done is also undocumented.

The default value of this attribute is L<defaultEncode|/defaultEncode>.

=head2 default_flavor (string)

This attribute stores the name of the default flavor to use if a flavor
is not specified in the C<copy()> or C<paste()> call. The default value
of this attribute is C<defaultFlavor()>.

=head2 fatal (boolean)

If this attribute is true, any pasteboard error throws an exception. If
false, error codes are returned to the caller.

This attribute can be set statically, in which case it controls whether
static methods throw an exception on a pasteboard error. Currently, only
new() is affected by this; pbcopy() and friends are subroutines, not
static methods.

Setting this statically does B<not> affect the default value of this
attribute in an instantiated object.

The default is 1 (i.e. true).

=head2 id (integer)

This attribute supplies the id for data to be copied to or pasted from
the pasteboard. In addition to a non-negative integer, it can be set to
undef. See copy() and paste() for the effects of this attribute on their
action.  In most cases you will not need to change this.

The default is undef.

=head2 missing_ok (boolean)

If this attribute is true, paste() returns undef if the required flavor
is missing, rather than throwing an exception if 'fatal' is true. The
pbpaste() subroutine sets this true for the object it manufactures to
satisfy its request.

The default is 0 (i.e. false).

=head2 name (string, readonly)

This attribute reports the actual name assigned to the pasteboard. Under
Panther (Mac OS 10.3) it is the name passed to new (), or the name of
the system pasteboard if no name was passed in. Under Tiger (Mac OS
10.4) and above, the actual name is retrieved once the pasteboard is
created. If this name cannot be retrieved you get the same result as
under Panther.

This name may not be the name you used to create the
pasteboard, even if you used one of the built-in names. But unless you
created the pasteboard using name kPasteboardUniqueName, the name will
be equivalent. That is,

 my $pb1 = Mac::Pasteboard->new();
 my $pb2 = Mac::Pasteboard->new(
     $pb1->get('name'));

gives two handles to the same clipboard.

=head2 requested_name (string, readonly)

This attribute reports the name passed to C<new()>.

=head2 status (dualvar)

This attribute contains the status of the last operation. You can set
this with an integer; the dualvar will be generated.

The static attribute contains the status of the last static method to
operate on a pasteboard. Currently, this means the last call to new().

=head1 EXPORT

The pbcopy(), pbcopy_find(), pbpaste(), and pbpaste_find() subroutines
are exported by default. In addition, tag ':all' exports everything, and
tag ':const' exports all constants except those which must be exported
explicitly (currently only coreFoundationUnknownErr). Constants are also
accessible by &Mac::Pasteboard::constant_name. The following constants
are defined:

=head2 Error codes

=head3 badPasteboardFlavorErr

This constant represents the error number returned when a flavor is not
found on the pasteboard. It is not a dualvar -- it just represents the
number of the error, which is -25133.

=head3 duplicatePasteboardFlavorErr

This constant represents the error number returned when an attempt is
made to place in a pasteboard item a flavor that is already there.  It
is not a dualvar -- it just represents the number of the error, which is
-25134.

=head3 badPasteboardIndexErr

This constant represents the error number returned when the code indexes
off the end of the pasteboard. If you get it in use, it probably
represents a bug in this module, and should be reported as such. It is
not a dualvar -- it just represents the number of the error, which is
-25131.

=head3 badPasteboardItemErr

This constant represents the error number returned when the user
requests data from a non-existent item ID. It is not a dualvar -- it
just represents the number of the error, which is -25132.

=head3 badPasteboardSyncErr

This constant represents the error returned when the user tries to fetch
stale data from the pasteboard. Because this module is supposed to
synchronize before fetching, it represents either a bug or a race
condition. It is not a dualvar -- it just represents the number of the
error, which is -25130.

=head3 coreFoundationUnknownErr

This constant represents B<the> unknown error, not just B<an> unknown
error. One would think you would never get this from Apple's code, but
it appears that you will get this error if the caller does not have
access to the desktop. For example, you can get this error in a script
running over an ssh connection, or in a cron job.

B<This constant is not exported with the :const tag,> because there are
other places it could potentially come from. If you want it, you will
need to import it explicitly. It is not a dualvar -- it just represents
the number of the error, which is -4960.

=head3 noPasteboardPromiseKeeperErr

This constant represents the error returned when the user tries place
promised data on the pasteboard without first registering a promise
keeper callback. This package does not support promised data.
This constant is not a dualvar -- it just represents the number of the
error, which is -25136.

=head3 notPasteboardOwnerErr

This constant represents the error returned when the user tries place
data on the pasteboard without first becoming its owner by clearing it.
It is not a dualvar -- it just represents the number of the
error, which is -25135.

=head2 Flavor flags

=head3 kPasteboardFlavorNoFlags

This pasteboard flavor flag is really a value, to be used if no flags
are set.

=head3 kPasteboardFlavorNotSaved

This pasteboard flavor flag indicates that the flavor's data is
volatile, and should not be saved.

=head3 kPasteboardFlavorPromised

This pasteboard flavor flag indicates that the flavor's data is
promised. This module does not support creating promised data.

=head3 kPasteboardFlavorRequestOnly

This pasteboard flavor flag indicates that the flavor must be requested
explicitly; scanning for available flavors will not find it.

=head3 kPasteboardFlavorSenderOnly

This pasteboard flavor flag indicates that the flavor's data are only
available to the process that placed it on the pasteboard.

Oddly enough, the 'pbpaste' executable seems to be able to find such
data. But the Pasteboard Peeker demo application can not, so I am pretty
sure this module is working OK. Unfortunately I was unable to find the
source for pbpaste online, so I am unable to verify what's going on.

=head3 kPasteboardFlavorSenderTranslated

This pasteboard flavor flag indicates that the flavor's data has been
translated in some way by the process that placed it on the clipboard,
and it will not be saved by the Finder in clipping files.

=head3 kPasteboardFlavorSystemTranslated

This pasteboard flavor flag indicates that the flavor's data must be
translated by the Translation Manager. This flag cannot be set
programmatically, and the Finder will not save this data in clipping
files.

=head2 Pasteboard and flavor names

=head3 defaultFlavor

This constant represents the name of the default flavor,
'com.apple.traditional-mac-plain-text'.

=head3 kPasteboardClipboard

This constant represents the name of the system clipboard,
'com.apple.pasteboard.clipboard'.

=head3 kPasteboardFind

This constant represents the name of the find pasteboard,
'com.apple.pasteboard.find'.

=head3 kPasteboardUniqueName

This constant specifies that a unique name be generated for the
pasteboard. Under Mac OS 10.4 (Tiger) or above, the generated name will
be available in the L<name|/name (string, readonly)> attribute; under
Mac OS 10.3 (Panther), the generated name is unavailable, and the
L<name|/name (string, readonly)> attribute will be undef.

The value of this constant is documented as (CFStringRef) NULL, so it is
represented in Perl by undef.

=head2 Synchronization flags

=head3 kPasteboardClientIsOwner

This synchronization flag is true if the caller is the owner of the
pasteboard.

=head3 kPasteboardModified

This synchronization flag indicates that the pasteboard has been
modified since the last time this program accessed it, and the local
copy of the pasteboard has been synchronized.

=head2 Other Exports

=head3 defaultEncode

This constant specifies the default value of the C<encode> attribute.
This is true under macOS 10.15 Catalina and later, and false under
earlier versions.

=head1 BUGS

Please report bugs through
L<https://rt.cpan.org/Public/Dist/Display.html?Name=Mac-Pasteboard>,
L<https://github.com/trwyant/perl-Mac-Pasteboard/issues/>, or by mail to
the author.

=head1 SEE ALSO

The B<Clipboard> module by Ryan King will access text on the clipboard
under most operating systems. Under Mac OS X, it shells out to the
I<pbpaste> and I<pbcopy> executables.

The I<pbpaste> and I<pbcopy> executables themselves are available, and
described by their respective man pages.

The I<Pasteboard Manager Reference> is available online at
L<http://developer.apple.com/documentation/Carbon/Reference/Pasteboard_Reference/Reference/reference.html>.
See also the I<Pasteboard Manager Programming Guide> at
L<http://developer.apple.com/documentation/Carbon/Conceptual/Pasteboard_Prog_Guide/>.

The I<Uniform Type Identifiers Overview> is available online at
L<http://developer.apple.com/documentation/Carbon/Conceptual/understanding_utis/>.

=head1 AUTHOR

Thomas R. Wyant, III, F<wyant at cpan dot org>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2008, 2011-2021 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5.10.0. For more details, see the full text
of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=cut

# ex: set textwidth=72 :
