Mac::Growl - Perl module for registering and sending Growl Notifications on Mac OS X

  use Mac::Growl ':all';

  RegisterNotifications("MyPerlApp", \@allNotifications,
    \@defaultNotifications[, $iconOfApp]);

  PostNotification("MyPerlApp", $notificationName, $notificationTitle,
    $notificationDescription[, $sticky, $priority, $image_path]);

	use utf8;
	utf8::encode($string);

	require Encode;
	$string = Encode::encode('utf8', $string);

	require Encode;
	Encode::from_to($string, 'MacRoman', 'utf8');

	BEGIN { $Mac::Growl::base = 'Mac::Glue' }
	use Mac::Growl;

package Mac::Growl;

use strict;
use warnings;

our $VERSION = '0.67';

use base 'Exporter';
our @EXPORT = qw();
our @EXPORT_OK = qw(RegisterNotifications PostNotification);
our %EXPORT_TAGS = (all => \@EXPORT_OK);

#### we have various options here ...
#### in declining order of preference, we pick an implementation to use,
#### and stick with it.
our($base, $glue, $helper, $appkit, $encode);

# we could use gotos or something, but this is the most efficient and reliable
# way; we could also try to put all the implementations in one function, but
# that's just messy, and I'd rather have it be messy here than there. -- pudge
sub _Define_Subs {
	no warnings 'redefine';

	sub RegisterNotifications($$$;$);
	sub PostNotification($$$$;$$$);

	sub Foundation_RegisterNotifications($$$;$);
	sub Foundation_PostNotification($$$$;$$$);

	sub Glue_RegisterNotifications($$$;$);
	sub Glue_PostNotification($$$$;$$$);

	sub AppleScript_RegisterNotifications($$$;$);
	sub AppleScript_PostNotification($$$$;$$$);

	if ($base eq 'Foundation') {
		*RegisterNotifications = *Foundation_RegisterNotifications{CODE};
		*PostNotification      = *Foundation_PostNotification{CODE};
	} elsif ($base eq 'Mac::Glue') {
		*PostNotification      = *Glue_PostNotification{CODE};
		*RegisterNotifications = *Glue_RegisterNotifications{CODE};
	} else { # AppleScript
		*PostNotification      = *AppleScript_PostNotification{CODE};
		*RegisterNotifications = *AppleScript_RegisterNotifications{CODE};
	}

	sub _Fix_Glue_String(\$);
	sub _Fix_AppleScript_String(\$);
	sub _Fix_Encode(\$;$);
}

sub BEGIN {
	$encode = eval { require Encode; };
	$helper = 'GrowlHelperApp';

	if (!$base || $base eq 'Foundation') {
		eval 'require Foundation';
		if ($@) {
			$base = undef;
		} else {
			$base = 'Foundation';

			# load classes for images
			my $path = NSString->stringWithCString_('/System/Library/Frameworks/AppKit.framework');
			$appkit = NSBundle->alloc->init->initWithPath_($path);
			$appkit->load if $appkit;
			if ($appkit->isLoaded) {
				no strict 'refs';
				for my $class (qw(NSWorkspace NSImage)) {
					@{$class . '::ISA'} = 'PerlObjCBridge';
				}
			} else {
				undef $appkit;
			}
		}
	}

	if (!$base || $base eq 'Mac::Glue') {
		eval 'require Mac::Glue';
		if ($@) {
			$base = undef;
		} else {
			eval { $glue = Mac::Glue->new($helper) };
			$base = $glue ? 'Mac::Glue' : undef;
		}
	}

	for my $applescript (qw(Mac::OSA::Simple MacPerl Mac::AppleScript)) {
		if (!$base || $base eq $applescript) {
			eval "require $applescript";
			$base = $@ ? undef : $applescript;
		}
	}

	if (!$base || $base eq 'osascript') {
		chomp(my $res = `osascript -e1`);
		$base = $res eq 1 ? 'osascript' : undef;
	}

	if (!$base) {
		die "No way to invoke Growl, please see `perldoc Mac::Growl`";
	}

#	warn "Using $base for " . __PACKAGE__, "\n";

	_Define_Subs();
}

#################################
### Foundation implementation ###

use constant GROWL_APP_NAME						=> "ApplicationName";
use constant GROWL_APP_ICON						=> "ApplicationIcon";

use constant GROWL_NOTIFICATIONS_DEFAULT		=> "DefaultNotifications";
use constant GROWL_NOTIFICATIONS_ALL			=> "AllNotifications";
use constant GROWL_NOTIFICATIONS_USER_SET		=> "AllowedUserNotifications";

use constant GROWL_NOTIFICATION_NAME			=> "NotificationName";
use constant GROWL_NOTIFICATION_TITLE			=> "NotificationTitle";
use constant GROWL_NOTIFICATION_DESCRIPTION		=> "NotificationDescription";
use constant GROWL_NOTIFICATION_ICON			=> "NotificationIcon";
use constant GROWL_NOTIFICATION_PRIORITY		=> "NotificationPriority";
use constant GROWL_NOTIFICATION_STICKY			=> "NotificationSticky";

use constant GROWL_APP_REGISTRATION				=> "GrowlApplicationRegistrationNotification";
use constant GROWL_APP_REGISTRATION_CONF		=> "GrowlApplicationRegistrationConfirmationNotification";
use constant GROWL_NOTIFICATION					=> "GrowlNotification";

use constant GROWL_PING							=> "Honey, Mind Taking Out The Trash";
use constant GROWL_PONG							=> "What Do You Want From Me, Woman";
use constant NSNotificationPostToAllSessions	=> 1 << 1;

sub Foundation_RegisterNotifications($$$;$)
{
	my($appName, $allNotes, $defaultNotes, $iconOfApp) = @_;
	_Fix_Encode($_) for ($appName);

	my $appString    = NSString->alloc->initWithCString_($appName);
	my $notesArray   = NSMutableArray->alloc->init;
	my $defaultArray = NSMutableArray->alloc->init;

	$notesArray->addObject_($_)   for @$allNotes;
	$defaultArray->addObject_($_) for @$defaultNotes;

	my $regDict = NSMutableDictionary->alloc->initWithCapacity_(4);
	$regDict->setObject_forKey_($appString,    GROWL_APP_NAME);
	$regDict->setObject_forKey_($notesArray,   GROWL_NOTIFICATIONS_ALL);
	$regDict->setObject_forKey_($defaultArray, GROWL_NOTIFICATIONS_DEFAULT);
	$appString->release;
	$notesArray->release;
	$defaultArray->release;

	if ($appkit && defined $iconOfApp) {
		my $path = NSWorkspace->sharedWorkspace->fullPathForApplication_(
			NSString->stringWithCString_($iconOfApp)
		);
		if ($path && ref($path) eq 'NSCFString') {
			my $icon = NSWorkspace->sharedWorkspace->iconForFile_($path);
			if ($icon && $icon->isValid) {
				$regDict->setObject_forKey_($icon->TIFFRepresentation, GROWL_APP_ICON);
			}
		}
	}

	NSDistributedNotificationCenter->defaultCenter->postNotificationName_object_userInfo_options_(
		GROWL_APP_REGISTRATION,
		undef,
		$regDict,
		NSNotificationPostToAllSessions
	);
	$regDict->release;
}

sub Foundation_PostNotification($$$$;$$$)
{
	my($appName, $noteName, $noteTitle, $noteDescription, $sticky, $priority, $image) = @_;
	_Fix_Encode($_) for ($appName, $noteName, $noteTitle, $noteDescription);
	$sticky = $sticky ? 1 : 0;

	my $noteDict = NSMutableDictionary->alloc->initWithCapacity_(7);
	my $title = NSString->alloc->initWithUTF8String_($noteTitle);
	my $description = NSString->alloc->initWithUTF8String_($noteDescription);
	$noteDict->setObject_forKey_($noteName,     GROWL_NOTIFICATION_NAME);
	$noteDict->setObject_forKey_($appName,      GROWL_APP_NAME);
	$noteDict->setObject_forKey_($title,        GROWL_NOTIFICATION_TITLE);
	$noteDict->setObject_forKey_($description,  GROWL_NOTIFICATION_DESCRIPTION);
	$title->release;
	$description->release;
	if (defined $sticky) {
		my $noteSticky = NSNumber->alloc->initWithBool_($sticky);
		$noteDict->setObject_forKey_($noteSticky,   GROWL_NOTIFICATION_STICKY);
		$noteSticky->release;
	}
	if (defined $priority) {
		my $notePriority = NSNumber->alloc->initWithInt_($priority);
		$noteDict->setObject_forKey_($notePriority, GROWL_NOTIFICATION_PRIORITY);
		$notePriority->release;
	}

	if ($appkit && defined $image && -e $image) {
		my $path = NSString->alloc->initWithCString_($image);
		if ($path) {
			my $icon = NSImage->alloc->initWithContentsOfFile_($path);
			if ($icon) {
			   	if ($icon->isValid) {
					$noteDict->setObject_forKey_($icon->TIFFRepresentation, GROWL_NOTIFICATION_ICON);
				}
				$icon->release;
			}
			$path->release;
		}
	}

	NSDistributedNotificationCenter->defaultCenter->postNotificationName_object_userInfo_options_(
		GROWL_NOTIFICATION,
		undef,
		$noteDict,
		NSNotificationPostToAllSessions
	);
	$noteDict->release;
}


################################
### Mac::Glue implementation ###

sub Glue_RegisterNotifications($$$;$)
{
	my($appName, $allNotes, $defaultNotes, $iconOfApp) = @_;
	for ($appName) {
		_Fix_Encode($_);
		_Fix_Glue_String($_);
	}

	for my $notes ($allNotes, $defaultNotes) {
		$notes = [ map {
			Mac::Glue::param_type(Mac::AppleEvents::typeChar(), $_)
		} @$notes ];
	}

	$glue->register(
		as_application			=> $appName,
		all_notifications		=> $allNotes,
		default_notifications	=> $defaultNotes,
		icon_of_application		=> $iconOfApp,
	);
}

sub Glue_PostNotification($$$$;$$$)
{
	my($appName, $noteName, $noteTitle, $noteDescription, $sticky, $priority, $image) = @_;
	for ($appName, $noteName, $noteTitle, $noteDescription) {
		_Fix_Encode($_);
		_Fix_Glue_String($_);
	}
	$sticky = $sticky ? 1 : 0;

	my %params = (
		application_name	=> $appName,
		with_name			=> $noteName,
		title				=> $noteTitle,
		description			=> $noteDescription,
		sticky				=> $sticky
	);

	$params{priority} = $priority if defined $priority;

	my $image_url = _Fix_Image_Path($image);
	$params{image_from_location} = Mac::Glue::param_type(
		Mac::Glue::typeChar(), $image_url
	) if $image_url;

	$glue->notify(%params);
}

# make sure the strings are converted to Unicode, just in case
sub _Fix_Glue_String(\$)
{
	my($string) = @_;
	$$string = Mac::Glue::param_type(Mac::Glue::typeUnicodeText(), $$string);
}

##################################
### AppleScript implementation ###

sub AppleScript_RegisterNotifications($$$;$)
{
	my($appName, $allNotes, $defaultNotes, $iconOfApp) = @_;
	_Fix_Encode($_, 'MacRoman') for ($appName);

	# protect quotes and slashes
	for ($appName, $iconOfApp) {
		next unless defined;
		_Fix_AppleScript_String($_);
	}

	for my $list ($allNotes, $defaultNotes) {
		_Fix_AppleScript_String($_) for @$list;
		my $string = join('","', @$list);
		$list = $string;
	}

	my $script = qq'tell application "$helper" to register ' .
		qq'as application "$appName" ' .
		qq'all notifications ["$allNotes"] default notifications ["$defaultNotes"]';
	$script .= qq' icon of application "$iconOfApp"' if $iconOfApp;

	_Execute_AppleScript($script);
}

sub AppleScript_PostNotification($$$$;$$$)
{
	my($appName, $noteName, $noteTitle, $noteDescription, $sticky, $priority, $image) = @_;
	$sticky = $sticky ? 1 : 0;

	# protect quotes and slashes
	for ($appName, $noteName, $noteTitle, $noteDescription) {
		next unless defined;
		_Fix_AppleScript_String($_);
		_Fix_Encode($_, 'MacRoman');  # can't get to work with UTF8, so this will do
	}

	my $script = qq'tell application "$helper" to notify ' .
		qq'application name "$appName" with name "$noteName" ' .
		qq'title "$noteTitle" description "$noteDescription"';
	$script .= ' sticky true' if $sticky;

	if (defined $priority) {
		$priority =~ s/^.*?(-?\d+).*$/$1/g;
		$script .= " priority $priority" if $priority;
	}

	my $image_url = _Fix_Image_Path($image);
	$script .= qq' image from location "$image_url"' if $image_url;

	_Execute_AppleScript($script);
}

sub _Fix_AppleScript_String(\$)
{
	my($string) = @_;
	$$string =~ s/\\/\\\\/g;
	$$string =~ s/"/\\"/g;
}

sub _Execute_AppleScript
{
	my($script, $return) = @_;
	my $reply;
	# warn $script, "\n";

	if ($base eq 'Mac::OSA::Simple')
	{
		$reply = Mac::OSA::Simple::applescript($script);
	}

	elsif ($base eq 'MacPerl')
	{
		$reply = MacPerl::DoAppleScript($script);
	}

	elsif ($base eq 'Mac::AppleScript')
	{
		$reply = Mac::AppleScript::RunAppleScript($script);
	}

	else # ($base eq 'osascript')
	{
		if ($return) {
			$script =~ s/\\/\\\\/g;
			$script =~ s/'/'\''/g;
			chomp($reply = `osascript -ss -e '$script' 2>/dev/null`);
		} else {
			system('osascript', '-e', $script);
		}
	}

	if ($return) {
		$reply =~ s/^"(.+)"$/$1/;
		return $reply;
	}
}


#######################
### Misc. Functions ###

{
my $uri_file;

sub _Fix_Image_Path
{
	require File::Spec;
	unless (defined $uri_file) {
		eval 'require URI::file';
		$uri_file = $@ ? 0 : 1;
	}

	my($image) = @_;
	my $path;

	if (defined $image && length $image) {
		$path = File::Spec->rel2abs($image);
		if (-e $path) {
			my $reply;
			if ($uri_file) {
				my $uri = URI::file->new($path);
				$reply = $uri->as_string if $uri;
			} else {
				# URI::file will be available if Mac::Glue
				# is, so this only needs to be implemented
				# in AppleScript; yes, it's a hack, but
				# it's better to work out of the box than
				# to not
				my $script = <<EOT;
tell application "Finder"
   set thisfile to POSIX file "$path" as string
   set thisdoc to document file thisfile
   return URL of thisdoc
end tell
EOT
				$reply = _Execute_AppleScript($script, 1);
			}
			if ($reply) {
				# Growl being excessively anal
				$reply =~ s#^file:/(/localhost/)?(?!/)#file:///#;
				return $reply;
			}
		}
	}

	return;
}
}

sub _Fix_Encode (\$;$)
{
	my($str, $encoding) = @_;
	$$str = Encode::decode('utf8', $$str) if $encode;
	$$str = Encode::encode($encoding, $$str) if $encode && $encoding;
}

1;

__END__