<commit_before># Hammerspoon Spoon Plugins Documentation

* [What is a Spoon?](#what-is-a-spoon)
* [Where do I get Spoons from?](#where-do-i-get-spoons-from)
* [How do I install a Spoon?](#how-do-i-install-a-spoon)
* [How do I use a Spoon?](#how-do-i-use-a-spoon)
    * [Loading a Spoon](#loading-a-spoon)
    * [Integrating into your configuration](#integrating-into-your-configuration)
* [How do I create a Spoon?](#how-do-i-create-a-spoon)
    * [API Conventions](#api-conventions)
        * [Naming](#naming)
        * [Initialisation](#initialisation)
        * [Metadata](#metadata)
        * [Starting/Stopping](#startingstopping)
        * [Hotkeys](#hotkeys)
        * [Other](#other)
    * [Documentation](#documentation)
        * [Writing](#writing)
        * [Generating](#generating)
    * [Loading files](#loading-files)
        * [Code](#code)
        * [Assets](#assets)

## What is a Spoon?

Spoons are intended to be pure-Lua plugins for users to use in their Hammerspoon configs.

As a community, we have created many great configurations for Hammerspoon, but sharing code between them is hard and fragile. Spoons have been created as a way to address these issues.
Users should be able to download a Spoon and quickly integrate it into their config without worrying about what it is doing internally.

This is possible because of two things:

 * Infrastructure within Hammerspoon for loading Lua code from Spoons
 * The authors of Spoons sticking, wherever possible, to a standard API for users to use

## Where do I get Spoons from?

The official repository of Spoons is [http://www.hammerspoon.org/Spoons](http://www.hammerspoon.org/Spoons) (the source for which can be found at [https://github.com/Hammerspoon/Spoons](https://github.com/Hammerspoon/Spoons)), but authors may choose to distribute them separately from their own sites.

## How do I install a Spoon?

Spoons should be distributed as `.zip` files. Simply download one, uncompress it (if your browser hasn't done that part automatically) and double click on the Spoon. Hammerspoon will install it for you in `~/.hammerspoon/Spoons/`

## How do I use a Spoon?

There are two parts to this, loading the spoon, and integrating it into your configuration.
Hopefully the Spoon came with some documentation, either on its homepage or in `~/.hammerspoon/Spoons/NAME.spoon`. There you should find some documentation of the API offered by the Spoon, and any special requirements it has.

### Loading a Spoon

For most Spoons, simply add `hs.loadSpoon(NAME)` to your Hammerspoon config (note that `NAME` should *not* include the `.spoon` extension). This will make the spoon available in the global Lua namespace as `spoon.NAME`.

### Integrating into your configuration

In most cases, the API should take roughly this form:

 * `NAME:init()` - this is called automatically by `hs.loadSpoon()` and will do any initial setup work required, but should generally not start taking any actions
 * `NAME:start()` - if any kind of background work is necessary, this method will start it
 * `NAME:stop()` - if any kind of background work is running, this method will stop it
 * `NAME:bindHotkeys(mapping)` - this method is used to tell the Spoon how to bind hotkeys for its various functions. Depending on the Spoon, these hotkeys may be bound immediately, or when `:start()` is called. This method should accept a single argument, a table in the form:

```lua
  { someFeature = {{"cmd", "alt"}, "f"},
    otherFeature = {{"shift", "ctrl"}, "b"}}
```

The Spoon should also provide some standard metadata:

 * `NAME.name` - A string containing the name of the Spoon
 * `NAME.version` - A string containing the version number of the Spoon<commit_msg>Fix a quoting omission in SPOONS.md<commit_after># Hammerspoon Spoon Plugins Documentation

* [What is a Spoon?](#what-is-a-spoon)
* [Where do I get Spoons from?](#where-do-i-get-spoons-from)
* [How do I install a Spoon?](#how-do-i-install-a-spoon)
* [How do I use a Spoon?](#how-do-i-use-a-spoon)
    * [Loading a Spoon](#loading-a-spoon)
    * [Integrating into your configuration](#integrating-into-your-configuration)
* [How do I create a Spoon?](#how-do-i-create-a-spoon)
    * [API Conventions](#api-conventions)
        * [Naming](#naming)
        * [Initialisation](#initialisation)
        * [Metadata](#metadata)
        * [Starting/Stopping](#startingstopping)
        * [Hotkeys](#hotkeys)
        * [Other](#other)
    * [Documentation](#documentation)
        * [Writing](#writing)
        * [Generating](#generating)
    * [Loading files](#loading-files)
        * [Code](#code)
        * [Assets](#assets)

## What is a Spoon?

Spoons are intended to be pure-Lua plugins for users to use in their Hammerspoon configs.

As a community, we have created many great configurations for Hammerspoon, but sharing code between them is hard and fragile. Spoons have been created as a way to address these issues.
Users should be able to download a Spoon and quickly integrate it into their config without worrying about what it is doing internally.

This is possible because of two things:

 * Infrastructure within Hammerspoon for loading Lua code from Spoons
 * The authors of Spoons sticking, wherever possible, to a standard API for users to use

## Where do I get Spoons from?

The official repository of Spoons is [http://www.hammerspoon.org/Spoons](http://www.hammerspoon.org/Spoons) (the source for which can be found at [https://github.com/Hammerspoon/Spoons](https://github.com/Hammerspoon/Spoons)), but authors may choose to distribute them separately from their own sites.

## How do I install a Spoon?

Spoons should be distributed as `.zip` files. Simply download one, uncompress it (if your browser hasn't done that part automatically) and double click on the Spoon. Hammerspoon will install it for you in `~/.hammerspoon/Spoons/`

## How do I use a Spoon?

There are two parts to this, loading the spoon, and integrating it into your configuration.
Hopefully the Spoon came with some documentation, either on its homepage or in `~/.hammerspoon/Spoons/NAME.spoon`. There you should find some documentation of the API offered by the Spoon, and any special requirements it has.

### Loading a Spoon

For most Spoons, simply add `hs.loadSpoon("NAME")` to your Hammerspoon config (note that `NAME` should *not* include the `.spoon` extension). This will make the spoon available in the global Lua namespace as `spoon.NAME`.

### Integrating into your configuration

In most cases, the API should take roughly this form:

 * `NAME:init()` - this is called automatically by `hs.loadSpoon()` and will do any initial setup work required, but should generally not start taking any actions
 * `NAME:start()` - if any kind of background work is necessary, this method will start it
 * `NAME:stop()` - if any kind of background work is running, this method will stop it
 * `NAME:bindHotkeys(mapping)` - this method is used to tell the Spoon how to bind hotkeys for its various functions. Depending on the Spoon, these hotkeys may be bound immediately, or when `:start()` is called. This method should accept a single argument, a table in the form:

```lua
  { someFeature = {{"cmd", "alt"}, "f"},
    otherFeature = {{"shift", "ctrl"}, "b"}}
```

The Spoon should also provide some standard metadata:

 * `NAME.name` - A string containing the name of the Spoon
 * `NAME.version` - A string containing the version number of the Spoon
{'fraction_non_alphanumeric': 0.10013404825737265, 'fraction_numerical': 0.0, 'mean_word_length': 4.07205982324949, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3450479', 'n_tokens_mistral': 2167, 'n_tokens_neox': 2057, 'n_words': 938}