git.cworth.org Git - sup/blob - doc/Hooks.txt

   1 Sup's Hook System
   2 -----------------
   3
   4 Sup can be easily customized via its hook system, which allows custom
   5 user code to be injected into Sup's execution path by "hooking" the
   6 code onto pre-defined events. When those events occur, the code is
   7 executed.
   8
   9 To see which hooks are available, simply run sup -l. Each hook sits in
  10 a file in ~/.sup/hooks/. Hooks are written in Ruby, and require no
  11 class or method definitions, just the executable code itself.
  12
  13 Information passes from Sup to the hook code via Ruby variables
  14 (actually method calls), and from the hook code back to Sup via a
  15 return value. The values of variables persists across calls to the
  16 same hook, but is NOT available to other hooks. To make the value of a
  17 variable available to other hooks, use the get and set methods.  Each
  18 hook description lists the variables and return value expected, if
  19 any.
  20
  21 The following special functions are available to hooks:
  22 * say msg
  23   Displays the string msg to the user at the bottom of the screen.
  24 * log msg
  25   Adds the string msg to the log, which the user can access via the
  26   buffer list.
  27 * ask_yes_or_no question
  28   Prompts the user with the string question for a yes or no
  29   response. Returns true if the user answered yes, false otherwise.
  30 * get key
  31   Gets the cross-hook value associated with key (which is typically a
  32   string). If there is no value for a given key, nil is returned.
  33 * set key value
  34   Sets the cross-hook value associated with key to value. key is
  35   typically a string, while value can be whatever type it needs to be,
  36   including nil.
  37
  38 Some example hooks:
  39
  40 before-poll:
  41   ## runs fetchmail before polling
  42   if (@last_fetchmail_time || Time.now) < Time.now - 60
  43     say "Running fetchmail..."
  44     system "fetchmail >& /dev/null"
  45     say "Done running fetchmail."
  46   end
  47   @last_fetchmail_time = Time.now
  48
  49
  50 mime-decode:
  51   ## turn text/html attachments into plain text, unless they are part
  52   ## of a multipart/alternative pair
  53   unless sibling_types.member? "text/plain"
  54     case content_type
  55     when "text/html"
  56       `/usr/bin/w3m -dump -T #{content_type} '#{filename}'`
  57     end
  58   end
  59
  60 startup:
  61   ## runs a background task
  62   @bgtask_pid = fork
  63   if @bgtask_pid
  64     set 'bgtask_pid' @bgtask_pid
  65     Process.detach(@bgtask_pid) # so we don't have to wait on it when we go to kill it
  66   else
  67     exec "background-task args 2&>1 >> /tmp/logfile"
  68   end
  69
  70 after-poll:
  71   ## kills the background task after the first poll
  72   @bgtask_pid = get 'bgtask_pid'
  73   Process.kill("TERM", @bgtask_pid) unless @bgtask_pid == nil
  74   set 'bgtask_pid' nil