Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CPAN::Changes(3)      User Contributed Perl Documentation     CPAN::Changes(3)

NAME
       CPAN::Changes - Read and	write Changes files

SYNOPSIS
	   # Load from file
	   my $changes = CPAN::Changes->load( 'Changes'	);

	   # Create a new Changes file
	   $changes = CPAN::Changes->new(
	       preamble	=> 'Revision history for perl module Foo::Bar'
	   );

	   $changes->add_release( {
	       version => '0.01',
	       date    => '2009-07-06',
	   } );

	   $changes->serialize;

DESCRIPTION
       It is standard practice to include a Changes file in your distribution.
       The purpose the Changes file is to help a user figure out what has
       changed since the last release.

       People have devised many	ways to	write the Changes file.	A preliminary
       specification has been created (CPAN::Changes::Spec) to encourage
       module authors to write clear and concise Changes.

       This module will	help users programmatically read and write Changes
       files that conform to the specification.

METHODS
   new(	%args )
       Creates a new object using %args	as the initial data.

       "next_token"
	   Used	to passes a regular expression for a "next version"
	   placeholder token.  See "DEALING WITH "NEXT VERSION"	PLACEHOLDERS"
	   for an example of its usage.

   load( $filename, %args )
       Parses $filename	as per CPAN::Changes::Spec.  If	present, the optional
       %args are passed	to the underlaying call	to "new()".

   load_string(	$string, %args )
       Parses $string as per CPAN::Changes::Spec.  If present, the optional
       %args are passed	to the underlaying call	to "new()".

   preamble( [ $preamble ] )
       Gets/sets the preamble section.

   releases( [ @releases ] )
       Without any arguments, a	list of	current	release	objects	is returned
       sorted by ascending release date. When arguments	are specified, all
       existing	releases are removed and replaced with the supplied
       information. Each release may be	either a regular hashref, or a
       CPAN::Changes::Release object.

	   # Hashref argument
	   $changes->releases( { version => '0.01', date => '2009-07-06' } );

	   # Release object argument
	   my $rel = CPAN::Changes::Release->new(
	       version => '0.01', date => '2009-07-06'
	   );
	   $changes->releases( $rel );

   add_release(	@releases )
       Adds the	release	to the changes file. If	a release at the same version
       exists, it will be overwritten with the supplied	data.

   delete_release( @versions )
       Deletes all of the releases specified by	the versions supplied to the
       method.

   release( $version )
       Returns the release object for the specified version. Should there be
       no matching release object, undef is returned.

   serialize( reverse => $boolean, group_sort => \&sorting_function )
       Returns all of the data as a string, suitable for saving	as a Changes
       file.

       If reverse is provided and true,	the releases are printed in the
       reverse order (oldest to	latest).

       If group_sort is	provided, change groups	are sorted according to	the
       given function. If not, groups are sorted alphabetically.

   delete_empty_groups(	)
       Deletes change groups without changes in	all releases.

DEALING	WITH "NEXT VERSION" PLACEHOLDERS
       In the working copy of a	distribution, it's not uncommon	to have	a
       "next release" placeholder section as the first entry of	the "Changes"
       file.

       For example, the	"Changes" file of a distribution using Dist::Zilla and
       Dist::Zilla::Plugin::NextRelease	would look like:

	   Revision history for	Foo-Bar

	   {{$NEXT}}
	       - Add the 'frobuscate' method.

	   1.0.0     2010-11-30
	       - Convert all comments to Esperanto.

	   0.0.1     2010-09-29
	       - Original version unleashed on an unsuspecting world

       To have "CPAN::Changes" recognizes the "{{$NEXT}}" token	as a valid
       version,	you can	use the	"next_token" argument with any of the class'
       constructors. Note that the resulting release object will also be
       considered the latest release, regardless of its	timestamp.

       To continue with	our example:

	   # recognizes	{{$NEXT}} as a version
	   my $changes = CPAN::Changes->load(
	       'Changes',
	       next_token => qr/{{\$NEXT}}/,
	   );

	   my @releases	= $changes->releases;
	   print $releases[-1]->version;       # prints	'{{$NEXT}}'

SEE ALSO
       o   CPAN::Changes::Spec

       o   Test::CPAN::Changes

   SIMILAR MODULES
       o   Module::Metadata::Changes

       o   Module::Changes

AUTHOR
       Brian Cassidy <bricas@cpan.org>

COPYRIGHT AND LICENSE
       Copyright 2011-2013 by Brian Cassidy

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2015-06-21		      CPAN::Changes(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | DEALING WITH "NEXT VERSION" PLACEHOLDERS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CPAN::Changes&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help