MetaPOD::JSON - The JSON Formatted MetaPOD Spec
JSON
version 0.3.0
This is mostly a documentation stub, documenting the JSON Formatted version of MetaPOD
The Actual Implementation is stored in ::Format::JSON
::Format::JSON
=begin MetaPOD::JSON { "valid_json_data":"goes_here" } =end
or
=for MetaPOD::JSON { valid_json_data } =cut
You can also declare a version for which semantics to imbue into the declaration.
=begin MetaPOD::JSON v1.0.0
as Per ::Spec, the "v" is required, and the version semantics are always dotted decimal.
::Spec
Note: As Per ::Spec, the version is NOT a minimum version requirement, but a declaration of the versions semantics the containing declaration is encoded in. Given implementations MAY support multiple versions, or they MAY NOT support multiple versions.
It is ENCOURAGED that wherever possible to support the WIDEST variety of versions.
This version of the spec is mostly identical to "SPEC VERSION v1.0.0", and it MUST support all features of that version, with the following additions.
There are many ways for Perl Name spaces to behave, and this property indicates what style of interfaces a given name space supports.
SPEC VERSION v1.1.0 Supports 6 interface types:
class - Indicating the given name space has a constructor of some kind, which returns a bless'ed object.
class
bless
For instance, if your synopsis looks like this:
use Foo; my $instance = Foo->new(); $instance->();
Then you should include class in your "interface" list.
role - Indicating the given namespace is a "role" of some kind, and cannot be instantiated, only composed into other classes.
role
namespace
package Foo; use Moo; with "YourNameSpace";
You should include role in your "interface" list.
exporter - Indicating the given namespace exports things into the caller
exporter
exports
use Foo qw( func ); use Foo; bar(); # Exported by Foo
Then you should include exporter in your "interface" list.
This includes things like Moo and Moose which export functions like has into the calling namespace.
Moo
Moose
has
functions - Indicating a namespace which has functions intended to be called via fully qualified names.
functions
use Foo; Foo::bar();
Then you should include functions in your "interface" list.
single_class - A Hybrid between functions and class, a namespace which has methods, but no constructor, and the namespace itself behaves much like a singleton.
single_class
use Foo; Foo->set_thing( 1 );
Then you should include singleclass in your "interface" list.
singleclass
These usages are also candidates for singleclass "interface"es.
Foo->copy( $a , $b ); # a and/or b is modified, but no object is returned my $result = Foo->bar(); # $result is not an object
However, this is not an example of the single_class interface:
use Foo; my $instance = Foo->writer( $bar ); $instance->method();
Because here, writer doesn't modify the state of Foo, and writer could be seen as simply an alternative constructor.
writer
Foo
type_library - A Type Library of some kind.
type_library
For instance, if your class uses Moose::Util::TypeConstraints to create a named type of some kind, and that type is accessible via
Moose::Util::TypeConstraints
has Foo => ( isa => 'TypeName' );
Then you want to include type_library in your "interface" list.
Note: Some type libraries, notably MooseX::Types perform type creation in addition to exporting, and for such libraries, you should include both type_library and exporter
MooseX::Types
Name spaces that meet above definitions SHOULD document such interfaces as such:
{ "interface": [ "class", "exporter" ]}
interface can be in one of 2 forms.
interface
{ "interface" : $string } { "interface" : [ $string, $string, $string ] }
Both will perform logically appending either the string, or the list of elements, to an internal list which is deduplicated.
So that
{ "interface" : [ $a ]} { "interface" : [ $b ]}
And
{ "interface" : $a } { "interface" : $b }
Have the same effect, the result being the same as if you had specified
{ "interface" : [ $a, $b ] }
Spec version 1.0.0 is such that multiple declarations should be merged to form an aggregate,
e.g.:
=for MetaPOD::JSON v1.0.0 { "a":"b" } =for MetaPOD::JSON v1.0.0 { "c":"d" }
this should be the same as if one had done
=begin MetaPOD::JSON v1.0.0 { "a" : "b" "c" : "d" } =end MetaPOD::JSON
With the observation that latter keys may clobber preceding keys.
Because of the Data Collection design, it is not supported to declare multiple name-spaces within the same file at present.
This is mostly a practical consideration, as without this consideration, all declarations of class members would require re-stating the class, and that would quickly become tiresome.
All MetaPOD::JSON containing documents SHOULD contain at least one namespace declaration.
MetaPOD::JSON
Example:
{ "namespace": "My::Library" }
inherits
Any MetaPOD::JSON containing document that is known to inherit from another class, SHOULD document their inheritance as such:
{ "inherits": [ "Moose::Object" ]}
inherits can be in one of 2 forms.
{ "inherits" : $string } { "inherits" : [ $string, $string, $string ] }
{ "inherits" : [ $a ]} { "inherits" : [ $b ]}
{ "inherits" : $a } { "inherits" : $b }
{ "inherits" : [ $a, $b ] }
does
Any MetaPOD::JSON containing document that is known to "do" another role, SHOULD document their inheritance as such:
{ "does": [ "Some::Role" ]}
does can be in one of 2 forms.
{ "does" : $string } { "does" : [ $string, $string, $string ] }
{ "does" : [ $a ]} { "does" : [ $b ]}
{ "does" : $a } { "does" : $b }
{ "does" : [ $a, $b ] }
Kent Fredric <kentfredric@gmail.com>
This software is copyright (c) 2013 by Kent Fredric <kentfredric@gmail.com>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install MetaPOD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MetaPOD
CPAN shell
perl -MCPAN -e shell install MetaPOD
For more information on module installation, please visit the detailed CPAN module installation guide.