terminal-notifier 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fef9492e8e3563546fe5358647649031585b01fa
-  data.tar.gz: 9c9604dd1f3fd959e691e7c7e67d05da5ec13001
+SHA256:
+  metadata.gz: 78c9a9b889e4da2b6154981a05925abdbc29f29c50591d233e599b0de4cdff08
+  data.tar.gz: 07c78da6932247a170a8b30289f7720089f82a1fd7120f769164295be777abdc
 SHA512:
-  metadata.gz: 1a6d520de804fc3c57f5b95f1e4889ab5e6e087a4888190f24fe8ad8a100482c6101bf1eb705e3732c4df0b861927132e0f3ff1d6ef44b859ca7952caddf5bd7
-  data.tar.gz: 696b031ece86bfd7948c990279745f044cae51a31509fe36f56699b4c5f9713fcd2385947cbf08eb5f4f2bc909c820b6379e1a5d607178fb3a3f636c7aca6401
+  metadata.gz: 94d37dc8ec053c61311c09931d7ab5d6a37922669fcf355d1a2569d86f0afc7ff913200e977e21d933329d4aaeb56b6e84bbdabe718694e9d8fc8f917e936976
+  data.tar.gz: 3552e9814c3a24a63e898d3aaab4c6bbf12c8231d0ab55dfade43db566605dc9f1e18f053c85f2251f90b4c37e6d0bcf3b42d27c4a6bbb90fdc24388235464db

data/README.markdown

@@ -2,7 +2,9 @@
 
 A simple Ruby wrapper around the [`terminal-notifier`][HOMEPAGE] command-line
 tool, which allows you to send User Notifications to the Notification Center on
-macOS 10.10, or higher.
+macOS 10.14, or higher.
+
+Requires Ruby 3.2 or newer.
 
 
 ## Installation
@@ -25,8 +27,8 @@ TerminalNotifier.notify('Hello World', :activate => 'com.apple.Safari')
 TerminalNotifier.notify('Hello World', :open => 'http://twitter.com/julienXX')
 TerminalNotifier.notify('Hello World', :execute => 'say "OMG"')
 TerminalNotifier.notify('Hello World', :group => Process.pid)
-TerminalNotifier.notify('Hello World', :sender => 'com.apple.Safari')
 TerminalNotifier.notify('Hello World', :sound => 'default')
+TerminalNotifier.notify('Hello World', :contentImage => './logo.png')
 
 TerminalNotifier.remove(Process.pid)
 
@@ -34,6 +36,55 @@ TerminalNotifier.list(Process.pid)
 TerminalNotifier.list
 ```
 
+`:sender` and `:appIcon` were removed in 3.0.0. They are still accepted, but the
+tool ignores them and warns on stderr — see the main [README][README].
+
+
+## Asking a question
+
+`:action` and `:reply` wait for the user and return what they chose. An option
+whose value is `true` is passed as a bare flag.
+
+```ruby
+TerminalNotifier.notify('Deploy to production?', :action => 'Yes,No', :timeout => 30)
+#=> :yes            (or :no, :_actionclicked, :_closed, :_timeout)
+
+TerminalNotifier.notify("What's your name?", :reply => true, :timeout => 30)
+#=> "Alice"         (a String, because :reply was given)
+```
+
+Action results come back symbolised by `notify_result`; a `:reply` result is
+returned as the raw string.
+
+A timeout returns `:_timeout` rather than `false`, so it can be told apart from
+the notification failing to send — which is what `false` means.
+
+
+## Return values
+
+`notify` and `remove` return whether the command succeeded. `list` returns a
+hash (or an array of hashes for the default `'ALL'` group) with the keys
+`:group`, `:title`, `:subtitle`, `:message` and `:delivered_at`; absent fields
+are `nil`. It returns `nil` when there is nothing to report.
+
+Both raise `TerminalNotifier::UnsupportedPlatformError` when run on anything
+other than a supported macOS, and `TerminalNotifier::BinaryNotFoundError` when
+the bundled binary is missing.
+
+Set `TERMINAL_NOTIFIER_BIN` to use a binary other than the bundled one.
+
+
+## Development
+
+```
+$ cd Ruby
+$ bundle install
+$ bundle exec rspec
+```
+
+One example needs the compiled application bundle and is skipped without it.
+Build and vendor it with `bundle exec rake update_build`, which requires Xcode.
+
 
 ## License
 

data/bin/terminal-notifier

@@ -1,13 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-if $0 == __FILE__
-  $:.unshift File.expand_path('../../lib', __FILE__)
-end
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__) if $PROGRAM_NAME == __FILE__
 
-require 'terminal-notifier'
+require 'terminal-notifier/cli'
 
-if !ARGV.include?("-message") && !STDIN.tty?
-  ARGV.push(*["-message", STDIN.read.chomp])
-end
-
-exec TerminalNotifier::BIN_PATH, *ARGV
+TerminalNotifier::CLI.run

data/lib/terminal-notifier/cli.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'terminal-notifier'
+
+module TerminalNotifier
+  # The bin wrapper's logic, extracted so that it can be tested without
+  # spawning a process.
+  module CLI
+    # Folds piped stdin into a -message option, matching the behaviour of the
+    # binary itself when data is piped to it directly.
+    def self.argv_for(argv, stdin)
+      return argv if argv.include?('-message') || stdin.tty?
+
+      argv + ['-message', stdin.read.chomp]
+    end
+
+    def self.run(argv = ARGV, stdin = $stdin)
+      exec TerminalNotifier::BIN_PATH, *argv_for(argv, stdin)
+    end
+  end
+end

data/lib/terminal-notifier/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TerminalNotifier
+  # The version of this gem, which tracks the version of the bundled
+  # terminal-notifier binary.
+  #
+  # Note: this is *not* TerminalNotifier.version, which returns the macOS
+  # product version the tool is running on.
+  VERSION = '3.0.0'
+end

data/lib/terminal-notifier.rb

@@ -1,34 +1,145 @@
-# coding: utf-8
-require 'shellwords'
+# frozen_string_literal: true
+
 require 'rbconfig'
+require 'shellwords'
+require 'time'
+
+require 'terminal-notifier/version'
 
+# Sends macOS User Notifications by shelling out to the bundled
+# terminal-notifier application.
+#
+# See TerminalNotifier.notify, .remove and .list for the public API.
 module TerminalNotifier
-  BIN_PATH = File.expand_path('../../vendor/terminal-notifier/terminal-notifier.app/Contents/MacOS/terminal-notifier', __FILE__)
+  # Minimum macOS version supported by the bundled binary. UNUserNotificationCenter,
+  # which the tool is built on, is not available before this.
+  MINIMUM_MACOS_VERSION = '10.14'
+
+  # Exit code the binary uses when -timeout expires waiting for -action or
+  # -reply. The notification was delivered correctly and the tool reported
+  # @TIMEOUT, so this is an outcome to pass on rather than a failure.
+  TIMEOUT_EXIT_CODE = 6
+
+  # Path to the binary inside the vendored application bundle. Overridable so
+  # that a Homebrew-installed or self-built copy can be used instead.
+  BIN_PATH = ENV.fetch(
+    'TERMINAL_NOTIFIER_BIN',
+    File.expand_path(
+      '../vendor/terminal-notifier/terminal-notifier.app/Contents/MacOS/terminal-notifier',
+      __dir__
+    )
+  )
 
   class UnsupportedPlatformError < StandardError; end
-  # Returns wether or not the current platform is macOS 10.10, or higher.
+  class BinaryNotFoundError < StandardError; end
+
+  # Returns whether the current platform is macOS 10.14 or higher.
   def self.available?
-    @available ||= (/darwin|mac os/ =~ RbConfig::CONFIG['host_os']) && Gem::Version.new(version) > Gem::Version.new('10.10')
+    # Memoise with defined? rather than ||=, so that a false result is cached
+    # too and we don't re-shell out on every single call.
+    return @available if defined?(@available)
+
+    @available = macos? && Gem::Version.new(version) >= Gem::Version.new(MINIMUM_MACOS_VERSION)
   end
 
+  # The macOS product version, or nil when not running on macOS.
   def self.version
-    @version ||= `uname`.strip == 'Darwin' && `sw_vers -productVersion`.strip
+    return @version if defined?(@version)
+
+    # Only shell out when we already know this is macOS. RbConfig reports the
+    # Darwin kernel version, which doesn't map cleanly onto product versions,
+    # so sw_vers is still needed for the number itself.
+    @version = macos? ? `sw_vers -productVersion`.strip : nil
   end
 
-  def self.execute(verbose, options)
-    if available?
-      command = [BIN_PATH, *options.map { |k,v| v = v.to_s; ["-#{k}", "#{v[0] == "-" ? " " : ""}#{Shellwords.escape(v[0,1])}#{v[1..-1]}"] }.flatten]
-      command = Shellwords.join(command) if RUBY_VERSION < '1.9'
-      result = ''
-      IO.popen(command) do |stdout|
-        output = stdout.read
-        STDOUT.print output if verbose
-        result << output
+  def self.macos?
+    return @macos if defined?(@macos)
+
+    @macos = !(RbConfig::CONFIG['host_os'] =~ /darwin|mac os/).nil?
+  end
+
+  # Builds the argument vector for the binary.
+  #
+  # A value of `true` becomes a bare flag and `false` omits the option entirely,
+  # so switches like :reply and :ignoreDnD don't end up with a stray "true" as
+  # their value (which -reply would show as its placeholder text).
+  def self.command_for(options)
+    arguments = options.flat_map do |key, value|
+      case value
+      when true then ["-#{key}"]
+      when false, nil then []
+      else ["-#{key}", escape_value(value.to_s)]
       end
-      result
-    else
-      STDERR.print "terminal-notifier is only supported on macOS 10.10, or higher."
     end
+    [BIN_PATH, *arguments]
+  end
+
+  # Prepares a single option value for the binary.
+  #
+  # This is *not* shell escaping — IO.popen is handed an argv array, so no shell
+  # is ever involved. It is the escaping the tool's own README documents as
+  # ‘\[’: the binary reads its arguments through NSUserDefaults, which tries to
+  # parse each value as a property list, so a value beginning with '[', '(',
+  # '{', a quote, a space and so on comes back as nil and the notification is
+  # never sent. Prefixing a backslash makes NSUserDefaults treat it as a plain
+  # string, and the binary strips that backslash again (see
+  # objectForKeyedSubscript: in AppDelegate.m).
+  #
+  # Shellwords.escape is used purely as a convenient test of "would this
+  # character be taken as syntax", which is the same set that matters here.
+  def self.escape_value(value)
+    return value if value.empty?
+
+    # A value starting with '-' would be read as the next flag; the binary
+    # strips this leading space back off.
+    prefix = value.start_with?('-') ? ' ' : ''
+    "#{prefix}#{Shellwords.escape(value[0, 1])}#{value[1..]}"
+  end
+
+  # Runs the binary and returns its standard output.
+  #
+  # Raises UnsupportedPlatformError when not on a supported macOS, and
+  # BinaryNotFoundError when the vendored binary is missing.
+  def self.execute(verbose, options)
+    ensure_usable!
+
+    output = IO.popen(command_for(options), &:read)
+    # Remember the status so callers aren't exposed to races on the global $?.
+    Thread.current[:terminal_notifier_last_status] = $?
+    $stdout.print output if verbose
+    output
+  end
+
+  # Raises unless this platform and installation can actually run the binary.
+  def self.ensure_usable!
+    unless available?
+      raise UnsupportedPlatformError,
+            "terminal-notifier is only supported on macOS #{MINIMUM_MACOS_VERSION} or higher."
+    end
+
+    return if File.executable?(BIN_PATH)
+
+    raise BinaryNotFoundError,
+          "terminal-notifier binary not found at #{BIN_PATH}. " \
+          'Set TERMINAL_NOTIFIER_BIN to point at it.'
+  end
+
+  # The exit status of the most recent execute call on this thread.
+  def self.last_status
+    Thread.current[:terminal_notifier_last_status]
+  end
+
+  def self.succeeded?
+    status = last_status
+    !status.nil? && status.success?
+  end
+
+  # True when the binary ran and reported an outcome, including a timeout.
+  def self.reported?
+    status = last_status
+    return false if status.nil?
+
+    status.success? || status.exitstatus == TIMEOUT_EXIT_CODE
   end
 
   # Cleans up the result of a notification, making it easier to work it
@@ -54,18 +165,26 @@ module TerminalNotifier
   # notify_result('@timeout', {'reply' => true}) #=> '@timeout'
   # notify_result('I may like pie', {}) #=> :i_may_like_pie
   def notify_result(result, options, always_string = false)
+    # The binary terminates its response with a newline. Left on, a reply comes
+    # back as "text\n" and an action title symbolises to :title_ because the
+    # newline is a non-word character.
+    result = result.to_s.chomp
+
     if options[:reply] || options['reply'] || always_string
       result
     else
-      result.length == 0 || result.downcase.gsub(/\W+/,'_').to_sym
+      # NOTE: an empty result yields `true`, not a symbol, because the `||`
+      # short-circuits. Odd, but it is the long-standing public contract.
+      result.empty? || result.downcase.gsub(/\W+/, '_').to_sym
     end
   end
   module_function :notify_result
 
   # Sends a User Notification and returns whether or not it was a success.
   #
-  # The available options are `:title`, `:group`, `:activate`, `:open`,
-  # `:execute`, `:sender`, and `:sound`. For a description of each option see:
+  # The available options are `:title`, `:subtitle`, `:group`, `:activate`,
+  # `:open`, `:execute`, `:contentImage`, and `:sound`. For a description of
+  # each option see:
   #
   #   https://github.com/julienXX/terminal-notifier/blob/master/README.markdown
   #
@@ -77,13 +196,14 @@ module TerminalNotifier
   #   TerminalNotifier.notify('Hello World', :activate => 'com.apple.Safari')
   #   TerminalNotifier.notify('Hello World', :open => 'http://twitter.com/julienXX')
   #   TerminalNotifier.notify('Hello World', :execute => 'say "OMG"')
-  #   TerminalNotifier.notify('Hello World', :sender => 'com.apple.Safari')
   #   TerminalNotifier.notify('Hello World', :sound => 'default')
   #
-  # Raises if not supported on the current platform.
+  # Raises UnsupportedPlatformError if not supported on the current platform.
   def notify(message, options = {}, verbose = false, always_string = false)
-    result = TerminalNotifier.execute(verbose, options.merge(:message => message))
-    $? && $?.success? && notify_result(result, options, always_string)
+    result = TerminalNotifier.execute(verbose, options.merge(message: message))
+    # A timeout counts as a reported outcome: without this it would come back as
+    # a bare false, indistinguishable from the notification failing to send.
+    TerminalNotifier.reported? && notify_result(result, options, always_string)
   end
   module_function :notify
 
@@ -91,13 +211,15 @@ module TerminalNotifier
   # ‘group’ ID, if one exists.
   #
   # If no ‘group’ ID is given, all notifications are removed.
+  # rubocop:disable Naming/PredicateMethod -- `remove` is the public API name
   def remove(group = 'ALL', verbose = false)
-    TerminalNotifier.execute(verbose, :remove => group)
-    $? && $?.success?
+    TerminalNotifier.execute(verbose, remove: group)
+    TerminalNotifier.succeeded?
   end
+  # rubocop:enable Naming/PredicateMethod
   module_function :remove
 
-  LIST_FIELDS = [:group, :title, :subtitle, :message, :delivered_at].freeze
+  LIST_FIELDS = %i[group title subtitle message delivered_at].freeze
 
   # If a ‘group’ ID is given, and a notification for that group exists,
   # returns a hash with details about the notification.
@@ -107,18 +229,32 @@ module TerminalNotifier
   #
   # If no information is available this will return `nil`.
   def list(group = 'ALL', verbose = false)
-    output = TerminalNotifier.execute(verbose, :list => group)
-    return if output.strip.empty?
-
-    require 'time'
-    notifications = output.split("\n")[1..-1].map do |line|
-      LIST_FIELDS.zip(line.split("\t")).inject({}) do |hash, (key, value)|
-        hash[key] = key == :delivered_at ? Time.parse(value) : (value unless value == '(null)')
-        hash
-      end
-    end
+    output = TerminalNotifier.execute(verbose, list: group)
+    return if output.nil? || output.strip.empty?
+
+    # Drop the header row.
+    notifications = output.split("\n")[1..].to_a.map { |line| TerminalNotifier.parse_list_row(line) }
 
     group == 'ALL' ? notifications : notifications.first
   end
   module_function :list
+
+  # Turns one tab-separated -list row into a hash.
+  def self.parse_list_row(line)
+    LIST_FIELDS.zip(line.split("\t")).each_with_object({}) do |(key, value), hash|
+      hash[key] = key == :delivered_at ? parse_time(value) : presence(value)
+    end
+  end
+
+  def self.parse_time(value)
+    Time.parse(value.to_s)
+  rescue ArgumentError, TypeError
+    nil
+  end
+
+  # 3.0.0 emits an empty field for an absent value; earlier binaries emitted the
+  # literal string "(null)".
+  def self.presence(value)
+    value unless value.nil? || value.empty? || value == '(null)'
+  end
 end

data/vendor/terminal-notifier/terminal-notifier.app/Contents/Info.plist

@@ -2,8 +2,6 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-	<key>BuildMachineOSBuild</key>
-	<string>17A405</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -19,45 +17,18 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2.0.0</string>
+	<string>3.0.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
-	<key>CFBundleSupportedPlatforms</key>
-	<array>
-		<string>MacOSX</string>
-	</array>
 	<key>CFBundleVersion</key>
-	<string>15</string>
-	<key>DTCompiler</key>
-	<string>com.apple.compilers.llvm.clang.1_0</string>
-	<key>DTPlatformBuild</key>
-	<string>9A1004</string>
-	<key>DTPlatformVersion</key>
-	<string>GM</string>
-	<key>DTSDKBuild</key>
-	<string>17A360</string>
-	<key>DTSDKName</key>
-	<string>macosx10.13</string>
-	<key>DTXcode</key>
-	<string>0901</string>
-	<key>DTXcodeBuild</key>
-	<string>9A1004</string>
+	<string>16</string>
 	<key>LSMinimumSystemVersion</key>
-	<string>10.10</string>
+	<string>10.14</string>
 	<key>LSUIElement</key>
 	<true/>
-	<key>NSAppTransportSecurity</key>
-	<dict>
-		<key>NSAllowsArbitraryLoads</key>
-		<true/>
-	</dict>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2012-2017 Eloy Durán, Julien Blanchard. All rights reserved.</string>
-	<key>NSMainNibFile</key>
-	<string>MainMenu</string>
 	<key>NSPrincipalClass</key>
 	<string>NSApplication</string>
-	<key>NSUserNotificationAlertStyle</key>
-	<string>banner</string>
 </dict>
 </plist>

data/vendor/terminal-notifier/terminal-notifier.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/Terminal.icns</key>
+		<data>
+		Oq9GtJM1DqcGF1JCHiEgb0hoN6I=
+		</data>
+		<key>Resources/en.lproj/InfoPlist.strings</key>
+		<dict>
+			<key>hash</key>
+			<data>
+			j6qg+qbNaStgLrdDQMdUxznV6qM=
+			</data>
+			<key>optional</key>
+			<true/>
+		</dict>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Resources/Terminal.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			zPwPRX277SsWSp9wjhoAAPrY+Jaw1TMrN24rdI8/9SU=
+			</data>
+		</dict>
+		<key>Resources/en.lproj/InfoPlist.strings</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			/rXoINaO0x+HHSva+NFJNe00OnqHXd13TVVW2o39lRo=
+			</data>
+			<key>optional</key>
+			<true/>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>