| Artifact ID: | 66a17b9d5f4583bc9440de83e72089f3083a206efc4f68b6eac91cdbb626f90f |
|---|---|
| Page Name: | Plugin Meta Data |
| Date: | 2018-07-03 20:04:41 |
| Original User: | mario |
| Next | 82d63f8288affc7bbedcaa85c039e6c6b20d921bcbfbbb4a4873db296616972d |
# 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. <acronym title="Plugin Meta Data">PMD</acronym> is meant to be rather obvious, easy to extract, 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/) | 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 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: 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.