Artifact ID:	b77fb8ba5db39e91ed38fae5c3831c11ad863953
Page Name:	plugin meta data
Date:	2015-04-03 18:58:04
Original User:	mario
Next	f375b827c8459e7d810f53a25dc7243573323970

# Plugin meta spec

Streamtuner2 now uses a proper plugin description scheme. Note that this is completely unrelated to the streamtuner2 or channels API, or how plugins are actually initialized (pkgutil, imp, implib, pluginbase/plugnplay).

Basically the top-level comment block is scanned on initialization. It simply lists a few `key: values` for documentation and technical descriptors. It's basically a subset of YAML embedded in a script comment.

# api: streamtuner2 # type: feature # title: My Plugin # description: Lists all the things # version: 1.0 # category: music # config: { name: myconf, value: 1, type: boolean, description: enable foo } # # And here goes a longer doc/comment.

The key names are case-insensitive of course. A few fields like `title:`, `description:` are required. Theoretically also the `api:` and `type:`. But they're only used for decorative purposes like the `category:` or `version:` field.

More interestingly the `config:` field can be used to describe plugin options. Default values will automatically end up in streamtuners `conf.*` dict, and are presented to users in the config dialog.

* A `value:` represents the default. * The `type: select` can be used for dropdown boxes, with a `select: key=VAl|key2=VAL2..` attribute for options. * Other `type:` values are interpreted as strings, except `type: boolean` which becomes a checkbox. * A per-option `category:` attribute is ignored at the moment. * Params can be optionally quoted as in `value: "Desc, desc, desc." if they contain commas (which otherwise separate option attrs.)

And of course, the `config:` field can list multiple options. Simply make it multi-line (every plugin meta field can be) by indenting wrapped lines.

### Why?

This scheme is designed to be language-agnostic. It originated in PHP way back (see libconfig(http://milki.include-once.org/genericplugins/)), precisely to avoid common misdesigns.

* Meta data does not belong *in code*. Because that incurs importing them, even when they may go uninitialized/unused. * And it certainly should not reside in externalized ini/json data stores. **Because that's how you get ants!**

The meta description block also can double as packaging format. The `pack:` descriptor is used by fpm/xpm -s src(http://fossil.include-once.org/xpm/wiki/src). Which avoids manually concocting separated setup.py/.cfg as the current Python packaging eco system does. (This is stuff which can be automated, without requiring meta information to be doubled in-code and dutifully dished up for pip/setuptools).