# Widget type templates

Before writing a new widget type, make sure to ask yourself if anyone is going
to need the feature.  Only widget types that you (or an incapacitated friend
you can personally talk to) require would be merged.  Do not file PRs because
they seem like a good idea.  If they're really useful, they'll be requested
in the issue tracker.

Additionally, too simple widget types (e.g. an one-liner) and those that
are not modular enough are very unlikely to be merged.  By *modular*, we mean

> constructed with standardized units or dimensions
> allowing flexibility and variety in use

If all the above conditions are met, you can start from one of the templates
in this directory:

* `sync.lua`: synchronous widget type that does not fork
* `async.lua`: asynchronous widget type for fetching informations using
  a command-line utility.  As a rule of thumb, if your widget type uses
  `io.popen`, you would need to refactor it to use async facilities.

Your widget types should be placed in `widgets`: the `contrib` directory
exists only for historical reasons and is barely maintained anymore.
The filenames should be of the form `<name>_<platform>.lua`, whereas

* `<name>` is a single (alphanumeric) word, preferably in lowercase
* `<platform>` is the OS that the widget type works on.
  At the time of writing these are supported:
    - `freebsd`: FreeBSD
    - `openbsd`: OpenBSD
    - `bsd`: all \*BSDs listed above
    - `linux`: GNU/Linux
    - `all`: all of the above

Please be aware of `luacheck`, which may help you during the progress.
From `widgets`, run

    luacheck --config .luacheckrc ..

After finishing the widget type, you should document its usage in the project's
`README.md`.  Try to provide at least

* A brief description
* The list of supported platforms
* Type and structures of the arguments that the widget type passes
  (`format` and `warg`), with unused parameters omitted
* Type and structure of the return value