mack

README

Mack

Mack is a Golang wrapper for AppleScript. With Mack, you can easily trigger OS X desktop notifications and system sounds from within your Go application.

Installation

Mack requires OS X.

go get github.com/andybrewer/mack

Usage

Mack is ideal for local workflow optimization, OS X binary applications, or just spicing things up. For example:

Workflow: Process notification

When executing a long-running process, trigger a notification so you can get back to development without having to check the execution status.

package main

import "github.com/andybrewer/mack"

func main() {
  mack.Say("Starting process")
  // do stuff
  mack.Notify("Complete")
}

Workflow: Open applications

Interact with any Mac application from your code, like opening a URL to a HowTo video.

package main

import (
  "github.com/andybrewer/mack"
)

func main() {
  browsers := []string{"Some new browser", "Google Chrome", "Firefox", "Safari"}
  opened := false

  for _, browser := range browsers {
    err := mack.Tell(browser, `open location "http://youtube.com/my-howto-video"`)
    if err != nil {
      // handle error
    } else {
      // exit when we found a browser that works
      opened = true
      break
    }
  }

  if !opened {
    // alert user that a common browser could not be found
  }
}

App: ToDo list

Add a cheap GUI to your applications

package main

import "github.com/andybrewer/mack"

func main() {
  response, err := mack.Dialog("Enter a ToDo", "ToDo Wizard", "My new ToDo")
  if err != nil {
    panic(err)
  }

  if response.Clicked == "Cancel" {
    // handle the Cancel event
  } else {
    newToDo := response.Text
    // add ToDo to the database
    mack.Notify("Added " + newToDo + " to your calendar")
  }
}

Workflow: clipboard

Manipulate the clipboard

package main

import (
  "fmt"
  "github.com/andybrewer/mack"
)

func main() {
  // Output the content of the clipboard
  content, _ := mack.Clipboard()
  fmt.Println(content)

  // Change the content of the clipboard
  mack.SetClipboard("Hello World!")
  content, _ = mack.Clipboard()
  fmt.Println(content)
}

Documentation

Currently, Mack supports the following AppleScript commands:

• Beep
• Clipboard
• Display Alert
• Display Dialog
• Display Notification
• Say
• Tell

Full documentation is available at: godoc.org/github.com/andybrewer/mack

Links

• AppleScript Command Reference Docs

Contributors

• Andy Brewer (andybrewer)
• Hiroaki Nakamura (hnakamur)
• Antoine Augusti (AntoineAugusti)
• Gareth Watts (gwatts)

License

MIT

Documentation

Overview

Mack is a Golang wrapper for AppleScript. With Mack, you can easily trigger OS X desktop notifications and system sounds from within your Go application. Mack is ideal for local workflow optimization or OS X binary applications.

Repository: http://github.com/everdev/mack

Index

• func Beep(times int) error
• func Clipboard() (string, error)
• func List(title string, items ...string) (selected []string, didCancel bool, err error)
• func ListWithOpts(list ListOptions) (selected []string, didCancel bool, err error)
• func Notify(text string, options ...string) error
• func Say(text string, options ...string) error
• func SetClipboard(content string) error
• func Tell(application string, commands ...string) (string, error)
• type AlertOptions
• type DialogOptions
• type ListOptions
• type Response
  • func Alert(title string, options ...string) (Response, error)
  • func AlertBox(alert AlertOptions) (Response, error)
  • func Dialog(text string, options ...string) (Response, error)
  • func DialogBox(dialog DialogOptions) (Response, error)

Functions

func Beep

func Beep(times int) error

Beep triggers a given number of system beeps.

mack.Beep(1)  // Beeps once
mack.Beep(3)  // Beeps 3 times

Parameters:

times int  // Required - The number of beeps to play

func Clipboard

func Clipboard() (string, error)

Clipboard returns the content of the clipboard

func List

func List(title string, items ...string) (selected []string, didCancel bool, err error)

List triggers a desktop list selection box. It accepts a title and one or more string items for the user to select from

Use ListWithOpts for more control over the parameters

selected, didCancel, err := mack.List("Pick Things", "thing one", "thing two")

func ListWithOpts

func ListWithOpts(list ListOptions) (selected []string, didCancel bool, err error)

ListWithOpts trigger a desktop list selection box accepting custom parameters.

list := mack.ListOptions{
   Items: []string{"item one", 'item two"},
   Title: "My List Title",
   Message: "Pick one or more items from this list",
   DefaultItems: []string{"item one"},
   AllowMultiple: true,
 }
selected, didCancel, err := ListWithOpts(list)

func Notify

func Notify(text string, options ...string) error

Notify triggers a desktop notification.

mack.Notify("My message")                                     // Display a notification with the content "My message"
mack.Notify("My message", "My title")                         // Display a notification with the title "My title"
mack.Notify("My message", "My title", "My subtitle")          // Display a notification with the subtitle "My subtitle"
mack.Notify("My message", "My title", "My subtitle", "Ping")  // Display a notification with a Ping sound
mack.Notify("My message", "", "", "Ping")                     // Display a notification with a Ping sound and no title or subtitle

Parameters:

text string      // Required - The content of the notification
title string     // Optional - The title of the notification
subtitle string  // Optional - The subtitle of the notification
sound string     // Optional - The sound to play when showing the notification
                 // Sounds list located at: /System/Library/Sounds/
                 // ex. Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

func Say

func Say(text string, options ...string) error

Say triggers a voice notification that will read the text provided in a given voice.

mack.Say("Hi in Bruce's voice!", "Bruce")   // Have the "Bruce" voice read the text
mack.Say("Hi in default voice!")            // Have the system default voice read the text

Parameters:

text string   // Required - What the system voice will say
voice string  // Optional - The name of the system voice, otherwise defaults to system preferences
              // Voice list located at: /System/Library/Speech/Voices
              // ex. Agnes, Albert, Alex, Alice Compact, Alva Compact, Amelie Compact, Anna Compact, BadNews, Bahh, Bells, Boing, Bruce,
              //     Bubbles, Carmit Compact, Cellos, Damayanti Compact, Daniel Compact, Deranged, Diego Compact, Ellen Compact,
              //     Fiona Compact, Fred, GoodNews, Hysterical, Ioana Compact, Joana Compact, Junior, Kanya Compact, Karen Compact, Kathy,
              //     Kyoko Compact, Laura Compact, Lekha Compact, Luciana Compact, Mariska Compact, Mei-Jia Compact, Melina Compact,
              //     Milena Compact, Moira Compact, Monica Compact, Nora Compact, Organ, Paulina Compact, Princess, Ralph, Samantha Compact,
              //     Sara Compact, Satu Compact, Sin-ji Compact, Tarik Compact, Tessa Compact, Thomas Compact, Ting-Ting Compact, Trinoids,
              //     Veena Compact, Vicki, Victoria, Whisper, Xander Compact, Yelda Compact, Yuna Compact, Zarvox, Zosia Compact, Zuzana Compact

func SetClipboard

func SetClipboard(content string) error

SetClipboard changes the content of the clipboard

func Tell

func Tell(application string, commands ...string) (string, error)

Tell tells an application the specified commands

mack.Tell("TextEdit", "activate")  // Activates TextEdit
mack.Tell("TextEdit", "quit")      // Quits TextEdit
mack.Tell("Finder",
  "activate",
  `open (POSIX file "/Applications")`) // Activate Finder and open the "/Applications" folder

Parameters:

application string   // Required - What application the system will tell to
commands string      // Required - What command lines the system will tell

Types

type AlertOptions

type AlertOptions struct {
	Title    string // The title of the alert, displayed in emphasis
	Message  string // The explanatory message, displayed in small text
	Style    string // The style of the alert: "informational" (default), "warning" or "critical"
	Duration int    // The number of seconds to wait for a user response, blank or "" will keep it visible until closed

	// Buttons
	Buttons       string // The list of up to 3 buttons. Must be commas separated, ex. "Yes, No, Don't Know"
	DefaultButton string // The default selected button from the button list, ex. "Don't Know"
}

AlertOptions are used to generate an AlertBox

type DialogOptions

type DialogOptions struct {
	Text         string // The content of the dialog box
	Title        string // The title of the dialog box, displayed in emphasis
	Answer       string // The default text in the input field
	HiddenAnswer bool   // If true, converts the answer text to bullets (like a password field)
	Icon         string // The path to a .icns file, or one of the following: "stop", "note", "caution"
	Duration     int    // The number of seconds to wait for a user response

	// Buttons
	Buttons       string // The list of up to 3 buttons. Must be commas separated, ex. "Yes, No, Don't Know"
	DefaultButton string // The default selected button from the button list, ex. "Don't Know"
}

DialogOptions are used to generate a DialogBox

type ListOptions

type ListOptions struct {
	Items         []string // The items to display
	Title         string   // The title of the dialog box
	Message       string   // A message prompt to display in the obx
	OkButton      string   // Text to display on the OK button - defaults to "OK"
	CancelButton  string   // Text to display on the Cancel button - defaults to "Cancel"
	DefaultItems  []string // Optional list of items to select by default
	AllowMultiple bool     // If true, then the user can select multiple items in the list
	AllowEmpty    bool     // If true then the user can select zero items in the list
}

ListOptions supplies parameters to the ListWithOpts function.

type Response

type Response struct {
	Clicked string // The name of the button clicked
	GaveUp  bool   // True if the user failed to respond in the duration specified
	Text    string // Only on Dialog boxes - The return value of the input field
}

The response format after a button click on an alert or dialog box

func Alert

func Alert(title string, options ...string) (Response, error)

Alert triggers a desktop alert with custom buttons. Either an error is returned, or the string output from the user interaction.

mack.Alert("Alert")                               // Display an alert with the emhpasized text "My alert"
mack.Alert("Alert", "Message")                    // Display an alert with the small text "My message"
mack.Alert("Alert", "Message", "critical")        // Display an alert styled as "critical"
mack.Alert("Alert", "Message", "critical", "5")   // Display an alert that will disappear after 5 seconds
mack.Alert("Alert", "", "", "10")                 // Display an alert that will disappear after 10 seconds
response, err := mack.Alert("Alert")              // Capture the Response for the alert

Parameters:

title string      // Required - The title of the alert, displayed in emphasis
message string    // Optional - The explanatory message, displayed in small text
style string      // Optional - The style of the alert: "informational" (default), "warning" or "critical"
duration string   // Optional - The number of seconds to wait for a user response, blank or "" will keep it visible until closed

func AlertBox

func AlertBox(alert AlertOptions) (Response, error)

AlertBox triggers a desktop alert with the option for custom buttons. Either an error is returned, or the string output from the user interaction.

alert := mack.AlertOptions{
  Title:          "Alert title",          // Required
  Message:        "Alert message",        // Optional
  Style:          "critical",             // Optional
  Duration:       5,                      // Optional
  Buttons:        "Yes, No, Don't Know",  // Optional - Comma separated list, max of 3
  DefaultButton:  "Don't Know",           // Optional - Ignored if no ButtonList
}
response, err := mack.AlertBox(alert)     // Display an alert with the AlertBox settings, returns an error and Response

func Dialog

func Dialog(text string, options ...string) (Response, error)

Dialog triggers a desktop dialog box. Either an error is returned, or the string output from the user interaction.

mack.Dialog("Dialog text")                                    // Display a dialog box
mack.Dialog("Dialog text", "My Title")                        // Display a dialog box with the title "My Title"
mack.Dialog("Dialog text", "My Title", "default text")        // Display a dialog box with "default text" in the input field
mack.Dialog("Dialog text", "My Title", "default text", "5")   // Display a dialog box that will disappear after 5 seconds
mack.Dialog("Dialog text", "", "", "10")                      // Display a dialog box that will disappear after 10 seconds
response, err := mack.Dialog("My dialog")                     // Capture the Response for the dialog box

Parameters:

text string       // Required - The content of the dialog box
title string      // Optional - The title of the dialog box, displayed in emphasis
answer string     // Optional - The default text in the input field
duration string   // Optional - The number of seconds to wait for a user response

func DialogBox

func DialogBox(dialog DialogOptions) (Response, error)

DialogBox triggers a desktop dialog box with the option for custom buttons. Either an error is returned, or the string output from the user interaction.

dialog := mack.DialogOptions{
  Text:           "Dialog text",          // Required
  Title:          "Dialog title",         // Optional
  Answer:         "Default answer",       // Optional
  Duration:       5,                      // Optional
  HiddenAnswer:   true,                   // Optional - If true, turns the input text to bullets
  Icon:           "stop",                 // Optional - "stop", "note", "caution" or location of .icns file
  Buttons:        "Yes, No, Don't Know",  // Optional - Comma separated list, max of 3
  DefaultButton:  "Don't Know",           // Optional - Ignored if no ButtonList
}
response, err := mack.DialogBox(dialog)   // Display a dialog with the DialogBox settings, returns an error and Response