—our
$VERSION
=
'1.1.20'
;
# VERSION
1;
# ABSTRACT: Upgrading from previous version of specification
__END__
=pod
=head1 NAME
Rinci::Upgrading - Upgrading from previous version of specification
=head1 VERSION
version 1.1.20
=head1 DESCRIPTION
This document gives guide on how to convert your metadata from older version.
Examples are written in Perl, but are not limited to this language.
=head1 UPGRADING FROM SUB::SPEC 1.0 TO RINCI 1.1
=head2 Upgrading function metadata
In Perl, you can use L<Perinci::Sub::Wrapper> (which in turn is used by
L<Perinci::Access>) to automatically convert Sub::Spec 1.0 metadata to 1.1, so
you can skip this document if you want.
Terminology change: B<(sub) spec> is now called metadata: the reason is because
there are now metadata for functions as well as other code entities like
variables, packages, etc. B<clause> is now called B<property>: the reason is to
avoid confusion with L<Data::Sah>'s clause.
The C<v> (spec version) property is required, add
v => 1.1
to your function metadata.
Each argument in the C<args> property is now a hash, instead of a schema. Move
the schema to the C<schema> key of the hash. To specify required argument, add
C<req> set to 1 to hash key. Move C<arg_pos> Sah clause to C<pos> hash key. Move
C<arg_greedy> Sah clause to C<greedy> hash key. Move C<arg_completion> Sah
clause to C<completion> hash key.
Example, change this:
args => {
# a required argument
arg1 => ['int*', {
summary => 'Blah ...',
min => 1, max => 100,
arg_pos => 0,
}],
# an optional argument
arg2 => ['bool', {
summary => 'Blah ...',
default => 0,
}],
}
Into this:
args => {
arg1 => {
summary => 'Blah ...',
schema => ['int*', {min=>1, max=>100}],
req => 1,
pos => 0,
},
arg2 => {
summary => 'Blah ...',
schema => [bool => {default=>0}],
},
}
It is now possible to give summary and description to the schema as well as to
the argument.
Accordingly, the C<result> property is also now a hash, instead of schema. Move
the schema into the C<schema> hash key.
=head2 Sub::Spec::HTTP
For the most part, you only need to upgrade client and server library. Client
library is now L<Perinci::CmdLine> and L<Perinci::Access>. Server library is now
C<Perinci::Access::HTTP::Server>.
Specification is now L<Riap> and L<Riap::HTTP>. Terminology changes. B<SS
request> now becomes B<Riap request>. Some key names changed (shortened).
Special headers are now prefixed with B<X-Riap-*> instead of B<X-SS-Req-*>.
Log levels are now numeric only (1-6) instead of numeric/string.
=head1 AUTHOR
Steven Haryanto <stevenharyanto@gmail.com>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut