├── .gitignore ├── Dockerfile.toolbox ├── LICENSE ├── Makefile ├── README.md ├── config.ld ├── init.lua └── rockspec ├── awesome-ez-0.3.0-2.rockspec └── awesome-ez-devel-2.rockspec /.gitignore: -------------------------------------------------------------------------------- 1 | gh-pages 2 | -------------------------------------------------------------------------------- /Dockerfile.toolbox: -------------------------------------------------------------------------------- 1 | FROM supplantr/lua-toolbox 2 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2019-2020 James Reed 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 4 | 5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 6 | 7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 8 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | URL = git@github.com:jcrd/awesome-ez 2 | 3 | rock: 4 | luarocks make --local rockspec/awesome-ez-devel-1.rockspec 5 | 6 | gh-pages: 7 | git clone -b gh-pages --single-branch $(URL) gh-pages 8 | 9 | ldoc: gh-pages 10 | ldoc . -d gh-pages 11 | 12 | serve: gh-pages 13 | python -m http.server --directory gh-pages 14 | 15 | .PHONY: rock ldoc serve 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # awesome-ez 2 | 3 | awesome-ez is a library for [Awesome](https://github.com/awesomeWM/awesome) 4 | window manager that aims to simplify the creation of key and button bindings. 5 | It is based on code from the old Awesome wiki. 6 | 7 | ## Installation 8 | 9 | Install the latest stable release with `luarocks`: 10 | 11 | ```sh 12 | luarocks install awesome-ez 13 | ``` 14 | 15 | ## Usage 16 | 17 | Require the library: 18 | 19 | ```lua 20 | local ez = require("awesome-ez") 21 | ``` 22 | 23 | Use `ez.keytable` to define key bindings: 24 | 25 | ```lua 26 | local globalkeys = ez.keytable { 27 | ["M-Return"] = {awful.spawn, "xterm"}, 28 | ... 29 | } 30 | ``` 31 | 32 | Use `ez.btntable` to define button bindings: 33 | 34 | ```lua 35 | local clientbtns = ez.btntable { 36 | ["1"] = function (c) client.focus = c end, 37 | ["M-1"] = awful.mouse.client.move, 38 | ["M-3"] = awful.mouse.client.resize, 39 | } 40 | ``` 41 | 42 | Binding definition strings consist of modifier characters and a key or button 43 | separated by hyphens, e.g. `M-S-x` is the combination of `Mod4`, `Shift`, and 44 | the `x` key. 45 | 46 | See the [API documentation](https://jcrd.github.io/awesome-ez/) for 47 | descriptions of all functions. 48 | 49 | ### Modifiers 50 | 51 | The following modifiers can be identified by their default shorthand characters 52 | in key and button definitions: 53 | 54 | Character | Modifier 55 | --------- | -------- 56 | M | Mod4 57 | A | Mod1 58 | S | Shift 59 | C | Control 60 | 61 | The `modifiers` table can be customized: 62 | 63 | ```lua 64 | ez.modifiers["M"] = "Mod1" 65 | ``` 66 | 67 | ## License 68 | 69 | This project is licensed under the MIT License (see [LICENSE](LICENSE)). 70 | -------------------------------------------------------------------------------- /config.ld: -------------------------------------------------------------------------------- 1 | -- ldoc config 2 | 3 | project='awesome-ez' 4 | title='awesome-ez API documentation' 5 | description='API documentation for awesome-ez, a library for Awesome WM' 6 | file='init.lua' 7 | 8 | -- vim: ft=lua 9 | -------------------------------------------------------------------------------- /init.lua: -------------------------------------------------------------------------------- 1 | -- This project is licensed under the MIT License (see LICENSE). 2 | 3 | --- Create key and button bindings from simple definitions. 4 | -- 5 | -- @author James Reed <jcrd@tuta.io> et al. 6 | -- @copyright 2019-2020 James Reed 7 | -- @module awesome-ez 8 | 9 | local awful = require("awful") 10 | local gtable = require("gears.table") 11 | 12 | local ez = {} 13 | 14 | ez.modifiers = { 15 | ["M"] = "Mod4", 16 | ["A"] = "Mod1", 17 | ["S"] = "Shift", 18 | ["C"] = "Control", 19 | } 20 | 21 | --- Split a string on a delimiter. 22 | -- 23 | -- @param s The string. 24 | -- @param sep The delimiter. 25 | -- @return A table of strings. 26 | local function split(s, sep) 27 | sep = sep or "%s" 28 | local res = {} 29 | for m in string.gmatch(s, string.format("([^%s]+)", sep)) do 30 | table.insert(res, m) 31 | end 32 | return res 33 | end 34 | 35 | ez.util = {} 36 | 37 | --- Convert a table into a callable function. 38 | -- 39 | -- The first element of the table should be a function, followed by arguments 40 | -- to this function. 41 | -- 42 | -- @param cb The callback or a table describing the callback. 43 | -- @usage local cb = ez.util.cb_from_table({awful.spawn, "xterm"}) 44 | -- @return The callback. 45 | function ez.util.cb_from_table(cb) 46 | if type(cb) == "table" and 47 | not (getmetatable(cb) and getmetatable(cb).__call) then 48 | local tbl = gtable.clone(cb, false) 49 | local func = table.remove(tbl, 1) 50 | cb = function() 51 | return func(unpack(tbl)) 52 | end 53 | end 54 | return cb 55 | end 56 | 57 | --- Parse a key definition string into modifiers and a key. 58 | -- 59 | -- Key definition strings consist of modifier characters and a key separated 60 | -- by hyphens, e.g. "M-S-x" is the combination of Mod4, Shift, and the x key. 61 | -- If the key is surrounded by <>, it is interpreted as a key group, e.g. 62 | -- "M-<numrow> uses the modifier Mod4 and the key group "numrow". 63 | -- 64 | -- The modifier key strings are: M = Mod4, A = Mod1, S = Shift, C = Control. 65 | -- 66 | -- @param keydef The key definition string. 67 | -- @usage local modkeys, key = ez.util.parse_key("M-Return") 68 | -- @return A table of modifiers and the key. 69 | function ez.util.parse_key(keydef) 70 | local modkeys = {} 71 | for _, key in ipairs(split(keydef, "-")) do 72 | if ez.modifiers[key] ~= nil then 73 | table.insert(modkeys, ez.modifiers[key]) 74 | else 75 | local group = string.match(key, "<(%w+)>") 76 | if group then 77 | return modkeys, nil, group 78 | end 79 | return modkeys, key 80 | end 81 | end 82 | end 83 | 84 | --- Parse a button definition string into modifiers and a button. 85 | -- 86 | -- Button definition strings consist of modifier characters and a key separated 87 | -- by hyphens, e.g. "M-S-1" is the combination of Mod4, Shift, and button 1. 88 | -- 89 | -- The modifier key strings are: M = Mod4, A = Mod1, S = Shift, C = Control. 90 | -- 91 | -- @param btndef The button definition string. 92 | -- @usage local modkeys, btn = ez.util.parse_button("M-1") 93 | -- @return A table of modifiers and the button. 94 | function ez.util.parse_button(btndef) 95 | if type(btndef) == "number" then 96 | return {}, btndef 97 | end 98 | local modkeys = {} 99 | for _, key in ipairs(split(btndef, "-")) do 100 | if ez.modifiers[key] ~= nil then 101 | table.insert(modkeys, ez.modifiers[key]) 102 | else 103 | return modkeys, tonumber(key) 104 | end 105 | end 106 | end 107 | 108 | --- Create a key binding from a key definition string and callback. 109 | -- 110 | -- @param keydef The key definition string. 111 | -- @param cb The callback or table describing the callback. 112 | -- @return A table with the key objects. 113 | function ez.key(keydef, cb) 114 | local modkeys, key, group = ez.util.parse_key(keydef) 115 | if group then 116 | return awful.key { 117 | keygroup = group, 118 | modifiers = modkeys, 119 | on_press = cb, 120 | } 121 | end 122 | return awful.key(modkeys, key, ez.util.cb_from_table(cb)) 123 | end 124 | 125 | --- Create a button binding from a button definition string and callback. 126 | -- 127 | -- @param btndef The button definition string. 128 | -- @param cb The callback or table describing the callback. 129 | -- @return A table with the button objects. 130 | function ez.btn(btndef, cb) 131 | local modkeys, btn = ez.util.parse_button(btndef) 132 | return awful.button(modkeys, btn, ez.util.cb_from_table(cb)) 133 | end 134 | 135 | --- Create key bindings for elements of a table. 136 | -- 137 | -- @param tbl The table of key bindings. 138 | -- @return A table containing created key objects. 139 | function ez.keytable(tbl) 140 | local res = {} 141 | for keydef, cb in pairs(tbl) do 142 | table.insert(res, ez.key(keydef, cb)) 143 | end 144 | return res 145 | end 146 | 147 | --- Create button bindings for elements of a table. 148 | -- 149 | -- @param tbl The table of button bindings. 150 | -- @return A table containing created button objects. 151 | function ez.btntable(tbl) 152 | local res = {} 153 | for btndef, cb in pairs(tbl) do 154 | table.insert(res, ez.btn(btndef, cb)) 155 | end 156 | return res 157 | end 158 | 159 | return ez 160 | -------------------------------------------------------------------------------- /rockspec/awesome-ez-0.3.0-2.rockspec: -------------------------------------------------------------------------------- 1 | package = "awesome-ez" 2 | version = "0.3.0-2" 3 | source = { 4 | url = "git+https://github.com/jcrd/awesome-ez", 5 | tag = "v0.3.0", 6 | } 7 | description = { 8 | summary = "AwesomeWM library for simplifying key and button bindings", 9 | homepage = "https://github.com/jcrd/awesome-ez", 10 | license = "MIT", 11 | } 12 | dependencies = { 13 | "lua >= 5.1", 14 | } 15 | build = { 16 | type = "builtin", 17 | modules = { 18 | ["awesome-ez"] = "init.lua", 19 | }, 20 | } 21 | -------------------------------------------------------------------------------- /rockspec/awesome-ez-devel-2.rockspec: -------------------------------------------------------------------------------- 1 | package = "awesome-ez" 2 | version = "devel-2" 3 | source = { 4 | url = "git+https://github.com/jcrd/awesome-ez", 5 | tag = "master", 6 | } 7 | description = { 8 | summary = "AwesomeWM library for simplifying key and button bindings", 9 | homepage = "https://github.com/jcrd/awesome-ez", 10 | license = "MIT", 11 | } 12 | dependencies = { 13 | "lua >= 5.1", 14 | } 15 | build = { 16 | type = "builtin", 17 | modules = { 18 | ["awesome-ez"] = "init.lua", 19 | }, 20 | } 21 | --------------------------------------------------------------------------------