doc/Hooks.txt (2730B) - raw
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 ## Please read:
52 https://github.com/sup-heliotrope/sup/wiki/Viewing-Attachments for
53 some security concerns on opening attachments.
54
55 ## turn text/html attachments into plain text, unless they are part
56 ## of a multipart/alternative pair
57 require 'shellwords'
58 unless sibling_types.member? "text/plain"
59 case content_type
60 when "text/html"
61 `/usr/bin/w3m -dump -T #{content_type} #{Shellwords.escape filename}`
62 end
63 end
64
65 startup:
66 ## runs a background task
67 @bgtask_pid = fork
68 if @bgtask_pid
69 set 'bgtask_pid' @bgtask_pid
70 Process.detach(@bgtask_pid) # so we don't have to wait on it when we go to kill it
71 else
72 exec "background-task args 2>&1 >> /tmp/logfile"
73 end
74
75 after-poll:
76 ## kills the background task after the first poll
77 @bgtask_pid = get 'bgtask_pid'
78 Process.kill("TERM", @bgtask_pid) unless @bgtask_pid == nil
79 set 'bgtask_pid' nil