Debian Codegraph @

lib/Rinci/Upgrading.pod

raw
1 package Rinci::Upgrading; # just to make PodWeaver happy
2
3 # AUTHORITY
4 # DATE
5 our $DIST = 'Rinci'; # DIST
6 # VERSION
7
8 1;
9 # ABSTRACT: Upgrading from previous version of specification
10
11 __END__
12
13 =pod
14
15 =encoding UTF-8
16
17 =head1 NAME
18
19 Rinci::Upgrading - Upgrading from previous version of specification
20
21 =head1 VERSION
22
23 This document describes version 1.1.104 of Rinci::Upgrading (from Perl distribution Rinci), released on 2023-09-30.
24
25 =head1 DESCRIPTION
26
27 This document gives guide on how to convert your metadata from older version.
28
29 Examples are written in Perl, but are not limited to this language.
30
31 =head1 UPGRADING FROM SUB::SPEC 1.0 TO RINCI 1.1
32
33 =head2 Upgrading function metadata
34
35 In Perl, you can use L<Perinci::Sub::Wrapper> (which in turn is used by
36 L<Perinci::Access>) to automatically convert Sub::Spec 1.0 metadata to 1.1, so
37 you can skip this document if you want.
38
39 Terminology change: B<(sub) spec> is now called metadata: the reason is because
40 there are now metadata for functions as well as other code entities like
41 variables, packages, etc. B<clause> is now called B<property>: the reason is to
42 avoid confusion with L<Data::Sah>'s clause.
43
44 The C<v> (spec version) property is required, add
45
46 v => 1.1
47
48 to your function metadata.
49
50 Each argument in the C<args> property is now a hash, instead of a schema. Move
51 the schema to the C<schema> key of the hash. To specify required argument, add
52 C<req> set to 1 to hash key. Move C<arg_pos> Sah clause to C<pos> hash key. Move
53 C<arg_greedy> Sah clause to C<greedy> hash key. Move C<arg_completion> Sah
54 clause to C<completion> hash key.
55
56 Example, change this:
57
58 args => {
59 # a required argument
60 arg1 => ['int*', {
61 summary => 'Blah ...',
62 min => 1, max => 100,
63 arg_pos => 0,
64 }],
65
66 # an optional argument
67 arg2 => ['bool', {
68 summary => 'Blah ...',
69 default => 0,
70 }],
71 }
72
73 Into this:
74
75 args => {
76 arg1 => {
77 summary => 'Blah ...',
78 schema => ['int*', {min=>1, max=>100}],
79 req => 1,
80 pos => 0,
81 },
82
83 arg2 => {
84 summary => 'Blah ...',
85 schema => [bool => {default=>0}],
86 },
87 }
88
89 It is now possible to give summary and description to the schema as well as to
90 the argument.
91
92 Accordingly, the C<result> property is also now a hash, instead of schema. Move
93 the schema into the C<schema> hash key.
94
95 =head2 Sub::Spec::HTTP
96
97 For the most part, you only need to upgrade client and server library. Client
98 library is now L<Perinci::CmdLine> and L<Perinci::Access>. Server library is now
99 C<Perinci::Access::HTTP::Server>.
100
101 Specification is now L<Riap> and L<Riap::HTTP>. Terminology changes. B<SS
102 request> now becomes B<Riap request>. Some key names changed (shortened).
103 Special headers are now prefixed with B<X-Riap-*> instead of B<X-SS-Req-*>.
104
105 Log levels are now numeric only (1-6) instead of numeric/string.
106
107 =head1 HOMEPAGE
108
109 Please visit the project's homepage at L<https://metacpan.org/release/Rinci>.
110
111 =head1 SOURCE
112
113 Source repository is at L<https://github.com/perlancar/perl-Rinci>.
114
115 =head1 AUTHOR
116
117 perlancar <[email protected]>
118
119 =head1 CONTRIBUTING
120
121
122 To contribute, you can send patches by email/via RT, or send pull requests on
123 GitHub.
124
125 Most of the time, you don't need to build the distribution yourself. You can
126 simply modify the code, then test via:
127
128 % prove -l
129
130 If you want to build the distribution (e.g. to try to install it locally on your
131 system), you can install L<Dist::Zilla>,
132 L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
133 L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other
134 Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond
135 that are considered a bug and can be reported to me.
136
137 =head1 COPYRIGHT AND LICENSE
138
139 This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012 by perlancar <[email protected]>.
140
141 This is free software; you can redistribute it and/or modify it under
142 the same terms as the Perl 5 programming language system itself.
143
144 =head1 BUGS
145
146 Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci>
147
148 When submitting a bug or request, please include a test-file or a
149 patch to an existing test-file that illustrates the bug or desired
150 feature.
151
152 =cut