Metadata Specification

Metadata Specification

This page provides the specification for the metadata comments embedded within the monolithic barcode.ps resource file.

The BWIPP helper C library and language bindings implement a parser for this specification and provide a stable API for accessing the metadata. You should use the library unless it is preferable to implement your own parser based on this specification.

Overview

The monolithic barcode.ps file contains all BWIPP resources within a delimited template region. Each resource is wrapped in a metadata block consisting of structured PostScript comments that describe its type, dependencies and properties.

File Structure

The monolithic file has the following top-level structure:

%!PS

% Barcode Writer in Pure PostScript - Version YYYY-MM-DD
%
% ...license header...

% --BEGIN TEMPLATE--

...

% --BEGIN RESOURCE preamble--
...
% --END RESOURCE preamble--

...

% --BEGIN ENCODER qrcode--
...
% --END ENCODER qrcode--

...

% --BEGIN RENDERER renmatrix--
...
% --END RENDERER renmatrix--

...

% --END TEMPLATE--

The version string is extracted from the header comment line:

% Barcode Writer in Pure PostScript - Version YYYY-MM-DD

The version is the last whitespace-delimited token on this line.

The template region is delimited by:

% --BEGIN TEMPLATE--
% --END TEMPLATE--

All resource blocks are contained within this region. Content before BEGIN TEMPLATE is the file header (license, version) and is not parsed for resources. Content after END TEMPLATE is ignored.

Resource Blocks

Each resource is wrapped in a BEGIN/END block:

% --BEGIN {TYPE} {NAME}--
...metadata comments...
...PostScript code (wrapped in DSC comments)...
% --END {TYPE} {NAME}--

TYPE is one of:

Type	Description
ENCODER	A barcode symbology encoder
RENDERER	A rendering engine (renlinear, renmatrix, renmaximatrix)
RESOURCE	A utility resource (e.g. preamble, raiseerror, parseinput)

NAME is the resource identifier (alphanumeric characters and hyphens).

The BEGIN and END lines must have matching TYPE and NAME values. Resource blocks must not be nested.

Metadata Comments

Between the BEGIN line and the PostScript code, resource blocks may contain metadata comments. These take two forms:

Dependencies

% --REQUIRES {dep1} {dep2} ...--

A space-separated list of resource names that this resource depends on in the order that they are to be included in a standalone PostScript file. Dependencies are not transitive: the list must include the recursive dependencies of all required resources.

The REQUIRES line is optional. If present, it must appear before any property comments.

Properties

% --KEY: VALUE

Properties are key-value pairs where the key is an uppercase alphabetic string followed by a colon, and the value is the remainder of the line (with leading space trimmed). The value may be empty.

The following properties are defined:

Key	Applies to	Description
DESC	ENCODER	Human-readable description of the symbology (e.g. QR Code, Code 128)
EXAM	ENCODER	Example barcode input data. May be empty
EXOP	ENCODER	Example encoder options as space-separated key=value pairs. May be empty
RNDR	ENCODER	Renderer used by this encoder: renlinear, renmatrix or renmaximatrix
FMLY	ENCODER	Family grouping for the encoder (e.g. One-dimensional symbols, Two-dimensional symbols)

RENDERER and RESOURCE type blocks do not carry DESC, EXAM, EXOP, RNDR or FMLY properties.

Some ENCODER resources intentionally omit FMLY. These are internal or utility encoders (e.g. gs1-cc, raw, daft) that are not intended to appear in family-grouped listings.

Complete Example

An encoder resource block in the monolithic file:

% --BEGIN ENCODER qrcode--
% --REQUIRES preamble raiseerror setuphooks processoptions parseinput setanycolor fifocache rendertext renmatrix--
% --DESC: QR Code
% --EXAM: http://goo.gl/0bis
% --EXOP: eclevel=M
% --RNDR: renmatrix
% --FMLY: Two-dimensional symbols
%%BeginResource: uk.co.terryburton.bwipp qrcode 0.0 ...
%%BeginData:        ... ASCII Lines
...PostScript code...
%%EndData
%%EndResource
% --END ENCODER qrcode--

A utility resource block:

% --BEGIN RESOURCE raiseerror--
% --REQUIRES preamble--
%%BeginResource: uk.co.terryburton.bwipp raiseerror 0.0 ...
%%BeginData:        ... ASCII Lines
...PostScript code...
%%EndData
%%EndResource
% --END RESOURCE raiseerror--

A renderer resource block:

% --BEGIN RENDERER renlinear--
% --REQUIRES preamble raiseerror setuphooks processoptions setanycolor rendertext--
%%BeginResource: uk.co.terryburton.bwipp renlinear 0.0 ...
%%BeginData:        ... ASCII Lines
...PostScript code...
%%EndData
%%EndResource
% --END RENDERER renlinear--

DSC Comments

Within each resource block, the PostScript code is wrapped in Document Structuring Conventions (DSC) comments. These are not part of the metadata specification but are present in the file:

%%BeginResource: {category} {name} {version} {revision} {VMusage} ...
%%BeginData:        {count} ASCII Lines
...PostScript code...
%%EndData
%%EndResource

The DSC comments are generated by the build system and should be ignored by metadata parsers. The PostScript code between %%BeginData and %%EndData is the resource body.

Parsing Notes

• Metadata comment lines always begin with % --.
• Property keys are distinguished from structural markers (BEGIN, END, REQUIRES) by the presence of a : character and by the key not ending with --.
• Any % --KEY: VALUE comment matching the above criteria is a valid property, even if the key is not one of the defined properties listed above. Unknown properties should be accepted and ignored.
• Resource ordering within the template region follows dependency order: a resource appears after all of its dependencies.