package Rinci::Upgrading; # just to make PodWeaver happy our $VERSION = '1.1.28'; # 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.28 =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