D 2018-07-04T18:42:53.314
L Plugin\sMeta\sData
N text/x-markdown
P 5842602a1218ed33b103912d02882c4cfb131556c1b39dfc7f23670386fc6b77
U mario
W 3373
# Plugin meta data
Plugin meta data is a comment scheme for scripting languages. It's meant for
application-level feature and config management. And typically looks like this:
# encoding: utf-8
# api: appname
# title: My Plugin
# description: Lists all the things
# type: feature
# version: 1.0
# state: stable
# category: ui
# license: MITL
# config: { name: myconf, value: 1, type: boolean, description: enable foo }
#
# And here goes a longer doc/comment.
Most `field:` names are fairly standard. Some fields are classifiers or hooks
for the application API. Others are mostly descriptions for end users.
<acronym title="Plugin Meta Data">PMD</acronym> is meant to be rather obvious,
easy to extract, and reusable across languages.
## Common fields
| key | usage |
-----------------------------------------------------------------------------
| [api](wiki/api) | Application identifier |
| [type](wiki/type) | Primary plugin "hook" or general classifier |
| [title](wiki/title) | Title |
| [description](wiki/description) | Summary or description of plugin |
| [category](wiki/category) | UI classification / menu hook |
| [version](wiki/version) | Script-specific version |
| [state](wiki/state) | stable/beta/etc |
| [license](wiki/license) | license identifier |
| [author](wiki/author) | author or contributor list |
| [config](wiki/config) | List of config options (JSOL struct) |
Custom properties are encouraged for further project or tool requirements.
## Comment syntax
The preferred comment scheme is a cohesive `#` hash block - because that's supported
with most scripting languages (and aligns best with an optional shebang).
* Implementations may support multi line `/* … */`, `//`, `<# … #>` comment blocks.
* It's however important that this meta block is the topmost comment in a script.
(See [Rationale](wiki/Rationale))
* All `# key: value` entries occupy consecutive comment lines with coherent formatting.
* Key names should be interpreted case-insensitively. Rfc/message-style,
no spaces allowed.
* Typically they carry just plain strings, because that's easiest to process
for trivial regex lexing.
* Longer field values might be multi-line by indenting wrapped text at least
`␣␣` two spaces beyond other `key:` comment lines.
* The [config](wiki/config) field is one of the few structured entries, and often spans
multiple lines.
* Whereas e.g. [author](wiki/author) or [depends](wiki/depends) are sometimes comma-separated lists.
Though the plugin meta extraction might still just read them as strings;
and leave list handling for later.
Overall it's a bit like YAML; just in a comment block.
Notably an empty line in the comment section separates plugin meta data from
a more detailed description section. Albeit this would often pertain application
end users, more than code implementation details or technical minutae.
Z dbf677a5c6900f81a84bf29a30037820