/usr/share/perl5/Rinci/Upgrading.pod is in librinci-perl 1.1.43-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | package Rinci::Upgrading; # just to make PodWeaver happy
# VERSION
1;
# ABSTRACT: Upgrading from previous version of specification
__END__
=pod
=encoding UTF-8
=head1 NAME
Rinci::Upgrading - Upgrading from previous version of specification
=head1 VERSION
version 1.1.43
=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 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/Rinci>.
=head1 SOURCE
Source repository is at L<https://github.com/sharyanto/perl-Rinci>.
=head1 BUGS
Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci>
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
=head1 AUTHOR
Steven Haryanto <stevenharyanto@gmail.com>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2013 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
|