Bug correcton in links module.
[berthome:berthome.git] / keychain.lua
1 -- -*- coding: utf-8 -*-
2 --------------------------------------------------------------------------------
3 -- @author Nicolas Berthier <nberthier@gmail.com>
4 -- @copyright 2010 Nicolas Berthier
5 --------------------------------------------------------------------------------
6 --
7 -- This is a module for defining keychains √† la emacs in awesome. I was also
8 -- inspired by ion3 behavior when designing it.
9 --
10 -- Remarks:
11 --
12 -- - This module does not handle `release' key bindings, but is it useful for
13 --   keychains?
14 --
15 -- - It has not been tested with multiple screens yet.
16 --
17 -- - There might (... must) be incompatibilities with the shifty module. Also,
18 --   defining global and per-client keychains with the same prefix is not
19 --   allowed (or leads to unspecified behaviors... --- in practice: the
20 --   per-client ones are ignored). However, I do think separation of per-client
21 --   and global keys is a bad idea if client keys do not have a higher priority
22 --   than the global ones...
23 --
24 -- Example usage: see `rc.lua' file.
25 --
26 --------------------------------------------------------------------------------
27
28 --{{{ Grab environment (mostly aliases)
29 local setmetatable = setmetatable
30 local ipairs = ipairs
31 local type = type
32 local pairs = pairs
33 local string = string
34 local print = print
35 local error = error
36 local io = io
37
38 local capi = capi
39 local client = client
40 local awesome = awesome
41 local root = root
42
43 local akey  = require ("awful.key")
44 local join = awful.util.table.join
45 local clone = awful.util.table.clone
46 --}}}
47
48 module ("keychain")
49
50 -- Privata data: we use weak keys in order to allow collection of private data
51 -- if keys (clients) are collected (i.e., no longer used, after having been
52 -- killed for instance)
53 local data = setmetatable ({}, { __mode = 'k' })
54
55 --{{{ Functional Tuples
56 -- see http://lua-users.org/wiki/FunctionalTuples for details
57
58 --- Creates a keystroke representation to fill the `escape' table configuration
59 --- property.
60 -- @param m Modifiers table.
61 -- @param k The key itself.
62 -- @return A keystroke representation (only for the escape sequence, for now?).
63 function keystroke (m, k)
64     if type (m) ~= "table" then
65         error ("Keystroke modifiers must be given a table (got a "..
66                type (m)..")")
67     end
68     if type (k) ~= "string" then
69         error ("Keystroke key must be given a string (got a "..
70                type (m)..")")
71     end
72     return function (fn) return fn (m, k) end
73 end
74
75 -- keystroke accessors
76 local function ks_mod (_m, _k) return _m end
77 local function ks_key (_m, _k) return _k end
78
79 -- ---
80
81 --- Creates a final keychain binding to fill the keychain binding tables,
82 --- meaning that the given function will be executed at the end of the keychain.
83 -- @param m Modifiers table.
84 -- @param k The key.
85 -- @param cont The function to be bound to the given keys.
86 -- @return A "final" key binding.
87 function key (m, k, cont)
88     if type (cont) ~= "function" then
89         error ("Final binding must be given a function (got a "..
90                type (cont)..")")
91     end
92     return function (fn) return fn (keystroke (m, k), cont, true) end
93 end
94
95 --- Creates an intermediate (prefix) keychain binding.
96 -- @param m Modifiers table.
97 -- @param k The key.
98 -- @param sub The subchain description table to be bound to the given keys.
99 -- @return An "intermediate" key binding.
100 function subchain (m, k, sub)
101     if type (sub) ~= "table" then
102         error ("Subchain binding must be given a table (got a "..
103                type (sub)..")")
104     end
105     return function (fn) return fn (keystroke (m, k), sub, false) end
106 end
107
108 -- key/subchain binding accessors
109 local function binding_ks   (ks, cont, leaf) return ks end
110 local function binding_cont (ks, cont, leaf) return cont end
111 local function binding_leaf (ks, cont, leaf) return leaf end
112
113 --- Creates an intermediate keychain if sub is a table, or a final key binding
114 --- otherwise (and then sub must be a function).
115 -- @param m Modifiers table.
116 -- @param k The key.
117 -- @param sub Either the subchain description table, or the function, to be
118 -- bound to the given keys.
119 function sub (m, k, sub)
120     if type (sub) == "table" then
121         return subchain (m, k, sub)
122     else
123         return key (m, k, sub)
124     end
125 end
126
127 --}}}
128
129 --{{{ Default values
130
131 --- Default escape sequences (S-g is inspired by emacs...)
132 local escape_keystrokes = {
133     keystroke ( {        }, "Escape" ),
134     keystroke ( { "Mod4" }, "g"      ),
135 }
136
137 --}}}
138
139 --{{{ Key table management facilities
140
141 local function set_keys (c, k)
142     if c == root then root.keys (k) else c:keys (k) end
143 end
144
145 local function keys_of (c)
146     if c == root then return root.keys () else return c:keys () end
147 end
148
149 --}}}
150
151 --{{{ Signal emission helper
152
153 local function notif (sig, w, ...)
154     if w ~= root then
155         client.emit_signal (sig, w, ...)
156     else                        -- we use global signals otherwise
157         awesome.emit_signal (sig, ...)
158     end
159 end
160
161 --}}}
162
163 --{{{ Client/Root-related state management
164
165 local function init_client_state_maybe (w)
166     if data[w] == nil then
167         local d = { }
168         d.keys = keys_of (w)    -- save client keys
169         data[w] = d             -- register client
170         notif ("keychain::enter", w)
171     end
172 end
173
174 local function restore_client_state (c)
175     local w = c or root
176     local d = data[w]
177     -- XXX: Turns out that `d' can be nil already here, in case the keyboard has
178     -- been grabbed since the previous call to this funtion... (that also seems
179     -- to be called again upon release‚Ķ)
180     if d then
181         set_keys (w, d.keys)    -- restore client keys
182         data[w] = nil           -- unregister client
183     end
184 end
185
186 local function leave (c)
187     local w = c or root
188
189     -- Destroy notifier structures if needed
190     if data[w] then             -- XXX: necessary test?
191         notif ("keychain::leave", w)
192     end
193 end
194
195 -- force disposal of resources when clients are killed 
196 client.add_signal ("unmanage", leave)
197
198 --}}}
199
200 --{{{ Key binding tree access helpers
201
202 local function make_on_entering (m, k, subchain) return
203     function (c)
204         local w = c or root
205         
206         -- Register and initialize client state, if not already in a keychain
207         init_client_state_maybe (w)
208
209         -- Update notifier text, and trigger its drawing if necessary
210         notif ("keychain::append", w, m, k)
211
212         -- Setup subchain
213         set_keys (w, subchain)
214     end
215 end
216
217 local function on_leaving (c)
218     -- Trigger disposal routine
219     leave (c)
220
221     -- Restore initial key mapping of client
222     restore_client_state (c)
223 end
224
225 --}}}
226
227 --{{{ Configuration
228
229 -- Flag to detect late initialization error
230 local already_used = false
231
232 -- Escape binding table built once upon initialization
233 local escape_bindings = { }
234
235 --- Fills the escape bindings table with actual `awful.key' elements triggering
236 --- execution of `on_leaving'.
237 local function init_escape_bindings ()
238     escape_bindings = { }
239     for _, e in ipairs (escape_keystrokes) do
240         escape_bindings = join (escape_bindings,
241                                 akey (e (ks_mod), e (ks_key), on_leaving))
242     end
243 end
244
245 -- Call it once upon module loading to initialize escape_bindings (in case
246 -- `init' is not called).
247 init_escape_bindings ()
248
249
250 --- Initializes the keychain module, with given properties; to be called before
251 --- ANY other function of this module.
252 -- Configurations fields include:
253 --
254 -- `escapes': A table of keystrokes (@see keychain.keystroke) escaping keychains
255 -- (defaults are `Mod4-g' and `Escape').
256 --
257 -- @param c The table of properties.
258 function init (c)
259     local c = c or { }
260
261     if already_used then
262         -- heum... just signal the error: "print" or "error"?
263         return print ("E: keychain: Call to `init' AFTER having bound keys!")
264     end
265
266     escape_keystrokes = c.escapes and c.escapes or escape_keystrokes
267     
268     -- Now, fill the escape bindings table again with actual `awful.key'
269     -- elements triggering `on_leaving' executions, in case escape keys has
270     -- changed.
271     init_escape_bindings ()
272 end
273
274 --}}}
275
276 --{{{ Keychain creation
277
278 --- Creates a new keychain binding.
279 -- @param m Modifiers table.
280 -- @param k The key.
281 -- @param chains A table of keychains, describing either final bindings (see
282 -- key constructor) or subchains (see subchain constructor). If arg is not a
283 -- table, then `awful.key' is called directly with the arguments.
284 -- @return A key binding for the `awful.key' module.
285 -- @see awful.key
286 function new (m, k, chains)
287
288     -- If the argument is a function, then we need to return an actual awful.key
289     -- directly.
290     if type (chains) ~= "table" then
291         return akey (m, k, chains)
292     end
293
294     -- This table will contain the keys to be mapped upon <m, k> keystroke. It
295     -- initially contains the escape bindings, so that one can still rebind them
296     -- differently in `chains'.
297     local subchain = clone (escape_bindings)
298
299     already_used = true         -- subsequent init avoidance flag...
300
301     -- For each entry of the given chains, add a corresponding `awful.key'
302     -- element in the subchain
303     for _, e in ipairs (chains) do
304         local ks = e (binding_ks)
305         if e (binding_leaf) then
306             -- We encountered a leaf in the chains.
307             local function on_leaf (c) on_leaving (c); e (binding_cont) (c) end
308             subchain = join (subchain, akey (ks (ks_mod), ks (ks_key), on_leaf))
309         else
310             -- Recursively call subchain creation. "Funny" detail: I think there
311             -- is no way of creating ill-structured keychain descriptors that
312             -- would produce infinite recursive calls here, since we control
313             -- their creation with functional tuples, that cannot lead to cyclic
314             -- structures...
315             local subch = new (ks (ks_mod), ks (ks_key), e (binding_cont))
316             subchain = join (subchain, subch)
317         end
318     end
319
320     -- Then return an actual `awful.key', triggering the `on_entering' routine
321     return akey (m, k, make_on_entering (m, k, subchain))
322 end
323 --}}}
324
325 -- Setup `__call' entry in module's metatable so that we can create new prefix
326 -- binding using `keychain (m, k, ...)' directly.
327 setmetatable (_M, { __call = function (_, ...) return new (...) end })
328
329 -- Local variables:
330 -- indent-tabs-mode: nil
331 -- fill-column: 80
332 -- lua-indent-level: 4
333 -- End:
334 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=80