hammerspoon/Spoons/SpoonInstall.spoon/init.lua

   1 --- === SpoonInstall ===
   2 ---
   3 --- Install and manage Spoons and Spoon repositories
   4 ---
   5 --- Download: [https://github.com/Hammerspoon/Spoons/raw/master/Spoons/SpoonInstall.spoon.zip](https://github.com/Hammerspoon/Spoons/raw/master/Spoons/SpoonInstall.spoon.zip)
   6
   7 local obj={}
   8 obj.__index = obj
   9
  10 -- Metadata
  11 obj.name = "SpoonInstall"
  12 obj.version = "0.1"
  13 obj.author = "Diego Zamboni <diego@zzamboni.org>"
  14 obj.homepage = "https://github.com/Hammerspoon/Spoons"
  15 obj.license = "MIT - https://opensource.org/licenses/MIT"
  16
  17 --- SpoonInstall.logger
  18 --- Variable
  19 --- Logger object used within the Spoon. Can be accessed to set the default log level for the messages coming from the Spoon.
  20 obj.logger = hs.logger.new('SpoonInstall')
  21
  22 --- SpoonInstall.repos
  23 --- Variable
  24 --- Table containing the list of available Spoon repositories. The key
  25 --- of each entry is an identifier for the repository, and its value
  26 --- is a table with the following entries:
  27 ---  * desc - Human-readable description for the repository
  28 ---  * url - Base URL for the repository. For now the repository is assumed to be hosted in GitHub, and the URL should be the main base URL of the repository. Repository metadata needs to be stored under `docs/docs.json`, and the Spoon zip files need to be stored under `Spoons/`.
  29 ---
  30 --- Default value:
  31 --- ```
  32 --- {
  33 ---    default = {
  34 ---       url = "https://github.com/Hammerspoon/Spoons",
  35 ---       desc = "Main Hammerspoon Spoon repository",
  36 ---    }
  37 --- }
  38 --- ```
  39 obj.repos = {
  40    default = {
  41       url = "https://github.com/Hammerspoon/Spoons",
  42       desc = "Main Hammerspoon Spoon repository",
  43    }
  44 }
  45
  46 --- SpoonInstall.use_syncinstall
  47 --- Variable
  48 --- If `true`, `andUse()` will update repos and install packages synchronously. Defaults to `false`.
  49 ---
  50 --- Keep in mind that if you set this to `true`, Hammerspoon will
  51 --- block until all missing Spoons are installed, but the notifications
  52 --- will happen at a more "human readable" rate.
  53 obj.use_syncinstall = false
  54
  55 -- Execute a command and return its output with trailing EOLs trimmed. If the command fails, an error message is logged.
  56 local function _x(cmd, errfmt, ...)
  57    local output, status = hs.execute(cmd)
  58    if status then
  59       local trimstr = string.gsub(output, "\n*$", "")
  60       return trimstr
  61    else
  62       obj.logger.ef(errfmt, ...)
  63       return nil
  64    end
  65 end
  66
  67 -- --------------------------------------------------------------------
  68 -- Spoon repository management
  69
  70 -- Internal callback to process and store the data from docs.json about a repository
  71 -- callback is called with repo as arguments, only if the call is successful
  72 function obj:_storeRepoJSON(repo, callback, status, body, hdrs)
  73    local success=nil
  74    if (status < 100) or (status >= 400) then
  75       self.logger.ef("Error fetching JSON data for repository '%s'. Error code %d: %s", repo, status, body or "<no error message>")
  76    else
  77       local json = hs.json.decode(body)
  78       if json then
  79          self.repos[repo].data = {}
  80          for i,v in ipairs(json) do
  81             v.download_url = self.repos[repo].download_base_url .. v.name .. ".spoon.zip"
  82             self.repos[repo].data[v.name] = v
  83          end
  84          self.logger.df("Updated JSON data for repository '%s'", repo)
  85          success=true
  86       else
  87          self.logger.ef("Invalid JSON received for repository '%s': %s", repo, body)
  88       end
  89    end
  90    if callback then
  91       callback(repo, success)
  92    end
  93    return success
  94 end
  95
  96 -- Internal function to return the URL of the docs.json file based on the URL of a GitHub repo
  97 function obj:_build_repo_json_url(repo)
  98    if self.repos[repo] and self.repos[repo].url then
  99       self.repos[repo].json_url = string.gsub(self.repos[repo].url, "/$", "") .. "/raw/master/docs/docs.json"
 100       self.repos[repo].download_base_url = string.gsub(self.repos[repo].url, "/$", "") .. "/raw/master/Spoons/"
 101       return true
 102    else
 103       self.logger.ef("Invalid or unknown repository '%s'", repo)
 104       return nil
 105    end
 106 end
 107
 108 --- SpoonInstall:asyncUpdateRepo(repo, callback)
 109 --- Method
 110 --- Asynchronously fetch the information about the contents of a Spoon repository
 111 ---
 112 --- Parameters:
 113 ---  * repo - name of the repository to update. Defaults to `"default"`.
 114 ---  * callback - if given, a function to be called after the update finishes (also if it fails). The function will receive the following arguments:
 115 ---    * repo - name of the repository
 116 ---    * success - boolean indicating whether the update succeeded
 117 ---
 118 --- Returns:
 119 ---  * `true` if the update was correctly initiated (i.e. the repo name is valid), `nil` otherwise
 120 ---
 121 --- Notes:
 122 ---  * For now, the repository data is not persisted, so you need to update it after every restart if you want to use any of the install functions.
 123 function obj:asyncUpdateRepo(repo, callback)
 124    if not repo then repo = 'default' end
 125    if self:_build_repo_json_url(repo) then
 126       hs.http.asyncGet(self.repos[repo].json_url, nil, hs.fnutils.partial(self._storeRepoJSON, self, repo, callback))
 127       return true
 128    else
 129       return nil
 130    end
 131 end
 132
 133 --- SpoonInstall:updateRepo(repo)
 134 --- Method
 135 --- Synchronously fetch the information about the contents of a Spoon repository
 136 ---
 137 --- Parameters:
 138 ---  * repo - name of the repository to update. Defaults to `"default"`.
 139 ---
 140 --- Returns:
 141 ---  * `true` if the update was successful, `nil` otherwise
 142 ---
 143 --- Notes:
 144 ---  * This is a synchronous call, which means Hammerspoon will be blocked until it finishes. For use in your configuration files, it's advisable to use `SpoonInstall.asyncUpdateRepo()` instead.
 145 ---  * For now, the repository data is not persisted, so you need to update it after every restart if you want to use any of the install functions.
 146 function obj:updateRepo(repo)
 147    if not repo then repo = 'default' end
 148    if self:_build_repo_json_url(repo) then
 149       local a,b,c = hs.http.get(self.repos[repo].json_url)
 150       return self:_storeRepoJSON(repo, nil, a, b, c)
 151    else
 152       return nil
 153    end
 154 end
 155
 156 --- SpoonInstall:updateAllRepos()
 157 --- Method
 158 --- Synchronously fetch the information about the contents of all Spoon repositories registered in `SpoonInstall.repos`
 159 ---
 160 --- Parameters:
 161 ---  * None
 162 ---
 163 --- Returns:
 164 ---  * None
 165 ---
 166 --- Notes:
 167 ---  * This is a synchronous call, which means Hammerspoon will be blocked until it finishes.
 168 ---  * For now, the repository data is not persisted, so you need to update it after every restart if you want to use any of the install functions.
 169 function obj:updateAllRepos()
 170    for k,v in pairs(self.repos) do
 171       self:updateRepo(k)
 172    end
 173 end
 174
 175 --- SpoonInstall:repolist()
 176 --- Method
 177 --- Return a sorted list of registered Spoon repositories
 178 ---
 179 --- Parameters:
 180 ---  * None
 181 ---
 182 --- Returns:
 183 ---  * Table containing a list of strings with the repository identifiers
 184 function obj:repolist()
 185    local keys={}
 186    -- Create sorted list of keys
 187    for k,v in pairs(self.repos) do table.insert(keys, k) end
 188    table.sort(keys)
 189    return keys
 190 end
 191
 192 --- SpoonInstall:search(pat)
 193 --- Method
 194 --- Search repositories for a pattern
 195 ---
 196 --- Parameters:
 197 ---  * pat - Lua pattern that will be matched against the name and description of each spoon in the registered repositories. All text is converted to lowercase before searching it, so you can use all-lowercase in your pattern.
 198 ---
 199 --- Returns:
 200 ---  * Table containing a list of matching entries. Each entry is a table with the following keys:
 201 ---    * name - Spoon name
 202 ---    * desc - description of the spoon
 203 ---    * repo - identifier in the repository where the match was found
 204 function obj:search(pat)
 205    local res={}
 206    for repo,v in pairs(self.repos) do
 207       if v.data then
 208          for spoon,rec in pairs(v.data) do
 209             if string.find(string.lower(rec.name .. "\n" .. rec.desc), pat) then
 210                table.insert(res, { name = rec.name, desc = rec.desc, repo = repo })
 211             end
 212          end
 213       else
 214          self.logger.ef("Repository data for '%s' not available - call spoon.SpoonInstall:updateRepo('%s'), then try again.", repo, repo)
 215       end
 216    end
 217    return res
 218 end
 219
 220 -- --------------------------------------------------------------------
 221 -- Spoon installation
 222
 223 -- Internal callback function to finalize the installation of a spoon after the zip file has been downloaded.
 224 -- callback, if given, is called with (urlparts, success) as arguments
 225 function obj:_installSpoonFromZipURLgetCallback(urlparts, callback, status, body, headers)
 226    local success=nil
 227    if (status < 100) or (status >= 400) then
 228       self.logger.ef("Error downloading %s. Error code %d: %s", urlparts.absoluteString, status, body or "<none>")
 229    else
 230       -- Write the zip file to disk in a temporary directory
 231       local tmpdir=_x("/usr/bin/mktemp -d", "Error creating temporary directory to download new spoon.")
 232       if tmpdir then
 233          local outfile = string.format("%s/%s", tmpdir, urlparts.lastPathComponent)
 234          local f=assert(io.open(outfile, "w"))
 235          f:write(body)
 236          f:close()
 237
 238          -- Check its contents - only one *.spoon directory should be in there
 239          output = _x(string.format("/usr/bin/unzip -l %s '*.spoon/' | /usr/bin/awk '$NF ~ /\\.spoon\\/$/ { print $NF }' | /usr/bin/wc -l", outfile),
 240                      "Error examining downloaded zip file %s, leaving it in place for your examination.", outfile)
 241          if output then
 242             if (tonumber(output) or 0) == 1 then
 243                -- Uncompress the zip file
 244                local outdir = string.format("%s/Spoons", hs.configdir)
 245                if _x(string.format("/usr/bin/unzip -o %s -d %s 2>&1", outfile, outdir),
 246                      "Error uncompressing file %s, leaving it in place for your examination.", outfile) then
 247                   -- And finally, install it using Hammerspoon itself
 248                   self.logger.f("Downloaded and installed %s", urlparts.absoluteString)
 249                   _x(string.format("/bin/rm -rf '%s'", tmpdir), "Error removing directory %s", tmpdir)
 250                   success=true
 251                end
 252             else
 253                self.logger.ef("The downloaded zip file %s is invalid - it should contain exactly one spoon. Leaving it in place for your examination.", outfile)
 254             end
 255          end
 256       end
 257    end
 258    if callback then
 259       callback(urlparts, success)
 260    end
 261    return success
 262 end
 263
 264 --- SpoonInstall:asyncInstallSpoonFromZipURL(url, callback)
 265 --- Method
 266 --- Asynchronously download a Spoon zip file and install it.
 267 ---
 268 --- Parameters:
 269 ---  * url - URL of the zip file to install.
 270 ---  * callback - if given, a function to call after the installation finishes (also if it fails). The function receives the following arguments:
 271 ---    * urlparts - Result of calling `hs.http.urlParts` on the URL of the Spoon zip file
 272 ---    * success - boolean indicating whether the installation was successful
 273 ---
 274 --- Returns:
 275 ---  * `true` if the installation was correctly initiated (i.e. the URL is valid), `false` otherwise
 276 function obj:asyncInstallSpoonFromZipURL(url, callback)
 277    local urlparts = hs.http.urlParts(url)
 278    local dlfile = urlparts.lastPathComponent
 279    if dlfile and dlfile ~= "" and urlparts.pathExtension == "zip" then
 280       hs.http.asyncGet(url, nil, hs.fnutils.partial(self._installSpoonFromZipURLgetCallback, self, urlparts, callback))
 281       return true
 282    else
 283       self.logger.ef("Invalid URL %s, must point to a zip file", url)
 284       return nil
 285    end
 286 end
 287
 288 --- SpoonInstall:installSpoonFromZipURL(url)
 289 --- Method
 290 --- Synchronously download a Spoon zip file and install it.
 291 ---
 292 --- Parameters:
 293 ---  * url - URL of the zip file to install.
 294 ---
 295 --- Returns:
 296 ---  * `true` if the installation was successful, `nil` otherwise
 297 function obj:installSpoonFromZipURL(url)
 298    local urlparts = hs.http.urlParts(url)
 299    local dlfile = urlparts.lastPathComponent
 300    if dlfile and dlfile ~= "" and urlparts.pathExtension == "zip" then
 301       a,b,c=hs.http.get(url)
 302       return self:_installSpoonFromZipURLgetCallback(urlparts, nil, a, b, c)
 303    else
 304       self.logger.ef("Invalid URL %s, must point to a zip file", url)
 305       return nil
 306    end
 307 end
 308
 309 -- Internal function to check if a Spoon/Repo combination is valid
 310 function obj:_is_valid_spoon(name, repo)
 311    if self.repos[repo] then
 312       if self.repos[repo].data then
 313          if self.repos[repo].data[name] then
 314             return true
 315          else
 316             self.logger.ef("Spoon '%s' does not exist in repository '%s'. Please check and try again.", name, repo)
 317          end
 318       else
 319          self.logger.ef("Repository data for '%s' not available - call spoon.SpoonInstall:updateRepo('%s'), then try again.", repo, repo)
 320       end
 321    else
 322       self.logger.ef("Invalid or unknown repository '%s'", repo)
 323    end
 324    return nil
 325 end
 326
 327 --- SpoonInstall:asyncInstallSpoonFromRepo(name, repo, callback)
 328 --- Method
 329 --- Asynchronously install a Spoon from a registered repository
 330 ---
 331 --- Parameters:
 332 ---  * name - Name of the Spoon to install.
 333 ---  * repo - Name of the repository to use. Defaults to `"default"`
 334 ---  * callback - if given, a function to call after the installation finishes (also if it fails). The function receives the following arguments:
 335 ---    * urlparts - Result of calling `hs.http.urlParts` on the URL of the Spoon zip file
 336 ---    * success - boolean indicating whether the installation was successful
 337 ---
 338 --- Returns:
 339 ---  * `true` if the installation was correctly initiated (i.e. the repo and spoon name were correct), `false` otherwise.
 340 function obj:asyncInstallSpoonFromRepo(name, repo, callback)
 341    if not repo then repo = 'default' end
 342    if self:_is_valid_spoon(name, repo) then
 343       self:asyncInstallSpoonFromZipURL(self.repos[repo].data[name].download_url, callback)
 344    end
 345    return nil
 346 end
 347
 348 --- SpoonInstall:installSpoonFromRepo(name, repo)
 349 --- Method
 350 --- Synchronously install a Spoon from a registered repository
 351 ---
 352 --- Parameters:
 353 ---  * name = Name of the Spoon to install.
 354 ---  * repo - Name of the repository to use. Defaults to `"default"`
 355 ---
 356 --- Returns:
 357 ---  * `true` if the installation was successful, `nil` otherwise.
 358 function obj:installSpoonFromRepo(name, repo, callback)
 359    if not repo then repo = 'default' end
 360    if self:_is_valid_spoon(name, repo) then
 361       return self:installSpoonFromZipURL(self.repos[repo].data[name].download_url)
 362    end
 363    return nil
 364 end
 365
 366 --- SpoonInstall:andUse(name, arg)
 367 --- Method
 368 --- Declaratively install, load and configure a Spoon
 369 ---
 370 --- Parameters:
 371 ---  * name - the name of the Spoon to install (without the `.spoon` extension). If the Spoon is already installed, it will be loaded using `hs.loadSpoon()`. If it is not installed, it will be installed using `SpoonInstall:asyncInstallSpoonFromRepo()` and then loaded.
 372 ---  * arg - if provided, can be used to specify the configuration of the Spoon. The following keys are recognized (all are optional):
 373 ---    * repo - repository from where the Spoon should be installed if not present in the system, as defined in `SpoonInstall.repos`. Defaults to `"default"`.
 374 ---    * config - a table containing variables to be stored in the Spoon object to configure it. For example, `config = { answer = 42 }` will result in `spoon.<LoadedSpoon>.answer` being set to 42.
 375 ---    * hotkeys - a table containing hotkey bindings. If provided, will be passed as-is to the Spoon's `bindHotkeys()` method. The special string `"default"` can be given to use the Spoons `defaultHotkeys` variable, if it exists.
 376 ---    * fn - a function which will be called with the freshly-loaded Spoon object as its first argument.
 377 ---    * loglevel - if the Spoon has a variable called `logger`, its `setLogLevel()` method will be called with this value.
 378 ---    * start - if `true`, call the Spoon's `start()` method after configuring everything else.
 379 ---    * disable - if `true`, do nothing. Easier than commenting it out when you want to temporarily disable a spoon.
 380 ---
 381 --- Returns:
 382 ---  * None
 383 function obj:andUse(name, arg)
 384    if not arg then arg = {} end
 385    if arg.disable then return true end
 386    if hs.spoons.use(name, arg, true) then
 387       return true
 388    else
 389       local repo = arg.repo or "default"
 390       if self.repos[repo] then
 391          if self.repos[repo].data then
 392             local load_and_config = function(_, success)
 393                if success then
 394                   hs.notify.show("Spoon installed by SpoonInstall", name .. ".spoon is now available", "")
 395                   hs.spoons.use(name, arg)
 396                else
 397                   obj.logger.ef("Error installing Spoon '%s' from repo '%s'", name, repo)
 398                end
 399             end
 400             if self.use_syncinstall then
 401                return load_and_config(nil, self:installSpoonFromRepo(name, repo))
 402             else
 403                self:asyncInstallSpoonFromRepo(name, repo, load_and_config)
 404             end
 405          else
 406             local update_repo_and_continue = function(_, success)
 407                if success then
 408                   obj:andUse(name, arg)
 409                else
 410                   obj.logger.ef("Error updating repository '%s'", repo)
 411                end
 412             end
 413             if self.use_syncinstall then
 414                return update_repo_and_continue(nil, self:updateRepo(repo))
 415             else
 416                self:asyncUpdateRepo(repo, update_repo_and_continue)
 417             end
 418          end
 419       else
 420          obj.logger.ef("Unknown repository '%s' for Spoon", repo, name)
 421       end
 422    end
 423 end
 424
 425 return obj