Overview

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
Content

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: 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 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.