Class: Guard::Notifier::Tmux

Inherits:
Base
  • Object
show all
Defined in:
lib/guard/notifiers/tmux.rb

Overview

Changes the color of the Tmux status bar and optionally shows messages in the status bar.

Examples:

Add the `:tmux` notifier to your `Guardfile`

notification :tmux

Enable text messages

notification :tmux, display_message: true

Customize the tmux status colored for notifications

notification :tmux, color_location: 'status-right-bg'

Constant Summary

DEFAULTS =

Default options for the tmux notifications.

{
  client:                 'tmux',
  tmux_environment:       'TMUX',
  success:                'green',
  failed:                 'red',
  pending:                'yellow',
  default:                'green',
  timeout:                5,
  display_message:        false,
  default_message_format: '%s - %s',
  default_message_color:  'white',
  display_on_all_clients: false,
  display_title:          false,
  default_title_format:   '%s - %s',
  line_separator:         ' - ',
  change_color:           true,
  color_location:         'status-left-bg'
}

Constants inherited from Base

Base::HOSTS

Instance Attribute Summary

Attributes inherited from Base

#options

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

_supported_host?, gem_name, #images_path, #initialize, name, #name, #normalize_standard_options!, require_gem_safely, supported_hosts, title, #title

Constructor Details

This class inherits a constructor from Guard::Notifier::Base

Class Method Details

._register!(opts) ⇒ Boolean

Detects if a TMUX environment is available and if not, displays an error message unless `opts` is true.

Returns:

  • (Boolean)

    whether or not a TMUX environment is available



59
60
61
62
63
64
65
66
67
68
# File 'lib/guard/notifiers/tmux.rb', line 59

def self._register!(opts)
  if _tmux_environment_available?(opts)
    true
  else
    unless opts[:silent]
      ::Guard::UI.error 'The :tmux notifier runs only on when Guard is executed inside of a tmux session.'
    end
    false
  end
end

._tmux_environment_available?(opts) ⇒ Boolean

Returns whether or not a TMUX environment is available

Returns:

  • (Boolean)

    whether or not a TMUX environment is available



48
49
50
# File 'lib/guard/notifiers/tmux.rb', line 48

def self._tmux_environment_available?(opts)
  !ENV[opts.fetch(:tmux_environment, DEFAULTS[:tmux_environment])].nil?
end

.available?(opts = {}) ⇒ Boolean

Returns:

  • (Boolean)


40
41
42
# File 'lib/guard/notifiers/tmux.rb', line 40

def self.available?(opts = {})
  super and _register!(opts)
end

.options_storeObject



242
243
244
# File 'lib/guard/notifiers/tmux.rb', line 242

def self.options_store
  @options_store ||= {}
end

.turn_offObject

Notification stopping. Restore the previous Tmux state if available (existing options are restored, new options are unset) and unquiet the Tmux output.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
# File 'lib/guard/notifiers/tmux.rb', line 227

def self.turn_off
  if @options_stored
    @options_store.each do |client, options|
      options.each do |key, value|
        if value
          `#{ DEFAULTS[:client] } set -t #{ client } -q #{ key } #{ value }`
        else
          `#{ DEFAULTS[:client] } set -t #{ client } -q -u #{ key }`
        end
      end
    end
    _reset_options_store
  end
end

.turn_onObject

Notification starting, save the current Tmux settings and quiet the Tmux output.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
# File 'lib/guard/notifiers/tmux.rb', line 207

def self.turn_on
  unless @options_stored
    _reset_options_store

    _clients.each do |client|
      options_store[client] ||= {}
      `#{ DEFAULTS[:client] } show -t #{ client }`.each_line do |line|
        option, _, setting = line.chomp.partition(' ')
        @options_store[client][option] = setting
      end
    end

    @options_stored = true
  end
end

Instance Method Details

#display_message(type, title, message, opts = {}) ⇒ Object

Displays a message in the status bar of tmux.

Parameters:

  • type (String)

    the notification type. Either 'success', 'pending', 'failed' or 'notify'

  • title (String)

    the notification title

  • message (String)

    the notification message body

  • options (Hash)

    additional notification library options



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
# File 'lib/guard/notifiers/tmux.rb', line 175

def display_message(type, title, message, opts = {})
  message_format = opts.fetch("#{ type }_message_format".to_sym, opts.fetch(:default_message_format, DEFAULTS[:default_message_format]))
  message_color = opts.fetch("#{ type }_message_color".to_sym, opts.fetch(:default_message_color, DEFAULTS[:default_message_color]))
  display_time = opts.fetch(:timeout, DEFAULTS[:timeout])
  separator = opts.fetch(:line_separator, DEFAULTS[:line_separator])

  color = tmux_color type, opts
  formatted_message = message.split("\n").join(separator)
  display_message = message_format % [title, formatted_message]

  _run_client "set", "-q display-time #{ display_time * 1000 }"
  _run_client "set", "-q message-fg #{ message_color }"
  _run_client "set", "-q message-bg #{ color }"
  _run_client "display-message", "'#{ display_message }'"
end

#display_title(type, title, message, opts = {}) ⇒ Object

Displays a message in the title bar of the terminal.

Parameters:

  • title (String)

    the notification title

  • message (String)

    the notification message body

  • options (Hash)

    additional notification library options



135
136
137
138
139
140
141
142
143
144
145
# File 'lib/guard/notifiers/tmux.rb', line 135

def display_title(type, title, message, opts = {})
  title_format   = opts.fetch("#{ type }_title_format".to_sym, opts.fetch(:default_title_format, DEFAULTS[:default_title_format]))
  teaser_message = message.split("\n").first
  display_title  = title_format % [title, teaser_message]

  if _tmux_version >= 1.7
    _run_client "set-option", "-q set-titles-string '#{ display_title }'"
  else
    _run_client "set-option", "set-titles-string '#{ display_title }'"
  end
end

#notify(message, opts = {}) ⇒ Object

Shows a system notification.

By default, the Tmux notifier only makes use of a color based notification, changing the background color of the `color_location` to the color defined in either the `success`, `failed`, `pending` or `default`, depending on the notification type.

You may enable an extra explicit message by setting `display_message` to true, and may further disable the colorization by setting `change_color` to false.

Parameters:

  • title (String)

    the notification title

  • opts (Hash) (defaults to: {})

    additional notification library options

Options Hash (opts):

  • type (String)

    the notification type. Either 'success', 'pending', 'failed' or 'notify'

  • message (String)

    the notification message body

  • image (String)

    the path to the notification image

  • change_color (Boolean)

    whether to show a color notification

  • color_location (String, Array)

    the location where to draw the color notification

  • display_message (Boolean)

    whether to display a message or not

  • display_on_all_clients (Boolean)

    whether to display a message on all tmux clients or not



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
# File 'lib/guard/notifiers/tmux.rb', line 96

def notify(message, opts = {})
  super
  opts.delete(:image)

  if opts.fetch(:change_color, DEFAULTS[:change_color])
    color_locations = Array(opts.fetch(:color_location, DEFAULTS[:color_location]))
    color = tmux_color(opts[:type], opts)

    color_locations.each do |color_location|
      _run_client "set","-q #{ color_location } #{ color }"
    end
  end

  type  = opts.delete(:type).to_s
  title = opts.delete(:title)

  if opts.fetch(:display_title, DEFAULTS[:display_title])
    display_title(type, title, message, opts)
  end

  if opts.fetch(:display_message, DEFAULTS[:display_message])
    display_message(type, title, message, opts)
  end
end

#tmux_color(type, opts = {}) ⇒ String

Get the Tmux color for the notification type. You can configure your own color by overwriting the defaults.

Parameters:

  • type (String)

    the notification type

Returns:

  • (String)

    the name of the emacs color



197
198
199
200
201
202
# File 'lib/guard/notifiers/tmux.rb', line 197

def tmux_color(type, opts = {})
  type = type.to_sym
  type = :default unless [:success, :failed, :pending].include?(type)

  opts.fetch(type, DEFAULTS[type])
end