Skip to content

Latest commit

 

History

History
145 lines (119 loc) · 3.73 KB

README.adoc

File metadata and controls

145 lines (119 loc) · 3.73 KB
Raw

Notify

Note
 This is probably a better choice.

Build Status Coverage Status

A tiny Go library and CLI tool for displaying user notifications on OS X.

The state of OS X notifications

Before OS X 10.9 (Mavericks), displaying a notification in the native Notification Center required having a code-signed app bundle. These were dark times, and awesome tools like terminal-notifier were born out of frustration with the dismal state of affairs. However, as of OS X 10.9 you can display a notification through Apple’s Applescript API. It looks something like this:

osascript -e 'display notification "text" with title "title"'

Still, that’s not a particularly nice API for most users. That’s where this package comes in. It implements a nicer wrapper over the Applescript notification API in both a command-line interface and a Go library.

Other platforms

This package will correctly compile and run on other platforms. Instead of displaying a notification, the call to Show will fail, returning ErrorUnsupportedPlatform.

Requirements

  • ❏ Go v1.0+ (1.2+ for accurate coverage reporting)

  • ❏ OS X 10.9+ to actually display the notifications, other platforms will simply return ErrorUnsupportedPlatform

Command-line usage

Installation

go get -u github.com/ciarand/notify/cmd/notify

Usage

Usage of notify:
  -sound="": An optional sound name to play
  -subtitle="": An optional subtitle for the notification
  -text="": The required text for the notification
  -title="": The required title of the notification

Examples

# a basic notification
notify -title "Title" -text "Text"
# with a subtitle
notify -title "Title" -text "Text" -subtitle "Subtitle"
# with a sound (check /System/Library/Sounds or ~/Library/Sounds)
notify -title "Title" -text "Text" -sound "Basso"
# all together now
notify -title "Title" -text "Text" -subtitle "subtitle" -sound "Funk"

Library usage

Installation

go get -u github.com/ciarand/notify

Usage

The library presents a very simple API. There are 4 ways to create a new notification:

// a basic notification
func NewNotification(title, text string) Notification
// a notification with a subtitle
func NewSubtitledNotification(title, sub, text string) Notification
// a notification with sound (check /System/Library/Sounds or ~/Library/Sounds)
func NewNotificationWithSound(title, text, sound string) Notification
// a notification with a subtitle and a sound
func NewSubtitledNotificationWithSound(title, sub, text, sound string) Notification

Once you have a Notification, you can call Display on it:

package main

import "github.com/ciarand/notify"

func main() {
	n := notify.NewNotification("Error", "Foobar failed, the defenses are failing!")

	if err := n.Display(); err == notify.ErrorUnsupportedPlatform {
		fmt.Println("You're not using Darwin!")
	} else if err != nil {
		fmt.Println("An error happened when running the command!")
	} else {
		fmt.Println("Everything went great!")
	}
}

Development

Tests are run with go test, as you’d expect.

License

ISC, see the LICENSE file.