1 --- === SpoonInstall ===
3 --- Install and manage Spoons and Spoon repositories
5 --- Download: [https://github.com/Hammerspoon/Spoons/raw/master/Spoons/SpoonInstall.spoon.zip](https://github.com/Hammerspoon/Spoons/raw/master/Spoons/SpoonInstall.spoon.zip)
11 obj.name = "SpoonInstall"
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"
17 --- SpoonInstall.logger
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')
22 --- SpoonInstall.repos
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/`.
34 --- url = "https://github.com/Hammerspoon/Spoons",
35 --- desc = "Main Hammerspoon Spoon repository",
41 url = "https://github.com/Hammerspoon/Spoons",
42 desc = "Main Hammerspoon Spoon repository",
46 --- SpoonInstall.use_syncinstall
48 --- If `true`, `andUse()` will update repos and install packages synchronously. Defaults to `false`.
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
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)
59 local trimstr = string.gsub(output, "\n*$", "")
62 obj.logger.ef(errfmt, ...)
67 -- --------------------------------------------------------------------
68 -- Spoon repository management
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)
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>")
77 local json = hs.json.decode(body)
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
84 self.logger.df("Updated JSON data for repository '%s'", repo)
87 self.logger.ef("Invalid JSON received for repository '%s': %s", repo, body)
91 callback(repo, success)
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/"
103 self.logger.ef("Invalid or unknown repository '%s'", repo)
108 --- SpoonInstall:asyncUpdateRepo(repo, callback)
110 --- Asynchronously fetch the information about the contents of a Spoon repository
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
119 --- * `true` if the update was correctly initiated (i.e. the repo name is valid), `nil` otherwise
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))
133 --- SpoonInstall:updateRepo(repo)
135 --- Synchronously fetch the information about the contents of a Spoon repository
138 --- * repo - name of the repository to update. Defaults to `"default"`.
141 --- * `true` if the update was successful, `nil` otherwise
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)
156 --- SpoonInstall:updateAllRepos()
158 --- Synchronously fetch the information about the contents of all Spoon repositories registered in `SpoonInstall.repos`
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
175 --- SpoonInstall:repolist()
177 --- Return a sorted list of registered Spoon repositories
183 --- * Table containing a list of strings with the repository identifiers
184 function obj:repolist()
186 -- Create sorted list of keys
187 for k,v in pairs(self.repos) do table.insert(keys, k) end
192 --- SpoonInstall:search(pat)
194 --- Search repositories for a pattern
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.
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)
206 for repo,v in pairs(self.repos) do
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 })
214 self.logger.ef("Repository data for '%s' not available - call spoon.SpoonInstall:updateRepo('%s'), then try again.", repo, repo)
220 -- --------------------------------------------------------------------
221 -- Spoon installation
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)
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>")
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.")
233 local outfile = string.format("%s/%s", tmpdir, urlparts.lastPathComponent)
234 local f=assert(io.open(outfile, "w"))
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)
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)
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)
259 callback(urlparts, success)
264 --- SpoonInstall:asyncInstallSpoonFromZipURL(url, callback)
266 --- Asynchronously download a Spoon zip file and install it.
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
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))
283 self.logger.ef("Invalid URL %s, must point to a zip file", url)
288 --- SpoonInstall:installSpoonFromZipURL(url)
290 --- Synchronously download a Spoon zip file and install it.
293 --- * url - URL of the zip file to install.
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)
304 self.logger.ef("Invalid URL %s, must point to a zip file", url)
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
316 self.logger.ef("Spoon '%s' does not exist in repository '%s'. Please check and try again.", name, repo)
319 self.logger.ef("Repository data for '%s' not available - call spoon.SpoonInstall:updateRepo('%s'), then try again.", repo, repo)
322 self.logger.ef("Invalid or unknown repository '%s'", repo)
327 --- SpoonInstall:asyncInstallSpoonFromRepo(name, repo, callback)
329 --- Asynchronously install a Spoon from a registered repository
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
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)
348 --- SpoonInstall:installSpoonFromRepo(name, repo)
350 --- Synchronously install a Spoon from a registered repository
353 --- * name = Name of the Spoon to install.
354 --- * repo - Name of the repository to use. Defaults to `"default"`
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)
366 --- SpoonInstall:andUse(name, arg)
368 --- Declaratively install, load and configure a Spoon
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.
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
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)
394 hs.notify.show("Spoon installed by SpoonInstall", name .. ".spoon is now available", "")
395 hs.spoons.use(name, arg)
397 obj.logger.ef("Error installing Spoon '%s' from repo '%s'", name, repo)
400 if self.use_syncinstall then
401 return load_and_config(nil, self:installSpoonFromRepo(name, repo))
403 self:asyncInstallSpoonFromRepo(name, repo, load_and_config)
406 local update_repo_and_continue = function(_, success)
408 obj:andUse(name, arg)
410 obj.logger.ef("Error updating repository '%s'", repo)
413 if self.use_syncinstall then
414 return update_repo_and_continue(nil, self:updateRepo(repo))
416 self:asyncUpdateRepo(repo, update_repo_and_continue)
420 obj.logger.ef("Unknown repository '%s' for Spoon", repo, name)