# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - # # file: lib/Software/License/OrLaterPack.pm # # Copyright © 2015 Van de Bugger # # This file is part of perl-Software-License-OrLaterPack. # # perl-Software-License-OrLaterPack is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by the Free Software Foundation, # either version 3 of the License, or (at your option) any later version. # # perl-Software-License-OrLaterPack is distributed in the hope that it will be useful, but # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. See the GNU General Public License for more details. # # You should have received a copy of the GNU General Public License along with # perl-Software-License-OrLaterPack. If not, see <http://www.gnu.org/licenses/>. # # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - # This is dummy main module of `OrLaterPack`, because CPAN does not handle well distributions # without a main module. Also, it documents the distribution as a whole. package Software::License::OrLaterPack; use strict; # Let Kwalitee be happy. use warnings; # Ditto. use version 0.77; # ABSTRACT: Use GNU license with "or later" clause our $VERSION = 'v0.10.0'; # VERSION 1; #pod =pod #pod #pod =encoding UTF-8 #pod #pod =for :this This is C<OrLaterPack> user manual. Read this if you want to use GNU license with "or later" clause. #pod #pod =for :those If you are going to hack or extend C<OrLaterPack> read module documentation, e. g. #pod L<Software::License::GPL_3::or_later>. General topics like getting source, building, installing, #pod bug reporting and some others are covered in the F<README> file. #pod #pod =for comment --------------------------------------------------------------------------------------- #pod #pod =head1 SYNOPSIS #pod #pod In C<dist.ini>: #pod #pod name = Foo-Bar #pod version = 0.001 #pod author = John Doe <john.doe@example.com> #pod license = GPL_3::or_later #pod ; or another license, see the list of provided licenses #pod copyright_holder = John Doe #pod copyright_year = 2015 #pod … #pod #pod Direct usage: #pod #pod use Software::License::GPL_3::or_later; #pod # or another license, see the list of provided licenses #pod my $lic = Software::License::GPL_3::or_later->new( { #pod holder => 'John Doe', #pod year => '2010', #pod program => 'Assa', #pod } ); #pod $lic->abbr; # returns 'GPLv3+' #pod $lic->notice; # Copyright statement and 3-paragraph GNU license notice #pod … #pod #pod =for comment --------------------------------------------------------------------------------------- #pod #pod =head1 DESCRIPTION #pod #pod All "or later" are just subclasses of corresponding base license classes. For example, #pod C<Software::License::GPL_3::or_later> is a subclass of C<Software::License::GPL_3>, so any "or #pod later" license can be used like any other license. For example, in your F<dist.ini> file: #pod #pod license = GPL_3::or_later #pod #pod However, licenses in the pack introduce few features not found in base classes. #pod #pod =head2 Program Name #pod #pod C<Software::License> constructor accepts hashref as the only argument: #pod #pod $lic = Software::License::GPL_3::or_later->new( { #pod holder => 'John Doe', #pod year => '2010', #pod } ); #pod #pod C<Software::License> documents two keys C<holder> and C<year> shown in example. However, #pod C<Software::License> constructor just (re)blesses passed hashref to the package, keeping all the #pod hash keys and values intact, so you can pass more arguments to the constructor. #pod #pod C<OrLaterPack> licenses use two more keys C<program> and C<Program>: #pod #pod $lic = Software::License::GPL_3::or_later->new( { #pod holder => 'John Doe', #pod year => '2010', #pod program => 'assa', #pod Program => 'Assa', #pod } ); #pod #pod These values are used as program name instead of generic "this program" in license notice, for #pod example: #pod #pod Assa is free software: you can redistribute it and/or modify it… #pod #pod C<program> key is used in the middle of sentence, C<Program> is used if program name starts a #pod sentence. You may specify either one or both keys. If only one key specified, it is used in all the #pod occurrences regardless of its position within a sentence. #pod #pod Note: At time of writing, these keys are used only by licenses from C<OrLaterPack>. You can safely #pod pass them to constructor of any license, it does not hurt but keys will not be used. #pod #pod When using C<Dist::Zilla> you just specify few options, and C<Dist::Zilla> does all the work on #pod behalf of you: #pod #pod name = Assa #pod license = GPL_3::or_later #pod copyright_holder = John Doe #pod copyright_year = 2010 #pod #pod Program name is specified, but C<Dist::Zilla> does not pass it to license object constructor. Patch #pod for C<Dist::Zilla> submitted but not yet applied. Meanwhile, you can hack it with little help from #pod C<Hook> plugin: #pod #pod name = Assa #pod license = GPL_3::or_later #pod copyright_holder = John Doe #pod copyright_year = 2010 #pod [Hook::Init] #pod . = $dist->license->{ program } = $dist->name; #pod ; Voilà : license has `program` key now. #pod ... #pod #pod For accessing these keys, C<OrLaterPack> introduced two methods: C<program> and C<Program>. They #pod are convenient because you should not worry if the key was specified or not: a method returns best #pod available variant of program name. For example, if C<program> key was not passed to the #pod constructor, C<< $self->{ program } >> will return C<undef>, while C<< $self->program >> will #pod return value of C<Program> key, if it was specified, or "this program" as the last resort. However, #pod these methods are not defined in base class and can be invoked only on a license from #pod C<OrLaterPack>. #pod #pod =head2 Short License Notice #pod #pod Standard GNU license notice consists of 3 paragraphs (more than 100 words and 600 characters). It #pod is ok for the program documentation, but it far too long to be printed in the beginning of #pod interactive session. For latter purpose FSF recommends to use short notice like this one: #pod #pod Copyright (C) 2010 John Doe #pod License GPLv3+: GNU General Public License version 3 or later. #pod This is free software: you are free to change and redistribute it. #pod There is NO WARRANTY, to the extent permitted by law. #pod #pod To get short license notice, pass C<'short'> argument to the C<notice> method: #pod #pod $lic->notice( 'short' ); #pod #pod At time of writing, C<'short'> argument is respected only by licenses in C<orLaterPack>. Other #pod licenses ignore the arguments and return ordinary license note. #pod #pod Note: This feature is considered experimental now. #pod #pod =for comment --------------------------------------------------------------------------------------- #pod #pod =head1 LIST OF PROVIDED LICENSES #pod #pod =for :list #pod = L<Software::License::AGPL_3::or_later> #pod = L<Software::License::GPL_1::or_later> #pod = L<Software::License::GPL_2::or_later> #pod = L<Software::License::GPL_3::or_later> #pod = L<Software::License::LGPL_2_1::or_later> #pod = L<Software::License::LGPL_3_0::or_later> #pod #pod #pod =head1 CAVEATS #pod #pod L<CPAN::Meta::Spec> hardcodes the list of "valid" licenses. In version 2.150001 of the module there #pod are no "upgradable" GNU licenses, so in CPAN the GPLv3+ will look as ordinal GPLv3 (C<gpl_3>), and #pod so on. #pod #pod =for comment --------------------------------------------------------------------------------------- #pod #pod =head1 SEE ALSO #pod #pod =for :list #pod = L<Dist::Zilla> #pod = L<Dist::Zilla::Plugin::Hook> #pod = L<Software::License> #pod = L<Why should programs say “Version 3 of the GPL or any later version�|https://www.gnu.org/licenses/gpl-faq.html#VersionThreeOrLater> #pod #pod =for comment --------------------------------------------------------------------------------------- #pod #pod =head1 COPYRIGHT AND LICENSE #pod #pod Copyright (C) 2015 Van de Bugger #pod #pod perl-Software-License-OrLaterPack is free software: you can redistribute it #pod and/or modify it under the terms of the GNU General Public License as #pod published by the Free Software Foundation, either version 3 of the License, #pod or (at your option) any later version. #pod #pod perl-Software-License-OrLaterPack is distributed in the hope that it will #pod be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of #pod MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General #pod Public License for more details. #pod #pod You should have received a copy of the GNU General Public License along #pod with perl-Software-License-OrLaterPack. If not, see #pod <http://www.gnu.org/licenses/>. #pod #pod #pod =cut # doc/what.pod # #pod =encoding UTF-8 #pod #pod =head1 WHAT? #pod #pod C<Software-License-OrLaterPack> (or just C<OrLaterPack> for brevity) is an add-on for C<Software-License>, a set #pod of licenses with "or later" clause (like C<GPL_3::or_later>). It allows Perl developers (who use #pod C<Dist-Zilla>) to release their work under the terms of a I<License> version I<N> or (at user #pod option) any later version. #pod #pod =cut # end of file # # doc/why.pod # #pod =encoding UTF-8 #pod #pod =head1 WHY? #pod #pod C<Dist-Zilla> is a popular tool for building CPAN distributions. Build process is controlled by #pod F<dist.ini>, C<Dist-Zilla> configuration file. A distribution author can specify license covering #pod his work by using C<license> option in F<dist.ini> file: #pod #pod license = NAME #pod #pod where I<NAME> is a name of module from L<Software::License> hierarchy. #pod #pod C<Software-License> is shipped with a set of popular licenses, from C<Apache_1_1> to C<Zlib>, #pod including GNU licenses (GPL), including their "Affero" and "Lesser" variants. #pod #pod So, if a developer wants to release his work under the terms of the GPL version 3, he should write #pod in his F<dist.ini>: #pod #pod license = GPL_3 #pod #pod However, L<Free Software Foundation recommends using clause "license version I<N> or (at your #pod option) any later version"|>. Unfortunately, C<Software-License> #pod distribution does not supply (out of the box) a way to express such clause. #pod #pod C<OrLaterPack> fulfills the lack. If C<OrLaterPack> is installed, a developer can specify in his #pod F<dist.ini>: #pod #pod license = GPL_3::or_later #pod #pod =cut # end of file # # end of file # __END__ =pod =encoding UTF-8 =head1 NAME Software::License::OrLaterPack - Use GNU license with "or later" clause =head1 VERSION Version v0.10.0, released on 2015-10-03 09:01 UTC. =head1 WHAT? C<Software-License-OrLaterPack> (or just C<OrLaterPack> for brevity) is an add-on for C<Software-License>, a set of licenses with "or later" clause (like C<GPL_3::or_later>). It allows Perl developers (who use C<Dist-Zilla>) to release their work under the terms of a I<License> version I<N> or (at user option) any later version. This is C<OrLaterPack> user manual. Read this if you want to use GNU license with "or later" clause. If you are going to hack or extend C<OrLaterPack> read module documentation, e. g. L<Software::License::GPL_3::or_later>. General topics like getting source, building, installing, bug reporting and some others are covered in the F<README> file. =head1 SYNOPSIS In C<dist.ini>: name = Foo-Bar version = 0.001 author = John Doe <john.doe@example.com> license = GPL_3::or_later ; or another license, see the list of provided licenses copyright_holder = John Doe copyright_year = 2015 … Direct usage: use Software::License::GPL_3::or_later; # or another license, see the list of provided licenses my $lic = Software::License::GPL_3::or_later->new( { holder => 'John Doe', year => '2010', program => 'Assa', } ); $lic->abbr; # returns 'GPLv3+' $lic->notice; # Copyright statement and 3-paragraph GNU license notice … =head1 DESCRIPTION All "or later" are just subclasses of corresponding base license classes. For example, C<Software::License::GPL_3::or_later> is a subclass of C<Software::License::GPL_3>, so any "or later" license can be used like any other license. For example, in your F<dist.ini> file: license = GPL_3::or_later However, licenses in the pack introduce few features not found in base classes. =head2 Program Name C<Software::License> constructor accepts hashref as the only argument: $lic = Software::License::GPL_3::or_later->new( { holder => 'John Doe', year => '2010', } ); C<Software::License> documents two keys C<holder> and C<year> shown in example. However, C<Software::License> constructor just (re)blesses passed hashref to the package, keeping all the hash keys and values intact, so you can pass more arguments to the constructor. C<OrLaterPack> licenses use two more keys C<program> and C<Program>: $lic = Software::License::GPL_3::or_later->new( { holder => 'John Doe', year => '2010', program => 'assa', Program => 'Assa', } ); These values are used as program name instead of generic "this program" in license notice, for example: Assa is free software: you can redistribute it and/or modify it… C<program> key is used in the middle of sentence, C<Program> is used if program name starts a sentence. You may specify either one or both keys. If only one key specified, it is used in all the occurrences regardless of its position within a sentence. Note: At time of writing, these keys are used only by licenses from C<OrLaterPack>. You can safely pass them to constructor of any license, it does not hurt but keys will not be used. When using C<Dist::Zilla> you just specify few options, and C<Dist::Zilla> does all the work on behalf of you: name = Assa license = GPL_3::or_later copyright_holder = John Doe copyright_year = 2010 Program name is specified, but C<Dist::Zilla> does not pass it to license object constructor. Patch for C<Dist::Zilla> submitted but not yet applied. Meanwhile, you can hack it with little help from C<Hook> plugin: name = Assa license = GPL_3::or_later copyright_holder = John Doe copyright_year = 2010 [Hook::Init] . = $dist->license->{ program } = $dist->name; ; Voilà : license has `program` key now. ... For accessing these keys, C<OrLaterPack> introduced two methods: C<program> and C<Program>. They are convenient because you should not worry if the key was specified or not: a method returns best available variant of program name. For example, if C<program> key was not passed to the constructor, C<< $self->{ program } >> will return C<undef>, while C<< $self->program >> will return value of C<Program> key, if it was specified, or "this program" as the last resort. However, these methods are not defined in base class and can be invoked only on a license from C<OrLaterPack>. =head2 Short License Notice Standard GNU license notice consists of 3 paragraphs (more than 100 words and 600 characters). It is ok for the program documentation, but it far too long to be printed in the beginning of interactive session. For latter purpose FSF recommends to use short notice like this one: Copyright (C) 2010 John Doe License GPLv3+: GNU General Public License version 3 or later. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. To get short license notice, pass C<'short'> argument to the C<notice> method: $lic->notice( 'short' ); At time of writing, C<'short'> argument is respected only by licenses in C<orLaterPack>. Other licenses ignore the arguments and return ordinary license note. Note: This feature is considered experimental now. =head1 WHY? C<Dist-Zilla> is a popular tool for building CPAN distributions. Build process is controlled by F<dist.ini>, C<Dist-Zilla> configuration file. A distribution author can specify license covering his work by using C<license> option in F<dist.ini> file: license = NAME where I<NAME> is a name of module from L<Software::License> hierarchy. C<Software-License> is shipped with a set of popular licenses, from C<Apache_1_1> to C<Zlib>, including GNU licenses (GPL), including their "Affero" and "Lesser" variants. So, if a developer wants to release his work under the terms of the GPL version 3, he should write in his F<dist.ini>: license = GPL_3 However, L<Free Software Foundation recommends using clause "license version I<N> or (at your option) any later version"|>. Unfortunately, C<Software-License> distribution does not supply (out of the box) a way to express such clause. C<OrLaterPack> fulfills the lack. If C<OrLaterPack> is installed, a developer can specify in his F<dist.ini>: license = GPL_3::or_later =for comment --------------------------------------------------------------------------------------- =for comment --------------------------------------------------------------------------------------- =for comment --------------------------------------------------------------------------------------- =head1 LIST OF PROVIDED LICENSES =over 4 =item L<Software::License::AGPL_3::or_later> =item L<Software::License::GPL_1::or_later> =item L<Software::License::GPL_2::or_later> =item L<Software::License::GPL_3::or_later> =item L<Software::License::LGPL_2_1::or_later> =item L<Software::License::LGPL_3_0::or_later> =back =head1 CAVEATS L<CPAN::Meta::Spec> hardcodes the list of "valid" licenses. In version 2.150001 of the module there are no "upgradable" GNU licenses, so in CPAN the GPLv3+ will look as ordinal GPLv3 (C<gpl_3>), and so on. =for comment --------------------------------------------------------------------------------------- =for comment --------------------------------------------------------------------------------------- =head1 SEE ALSO =over 4 =item L<Dist::Zilla> =item L<Dist::Zilla::Plugin::Hook> =item L<Software::License> =item L<Why should programs say “Version 3 of the GPL or any later version�|https://www.gnu.org/licenses/gpl-faq.html#VersionThreeOrLater> =back =head1 AUTHOR Van de Bugger <van.de.bugger@gmail.com> =head1 COPYRIGHT AND LICENSE Copyright (C) 2015 Van de Bugger perl-Software-License-OrLaterPack is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. perl-Software-License-OrLaterPack is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with perl-Software-License-OrLaterPack. If not, see <http://www.gnu.org/licenses/>. =cut