lib/awful/util.lua.in

   1 ---------------------------------------------------------------------------
   2 -- @author Julien Danjou &lt;julien@danjou.info&gt;
   3 -- @copyright 2008 Julien Danjou
   4 -- @release @AWESOME_VERSION@
   5 ---------------------------------------------------------------------------
   6
   7 -- Grab environment we need
   8 local os = os
   9 local io = io
  10 local assert = assert
  11 local loadstring = loadstring
  12 local loadfile = loadfile
  13 local debug = debug
  14 local print = print
  15 local type = type
  16 local rtable = table
  17 local pairs = pairs
  18 local capi =
  19 {
  20     awesome = awesome,
  21     mouse = mouse
  22 }
  23
  24 --- Utility module for awful
  25 module("awful.util")
  26
  27 table = {}
  28
  29 function deprecate(see)
  30     io.stderr:write("W: awful: function is deprecated")
  31     if see then
  32         io.stderr:write(", see " .. see)
  33     end
  34     io.stderr:write("\n")
  35     io.stderr:write(debug.traceback())
  36 end
  37
  38 --- Strip alpha part of color.
  39 -- @param color The color.
  40 -- @return The color without alpha channel.
  41 function color_strip_alpha(color)
  42     if color:len() == 9 then
  43         color = color:sub(1, 7)
  44     end
  45     return color
  46 end
  47
  48 --- Make i cycle.
  49 -- @param t A length.
  50 -- @param i An absolute index to fit into #t.
  51 -- @return The object at new index.
  52 function cycle(t, i)
  53     while i > t do i = i - t end
  54     while i < 1 do i = i + t end
  55     return i
  56 end
  57
  58 --- Create a directory
  59 -- @param dir The directory.
  60 -- @return mkdir return code
  61 function mkdir(dir)
  62     return os.execute("mkdir -p " .. dir)
  63 end
  64
  65 --- Spawn a program.
  66 -- @param cmd The command.
  67 -- @paran sn Enable startup-notification.
  68 -- @param screen The screen where to spawn window.
  69 -- @return The awesome.spawn return value.
  70 function spawn(cmd, sn, screen)
  71     if cmd and cmd ~= "" then
  72         if sn == nil then sn = true end
  73         return capi.awesome.spawn(cmd, sn, screen or capi.mouse.screen)
  74     end
  75 end
  76
  77 --- Read a program output and returns its output as a string.
  78 -- @param cmd The command to run.
  79 -- @return A string with the program output.
  80 function pread(cmd)
  81     if cmd and cmd ~= "" then
  82         local f, err = io.popen(cmd, 'r')
  83         if f then
  84             local s = f:read("*all")
  85             f:close()
  86             return s
  87         else
  88             print(err)
  89         end
  90     end
  91 end
  92
  93 --- Eval Lua code.
  94 -- @return The return value of Lua code.
  95 function eval(s)
  96     return assert(loadstring(s))()
  97 end
  98
  99 local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;", [">"] = "&gt;", ["&"] = "&amp;" };
 100 --- Escape a string from XML char.
 101 -- Useful to set raw text in textbox.
 102 -- @param text Text to escape.
 103 -- @return Escape text.
 104 function escape(text)
 105     return text and text:gsub("['&<>\"]", xml_entity_names) or nil
 106 end
 107
 108 local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-", amp = "&" };
 109 --- Unescape a string from entities.
 110 -- @param text Text to unescape.
 111 -- @return Unescaped text.
 112 function unescape(text)
 113     return text and text:gsub("&(%a+);", xml_entity_chars) or nil
 114 end
 115
 116 --- Check if a file is a Lua valid file.
 117 -- This is done by loading the content and compiling it with loadfile().
 118 -- @param path The file path.
 119 -- @return A function if everything is alright, a string with the error
 120 -- otherwise.
 121 function checkfile(path)
 122     local f, e = loadfile(path)
 123     -- Return function if function, otherwise return error.
 124     if f then return f end
 125     return e
 126 end
 127
 128 --- Try to restart awesome.
 129 -- It checks if the configuration file is valid, and then restart if it's ok.
 130 -- If it's not ok, the error will be returned.
 131 -- @return Never return if awesome restart, or return a string error.
 132 function restart()
 133     local c = checkfile(capi.awesome.conffile)
 134
 135     if type(c) ~= "function" then
 136         return c
 137     end
 138
 139     capi.awesome.restart()
 140 end
 141
 142 --- Get the user's config or cache dir.
 143 -- It first checks XDG_CONFIG_HOME / XDG_CACHE_HOME, but then goes with the
 144 -- default paths.
 145 -- @param d The directory to get (either "config" or "cache").
 146 -- @return A string containing the requested path.
 147 function getdir(d)
 148     if d == "config" then
 149         local dir = os.getenv("XDG_CONFIG_HOME")
 150         if dir then
 151             return dir .. "/awesome"
 152         end
 153         return os.getenv("HOME") .. "/.config/awesome"
 154     elseif d == "cache" then
 155         local dir = os.getenv("XDG_CACHE_HOME")
 156         if dir then
 157             return dir .. "/awesome"
 158         end
 159         return os.getenv("HOME").."/.cache/awesome"
 160     end
 161 end
 162
 163 --- Check if file exists and is readable.
 164 -- @param filename The file path
 165 -- @return True if file exists and readable.
 166 function file_readable(filename)
 167     local file = io.open(filename)
 168     if file then
 169         io.close(file)
 170         return true
 171     end
 172     return false
 173 end
 174
 175 local function subset_mask_apply(mask, set)
 176     local ret = {}
 177     for i = 1, #set do
 178         if mask[i] then
 179             rtable.insert(ret, set[i])
 180         end
 181     end
 182     return ret
 183 end
 184
 185 local function subset_next(mask)
 186     local i = 1
 187     while i <= #mask and mask[i] do
 188         mask[i] = false
 189         i = i + 1
 190     end
 191
 192     if i <= #mask then
 193         mask[i] = 1
 194         return true
 195     end
 196     return false
 197 end
 198
 199 --- Return all subsets of a specific set.
 200 -- This function, giving a set, will return all subset it.
 201 -- For example, if we consider a set with value { 10, 15, 34 },
 202 -- it will return a table containing 2^n set:
 203 -- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc.
 204 -- @param set A set.
 205 -- @return A table with all subset.
 206 function subsets(set)
 207     local mask = {}
 208     local ret = {}
 209     for i = 1, #set do mask[i] = false end
 210
 211     -- Insert the empty one
 212     rtable.insert(ret, {})
 213
 214     while subset_next(mask) do
 215         rtable.insert(ret, subset_mask_apply(mask, set))
 216     end
 217     return ret
 218 end
 219
 220 --- Join all tables given as parameters.
 221 -- This will iterate all tables and insert all their keys into a new table.
 222 -- @param args A list of tables to join
 223 -- @return A new table containing all keys from the arguments.
 224 function table.join(...)
 225     local ret = {}
 226     for i = 1, arg.n do
 227         if arg[i] then
 228             for k, v in pairs(arg[i]) do
 229                 if type(k) == "number" then
 230                     rtable.insert(ret, v)
 231                 else
 232                     ret[k] = v
 233                 end
 234             end
 235         end
 236     end
 237     return ret
 238 end
 239
 240 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=80