clj-growl

Send Growl notifications from Clojure. Implements the GrowlTalk UDP protocol which is somewhat clearly described here. I also used a php implementation as a reference.

Version 0.2.1 of this library has been tested against Growl 1.2.1.

Installation

Leiningen

Add [clj-growl "0.2.1"] to your :dependencies in project.clj.

Maven

Add the following dependency:

<dependency>
  <groupId>clj-growl</groupId>
  <artifactId>clj-growl</artifactId>
  <version>0.2.1</version>
</dependency>

which comes from Clojars…

<repository>
  <id>clojars.org</id>
  <url>http://clojars.org/repo</url>
</repository>

API

The GrowlTalk protocol uses UDP so there is no way to get error messages when something goes wrong. Therefore, if it is not working for you, double-check everything and try again.

make-growler

(make-growler [password application])
(make-growler [password application notifications-list])

Create a function for sending Growl notifications. Optionally register a new application.

password A string which must match the one you enter in the “Server Password” field in the Growl control panel. If you did not enter a password then you may use nil or an empty string here.

application The name of the application.

notifications-list Optional list of the kinds of notifications that this application will receive. For each type, include the name of the notification and then a boolean to indicate if that notification is enabled by default. If this list is present then the application will be registered when you call make-growler. You may only send notifications to the types included in this list.

the growl function returned by make-growler, which is here called “growl”

(growl [notification title message])

notification A string that matches one of the configured notification types.

title The message title.

message The message text.

Usage

1. Install Growl.
2. Open the Growl control panel and select the “Network” tab.
3. Select “Listen for incoming notifications” and “Allow remote application registration”.
4. You may enter a “Server Password” or leave it empty.
5. Close the control panel.

(use 'clj-growl.core)

(def growl (make-growler "" "MyApp" ["Success" true "Failure" true]))

The make-growler function registers the application named “MyApp” configuring two types of notifications, which are both enabled by default, and returns a function that may be used to send notifications.

After you have called make-growler, open the Growl control panel to see the application “MyApp” in the list of applications (If you left the control panel open while registering, the application will not appear until you close and re-open the panel). Use the control panel to customize the appearance and behavior of your configured notifications.

To send notifications, use the growl function created above.

(growl "Success" "Hello World" "Clojure says Growl!")
(growl "Failure" "Meltdown!" "Run for your life.")

Notes

The current implementation does not support flags. Flags allow you to set the priority of the notification as well as its stickyness.

I don’t think it is possible to set the icon that is displayed in the notification when using the UDP protocol. The command line growlnotify allows you to set this. There is no reference to this in any of the UDP specs or examples that I have seen.

License

Copyright © 2010 Brenton Ashworth

Distributed under the Eclipse Public License, the same as Clojure uses. See the file COPYING.