Alert is a Growl-workalike for Emacs which uses a common notification
interface and multiple, selectable "styles", whose use is fully
customizable by the user.

* For module writers

Just use `alert' instead of `message' as follows:

  (require 'alert)

  ;; This is the most basic form usage
  (alert "This is an alert")

  ;; You can adjust the severity for more important messages
  (alert "This is an alert" :severity 'high)

  ;; Or decrease it for purely informative ones
  (alert "This is an alert" :severity 'trivial)

  ;; Alerts can have optional titles.  Otherwise, the title is the
  ;; buffer-name of the (current-buffer) where the alert originated.
  (alert "This is an alert" :title "My Alert")

  ;; Further, alerts can have categories.  This allows users to
  ;; selectively filter on them.
  (alert "This is an alert" :title "My Alert" :category 'debug)

* For users

For the user, there are several variables to control when and how alerts
are presented.  By default, they appear in the minibuffer much the same
as a normal Emacs message.  But there are many more possibilities:

  `alert-fade-time'
    Normally alerts disappear after this many seconds, if the style
    supports it.  The default is 5 seconds.

  `alert-default-style'
    Pick the style to use if no other config rule matches.  The
    default is `message', but `growl' works well too.

  `alert-reveal-idle-time'
    If a config rule choose to match on `idle', this is how many
    seconds idle the user has to be.  Defaults to 5 so that users
    don't miss any alerts, but 120 is also good.

  `alert-persist-idle-time'
    After this many idle seconds, alerts will become sticky, and not
    fade away more.  The default is 15 minutes.

  `alert-log-messages'
    By default, all alerts are logged to *Alerts* (and to *Messages*,
    if the `message' style is being used).  Set to nil to disable.

  `alert-hide-all-notifications'
    Want alerts off entirely?  They still get logged, however, unless
    you've turned that off too.

  `alert-user-configuration'
    This variable lets you control exactly how and when a particular
    alert, a class of alerts, or all alerts, get reported -- or if at
    all.  Use this to make some alerts use Growl, while others are
    completely silent.

* Programmatically adding rules

Users can also programmatically add configuration rules, in addition to
customizing `alert-user-configuration'.  Here is one that the author
currently uses with ERC, so that the fringe gets colored whenever people
chat on BitlBee:

 (alert-add-rule :status   '(buried visible idle)
                 :severity '(moderate high urgent)
                 :mode     'erc-mode
                 :predicate
                 #'(lambda (info)
                     (string-match (concat "\\`[^&].*@BitlBee\\'")
                                   (erc-format-target-and/or-network)))
                 :persistent
                 #'(lambda (info)
                     ;; If the buffer is buried, or the user has been
                     ;; idle for `alert-reveal-idle-time' seconds,
                     ;; make this alert persistent.  Normally, alerts
                     ;; become persistent after
                     ;; `alert-persist-idle-time' seconds.
                     (memq (plist-get info :status) '(buried idle)))
                 :style 'fringe
                 :continue t)

* Builtin alert styles

There are several builtin styles, and it is trivial to create new ones.
The builtins are:

  fringe        - Changes the current frame's fringe background color
  mode-line     - Changes the current frame's mode-line background color
  gntp          - Uses gntp, it requires gntp.el (see https://github.com/tekai/gntp.el)
  growl         - Uses Growl on OS X, if growlnotify is on the PATH
  ignore        - Ignores the alert entirely
  libnotify     - Uses libnotify if notify-send is on the PATH
  log           - Logs the alert text to *Alerts*, with a timestamp
  message       - Uses the Emacs `message' facility
  momentary     - Uses the Emacs `momentary-string-display' facility
  notifications - Uses notifications library via D-Bus
  notifier      - Uses terminal-notifier on OS X, if it is on the PATH
  osx-notifier  - Native OSX notifier using AppleScript
  toaster       - Use the toast notification system
  x11 -         - Changes the urgency property of the window in the X Window System

* Defining new styles

To create a new style, you need to at least write a "notifier", which is
a function that receives the details of the alert.  These details are
given in a plist which uses various keyword to identify the parts of the
alert.  Here is a prototypical style definition:

 (alert-define-style 'style-name :title "My Style's title"
                     :notifier
                     (lambda (info)
                       ;; The message text is :message
                       (plist-get info :message)
                       ;; The :title of the alert
                       (plist-get info :title)
                       ;; The :category of the alert
                       (plist-get info :category)
                       ;; The major-mode this alert relates to
                       (plist-get info :mode)
                       ;; The buffer the alert relates to
                       (plist-get info :buffer)
                       ;; Severity of the alert.  It is one of:
                       ;;   `urgent'
                       ;;   `high'
                       ;;   `moderate'
                       ;;   `normal'
                       ;;   `low'
                       ;;   `trivial'
                       (plist-get info :severity)
                       ;; Whether this alert should persist, or fade away
                       (plist-get info :persistent)
                       ;; Data which was passed to `alert'.  Can be
                       ;; anything.
                       (plist-get info :data))

                     ;; Removers are optional.  Their job is to remove
                     ;; the visual or auditory effect of the alert.
                     :remover
                     (lambda (info)
                       ;; It is the same property list that was passed to
                       ;; the notifier function.
                       ))

You can test a specific style with something like this:

(let ((alert-user-configuration '((((:severity high)) momentary nil))))
  (alert "Same buffer momentary alert" :title "My Alert" :severity 'high)
  (alert "This is a momentary alert in another visible buffer" :title "My Alert"
         :severity 'high :buffer (other-buffer (current-buffer) t)))