1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
-
+
-
+
-
+
-
-
-
-
-
+
+
+
+
+
-
+
-
+
-
-
+
+
+
-
+
-
+
+
+
+
|
# 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.
Basically the top-level comment block is scanned on initialization. It simply lists a few <kbd>key: values</kbd> 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.
The key names are case-insensitive of course. A few fields like <kbd>title:</kbd>, <kbd>description:</kbd> are required. Theoretically also the <kbd>api:</kbd> and <kbd>type:</kbd>. Though in ST2 they're currently just used for decorative purposes like the <kbd>category:</kbd> or <kbd>version:</kbd> 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.
More interestingly the <kbd>config:</kbd> 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.)
* A <kbd>value:</kbd> represents the default.
* The <kbd>type: select</kbd> can be used for dropdown boxes, with a `select:` <kbd>key=VAl|key2=VAL2..</kbd> attribute for options.
* Other <kbd>type:</kbd> values are interpreted as strings, except <kbd>type: boolean</kbd> which becomes a checkbox.
* A per-option <kbd>category:</kbd> attribute is ignored at the moment.
* Params can be optionally quoted as in <kbd>value: "Desc, desc, desc."</kbd> in case 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.
And of course, the <kbd>config:</kbd> 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.
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 a few common misdesigns.
* Meta data does not belong *in code*.
Because that incurs importing them, even when they may go uninitialized/unused.
* Meta data does **not** belong *in code*.
Because that incurs always 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).
|