Growl::Tiny - tiny perl module for sending Growl notifications on Mac OS X

version 0.0.3

    use Growl::Tiny;

Following the Tiny perl module convention, this module attempts to provide a way to use Mac::Growl on OS X without any of the prereqs (Mac::Glue, Mac::Carbon, etc.). I have repeatedly run into a number of problems installing these modules (on an old or brand new version of the OS, using a 64-bit perl, etc.), so I decided to write a tiny one that got the job done without them.

The only way I knew to use Growl without any prereqs was to use the growlnotify command-line tool. For more information on this tool, see:

  http://growl.info/documentation/growlnotify.php

There are some limitations, please see the BUGS AND LIMITATIONS section below. If these are a problem for you, please use Mac::Growl instead.

notify( { %options } )

Send a growl notification. Accepts either a hash or a hash reference.

Returns true if a notification was submitted.

subject => 'required notification text'

Text to be used for the notification body.

This is a required field--no notification will be generated if it is not set.

title => 'optional title'

Optional text to be used for the notification title.

priority => 0

Optional priority. This can be -2, -1, 0, 1, or 2.

sticky => 0

If 'sticky' is set to 'true', then the notification will remain on-screen until clicked.

quiet => 0

Suppress this notification.

host => ''

Send a network notification to the specified host by passing the -H option to growlnotify. Note that growl must be configured to accept network notifications for this to work. Set this to 'localhost' to use local network delivery for improved reliability--see the BUGS AND LIMITATIONS section below for more information.

If the environment variable GROWL_HOST is set, all notifications will be sent to that host by default. Individual notifications may still be sent to other hosts using the 'host' option.

image => '/path/to/image'

Set the path to an image to be used as an icon for notifications.

name => 'Growl::Tiny'

Set to the name of the application that is sending the notifications. By default this will be set to 'Growl::Tiny'. Setting this to the name of your application allows you to customize the notification options for your application in the growl preferences pane under the 'applications' tab.

Growl (http://growl.info) must be installed locally. You must also have the growlnotify script installed at:

    /usr/local/bin/growlnotify

The 'growlnotify' script will drop notifications when multiple notifications are being processed concurrently or are submitted too rapidly. I only discovered this while writing the test cases. As a result, this module is NOT recommended for any application where more than one notification might be generated per second. Note that Growl::Tiny will actually send messages much faster than this, but exceeding this rate may cause some notifications to be dropped.

The work-around for this is to use growlnotify to deliver network notifications to localhost. Unlike the default mechanism used by growlnotify, the network delivery seems to be very reliable. To enable this, go into the growl preference pane, select the 'network' tab, and enable 'listen for incoming connections'. I did not have to restart growl after changing this setting. Once this has been done, to use network notifications in Growl::Tiny, either set the environment variable GROWL_HOST, or else set the 'host' property on each notification to 'localhost'.

Note that there is no reasonable way to test if a notification has actually been displayed and not dropped. It is only possible to check that growlnotify returned success. This greatly limits the amount and quality of automated testing that can be performed.

notify - send a notification

http://growl.info - The Growl Project site

Mac::Growl - Local Growl Notification Framework.

Net::Growl - Growl Notifications over the network

Copyright (c) 2009, VVu@geekfarm.org All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.