Hammerspoon
Making Spoons more Discoverable and Easier to Use
Spoons are a tremendous idea! Thanks for implementing. Should make HS much more approachable to non-experts. Currently they are a bit hard to discover and use for novices. Some ideas to make this easier for even non-Lua-aware users (based loosely on how Emacs packages work):
- A list of Spoons in the repository, with version, one-line description, an accessible longer description, website, and author for each, linked to from the HS menu. A popularity score based on download count would be useful too.
- Enable/disable installed Spoons and list associated bindings from a menu.
- A minimal example for configuring each Spoon would be very helpful (on the Spoon's website).
- Instead of the current (and hard to discover) Spoon invocation method of:
local obj=hs.loadSpoon(NAME)
obj:bindHotKeys(...)
obj:start()
consider a simpler method that "just works" out of the box — loading and starting all installed spoons automatically, and offering a fully optional configuration field to interact with the Spoon, ala
SpoonName.config={Hotkeys = {DoFeature = {{"ctrl"},"c"}},
configVar1 = "MyLabel",
configVar2 = 1.0}
This would require Spoon authors to create sensible defaults for these that work "out of the box" (even for key bindings!). HS would need to report on duplicate bindings. But many people would just adopt the default.
For this method to work, HS would load all Spoons, run the user config files to pick up any optional new configuration, then start all loaded and enabled Spoons.
Maybe this is too big a change this late. If the load/bind/start version is kept, some clear examples of this pattern in the docs would be helpful.
FYI: This issue might be of interest, to learn some of the history of Spoons:
https://github.com/Hammerspoon/hammerspoon/issues/1182
FWIW, you can get a list of the installed spoons (only the ones you have downloaded, unfortunately... will have to consider expanding this) by typing help.spoon into the console. A web view based version of the built in help system can be invoked with hs.doc.hsdocs.help() and from there, click on the "Spoons" tab about halfway down the page.
I think someone was working on a spoon to download and install other spoons at one time... I'll have to look and see if that went anywhere and can be leveraged to show documentation for spoons that aren't currently installed.
There is a whole discussion about "auto-execution" in the link @latenitefilms provided, so I won't go into it here...
As to "default" key bindings, spoon authors can pre-define a default set as a table named defaultHotkeys in the spoon (see help.hs.spoons.use though it's not actually used unless the spoon is loaded with that method and the user specifies "default" ... I admit this isn't as well documented as it probably should be.
hs.hotkey already notifies about conflicting key bindings, though its been a while since I've checked... it may not be as clear about it as it could be.
Thanks guys. I see I'm late to the discussion, and a great deal of thought has already been put in on the best approach. I definitely lean towards the "make packages/plugins easy to load and operate" with the idea that you can attract a larger user base that way, and some number will dig into the Lua code and become coders and contributors. That's the model that Emacs uses for instance (you don't need to know Elisp to use packages, but eventually... you may get sucked in). I'll try my hand at making a Spoon soon.
To guide the glide path, it would be very useful to put a small example of how a Spoon is loaded, hotkeys set, and started somewhere near the top of the Hammerspoon Spoon Plugins Documentation page.
We do have http://www.hammerspoon.org/Spoons/SpoonInstall.html which can help.
I'm still torn on this stuff though - I'm really worried about making this all too easy to use, it changes the type of user that Hammerspoon attracts, and that will have an impact on supporting users, and maybe on the easier-to-use Mac automation apps.
Ok, how about this - we could add a couple of examples to our Getting Started Guide that include Spoons? That would also close #58.
Anyone feel like nominating a couple of Spoons to cover, and proposing some text? :)
Sounds like a good plan. I think the right balance is attracting technical users who don’t know Lua but are interested in the scriptability. Make it easy for them to ramp up and see the power, make it simple to contribute their own Spoons for a broader audience. When emacs went to a simple package manager system, both users and developers flourished. Thanks for this tool. It’s rather amazing what one can do.
Added a very simple Spoon example to the Getting Started Guide: http://www.hammerspoon.org/go/#smartreload
I only now noticed this issue, sorry for my late participation.
My SpoonInstall spoon offers a declarative way to download and configure spoons.
About documentation, I wrote a "getting started with Spoons" article in my blog some time ago: http://zzamboni.org/post/using-spoons-in-hammerspoon/. @cmsj feel free to copy/link/use it as needed if you consider it appropriate. There are also a lot of examples in my hammerspoon config file at https://github.com/zzamboni/dot-hammerspoon/blob/master/init.org
@zzamboni 's spooninstall should be the default strategy for managing spoons. I would love to see it being moved to hammerspoon core.
I think we need some more pieces first - eg updating Spoons, which means we need to publish version information. In general I agree though.
@zzamboni Thank you very much! I updated my config file according to your blog article. SpoonInstall is awesome!
@cmsj Is it possible to host official and third-party spoons on one repository just like mepla?
@hanjianwei the official repo is made up mostly of third party spoons. People still have to wait for me to merge the PRs, but I'm happy to host any reasonable Spoon here :)
@hanjianwei please note that SpoonInstall allows you to define and use your own repositories. I keep my own at https://github.com/zzamboni/zzSpoons/.