Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jwiegley/alert

A Growl-like alerts notifier for Emacs
https://github.com/jwiegley/alert

Last synced: 24 days ago
JSON representation

A Growl-like alerts notifier for Emacs

Awesome Lists containing this project

README 

        
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 desktop notifications, the [notifications package](https://www.gnu.org/software/emacs/manual/html_node/elisp/Desktop-Notifications.html) that is installed with emacs, provides a probably better alternative for most users.



# For module writers



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



``` lisp

(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)



;; If a backend allows replacing alerts, you may pass an id

;; to your alert; then the next one with the same id will replace the

;; first one:

(alert "You have 30 unread mails" :title "Mail!" :id 'new-mail-alert)

(alert "You have 49 unread mails" :title "Mail!" :id 'new-mail-alert)

;; This avoids piling up lots of alerts, when only the last one is

;; relevant.

```



# 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:



``` lisp

(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:



| Name          | Summary                                                            |

| ------------- | ------------------------------------------------------------------ |

| 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](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                                  |

| notifications | Uses notifications library via D-Bus                               |

| notifier      | Uses terminal-notifier on OS X, if it is on the PATH               |

| osx-notifier  | Native OSX notification using AppleScript                          |

| toaster       | Use the toast notification system                                  |

| x11           | Changes the urgency property of the window in the X Window System

| termux        | Use `termux-notification` from the Termux API                     |



# 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:



``` lisp

(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.

                      ))

```