| Artifact ID: | 82d63f8288affc7bbedcaa85c039e6c6b20d921bcbfbbb4a4873db296616972d |
|---|---|
| Page Name: | Plugin Meta Data |
| Date: | 2018-07-03 20:05:16 |
| Original User: | mario |
| Mimetype: | text/x-markdown |
| Parent: | 66a17b9d5f4583bc9440de83e72089f3083a206efc4f68b6eac91cdbb626f90f (diff) |
| Next | 14f27ce681c9aa1288585882f2ed2f77759d2ec0daf02e18e8f4a5cdfe848d89 |
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 key: names are fairly standard. Some fields are classifiers or hooks
for the application API. Others are mostly descriptions for end users.
PMD is meant to be rather obvious,
easy to extract, reusable across languages.
Common fields
| key | usage |
|---|---|
| api | Application identifier |
| type | Primary plugin "hook" or general classifier |
| title | Title |
| description | Summary or description of plugin |
| category | UI classification / menu hook |
| version | Script-specific version |
| state | stable/beta/etc |
| license | license identifier |
| author | author or contributor list |
| 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 might support
/* … */or//-blocks or<# … #>and whatever alternative the language offers though.It's however important that this meta block is the topmost comment in a script. (See Rationale)
All
# key: valueentries 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 field is one of the few structured entries, and often spans multiple lines.
Whereas e.g. author or 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.