https://github.com/kentnl/metapod-spec

The Specification of the MetaPOD format
https://github.com/kentnl/metapod-spec

Last synced: 4 days ago
JSON representation

The Specification of the MetaPOD format

• Host: GitHub
• URL: https://github.com/kentnl/metapod-spec
• Owner: kentnl
• License: other
• Created: 2013-11-24T03:47:30.000Z (almost 11 years ago)
• Default Branch: master
• Last Pushed: 2017-03-11T11:34:50.000Z (over 7 years ago)
• Last Synced: 2023-08-20T22:33:48.772Z (about 1 year ago)
• Language: Perl
• Size: 803 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.mkdn
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

        
# NAME

MetaPOD::Spec - The Specification of the MetaPOD format

# VERSION

version v0.5.1

# Specifying MetaPOD

## FORMATS

A FORMAT is a MetaPOD Subclass.

Segments will be parsed looking for

    MetaPOD::([^\s]+)

Where `$1` is the name of the MetaPOD `FORMAT`

e.g:

    =begin MetaPOD::JSON

    { JSON DATA }

    =end MetaPOD::JSON

These may, or may not, correspond to real world parser names, but the actual code loaded may be determined by the parser, and

this declaration is more an indication of a _specification_

And it may be that a `MetaPOD::JSON` declaration loads MetaPOD::Format::JSON

## VERSIONS

A VERSION as part of a Segment declaration **must** come after the format declaration, preceded only by white-space.

A VERSION declaration **must** start with a `v`

ALL VERSIONS will be assumed to be dotted-decimal, and parsed with the 'v' included.

These versions however do not necessarily have to map to a `CPAN` Version, and is instead supposed to be an indication of the

_specification_ version, a specification that may be provided by multiple `CPAN` packages/versions.

What this means to the _specification_ is at the whim of the format, and it is the formats job to respond to a version

declaration.

`FORMATS` may either

- reject a version as being "too new" and thus not supported by a back end

- change behaviour based on the value of this version

- reject a version as being "too old" to be supported by the back end

## Segment Declaration

A MetaPOD specification can be added to a POD document via one of the following forms

### Block Segments

    =begin MetaPOD::FORMAT

    FORMATDATA

    =end MetaPOD::FORMAT

And

    =begin MetaPOD::FORMAT VERSION

    FORMATDATA

    =end MetaPOD::FORMAT

### One Line Segments

    =for MetaPOD::FORMAT FORMATDATA

and

    =for MetaPOD::FORMAT VERSION FORMATDATA

## Multiple Segment Declaration

It is the design of this Spec to recommend that segment declarations **Should** be permissible to be declared multiple times, and

it **should** use this information to gather data progressively, merging data as it goes.

# AUTHOR

Kent Fredric 

# COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric .

This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.