1Module::Metadata::ChangUesse(r3)Contributed Perl DocumenMtoadtuiloen::Metadata::Changes(3)
2
6 Module::Metadata::Changes - Manage machine-readable
7 Changes/CHANGES/Changelog.ini files
8
10 One-liners
11 These examples use Changes/CHANGES and Changelog.ini in the 'current'
12 directory.
13 The command line options (except for -h) correspond to the options
15 documented under "Constructor and initialization", below.
16 shell>ini.report.pl -h
18 shell>ini.report.pl -c
19 shell>ini.report.pl -r 1.23
20 shell>sudo ini.report.pl -w > /var/www/Changelog.html
21 shell>perl -MModule::Metadata::Changes -e 'Module::Metadata::Changes->new(convert => 1)->run'
22 shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new->read->get_latest_version'
23 shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new->read->report'
24 shell>perl -MModule::Metadata::Changes -e 'print Module::Metadata::Changes->new(release=>"2.00")->read->report'
25 Module::Metadata::Changes ships with "ini.report.pl" in the bin/
27 directory. It is installed along with the module.
28 Also, Module::Metadata::Changes uses Config::IniFiles to read and write
30 Changelog.ini files.
31 Reporters
33 With a script like this:
34 #!/usr/bin/env perl
36 use feature 'say';
38 use strict;
39 use warnings;
40 use File::chdir; # For magic $CWD.
42 use Module::Metadata::Changes;
44 # ------------------------------------------------
46 my($work) = "$ENV{HOME}/perl.modules";
48 my($m) = Module::Metadata::Changes -> new;
49 opendir(INX, $work) || die "Can't opendir($work)";
51 my(@name) = sort grep{! /^\.\.?$/} readdir INX;
52 closedir INX;
53 my($config);
55 my($version);
56 for my $name (@name)
58 {
59 $CWD = "$work/$name"; # Does a chdir.
60 $version = $m -> read -> get_latest_version;
61 $config = $m -> config; # Must call read() before config().
62 say $config -> val('Module', 'Name'), " V $version ", $config -> val("V $version", 'Date');
64 }
65 you can get a report of the latest version number, from Changelog.ini,
67 for each module in your vast library.
68
70 Module::Metadata::Changes is a pure Perl module.
71 It allows you to convert old-style Changes/CHANGES files, and to read
73 and write Changelog.ini files.
74 =head1 Distributions
76 This module is available as a Unix-style distro (*.tgz).
78 See http://savage.net.au/Perl-modules.html for details.
80 See http://savage.net.au/Perl-modules/html/installing-a-module.html for
82 help on unpacking and installing.
83
85 new(...) returns an object of type Module::Metadata::Changes.
86 This is the class contructor.
88 Usage: "Module::Metadata::Changes -> new()".
90 This method takes a hash of options. There are no mandatory options.
92 Call "new()" as "new(option_1 => value_1, option_2 => value_2, ...)".
94 Available options:
96 o convert
98 This takes the value 0 or 1.
99 The default is 0.
101 If the value is 0, calling "run()" calls "read()" and "report()".
103 If the value is 1, calling "run()" calls "writer(reader() )".
105 o inFileName
107 The default is 'Changes' (or, if absent, 'CHANGES') when calling
108 "reader()", and 'Changelog.ini' when calling "read()".
109 o outFileName
111 The default is 'Changelog.ini'.
112 o pathForHTML
114 This is path to the HTML::Template-style templates used by the
115 'table' and 'webPage' options.
116 The default is
118 '/usr/share/perl-Module-Metadata-Changes/templates/module/metadata/changes'.
119 o release
121 The default is ''.
122 If this option has a non-empty value, the value is assumed to be a
124 release/version number.
125 In that case, reports (text, HTML) are restricted to only the given
127 version.
128 The default ('') means reports contain all versions.
130 'release' was chosen, rather than 'version', in order to avoid a
132 clash with 'verbose', since all options could then be abbreviated
133 to 1 letter (when running ini.report.pl).
134 Also, a lot of other software uses -r to refer to release/version.
136 o table
138 This takes the value 0 or 1.
139 The default is 0.
141 This option is only used when "report()" is called.
143 If the value is 0, calling "report()" outputs a text report.
145 If the value is 1, calling "report()" outputs a HTML report.
147 By default, the HTML report will just be a HTML table.
149 However, if the 'webPage' option is 1, the HTML will be a complete
151 web page.
152 o urlForCSS
154 The default is '/.sysassets/css/module/metadata/changes/ini.css'.
155 This is only used if the 'webPage' option is 1.
157 o verbose
159 This takes the value 0 or 1.
160 The default is 0.
162 If the value is 1, write progress reports to STDERR.
164 o webPage
166 This takes the value 0 or 1.
167 The default is 0.
169 A value of 1 automatically sets 'table' to 1.
171 If the value is 0, the 'table' option outputs just a HTML table.
173 If the value is 1, the 'table' option outputs a complete web page.
175
177 o config()
178 Returns the Config::IniFiles object, from which you can extract all the
179 data.
180 This method must be called after calling "read()".
182 See "scripts/report.names.pl" for sample code.
184 The names of the sections, [Module] and [V 1.23], and the keys under
186 each, are documented in the FAQ.
187 o errstr()
189 Returns the last error message, or ''.
190 o get_latest_release()
192 Returns an hash ref of details for the latest release.
193 Returns {} if there is no such release.
195 The hash keys are (most of) the reserved tokens, as discussed below in
197 the FAQ.
198 Some reserved tokens, such as EOT, make no sense as hash keys.
200 o get_latest_version()
202 Returns the version number of the latest version.
203 Returns '' if there is no such version.
205 o parse_datetime()
207 Used by "transform()".
208 o parse_datetime_1()
210 Used by "transform()".
211 o parse_datetime_2()
213 Used by "transform()".
214 o read([$input_file_name])
216 This method reads the given file, using Config::IniFiles.
217 The $input_file_name is optional. It defaults to 'Changelog.ini'.
219 See config().
221 Return value: The object, for method chaining.
223 o reader([$input_file_name])
225 This method parses the given file, assuming it is format is the common-
226 or-garden Changes/CHANGES style.
227 The $input_file_name is optional. It defaults to 'Changes' (or, if
229 absent, 'CHANGES').
230 "reader()" calls "module_name()" to save the module name for use by
232 other methods.
233 "reader()" calls "transform()".
235 Return value: An arrayref of hashrefs, i.e. the return value of
237 "transform()".
238 This value is suitable for passing to "writer()".
240 o report()
242 Displays various items for one or all releases.
243 If the 'release' option to "new()" was not used, displays items for all
245 releases.
246 If 'release' was used, restrict the report to just that
248 release/version.
249 If either the 'table' or 'webPage' options to "new()" were used, output
251 HTML by calling "report_as_html()".
252 If these latter 2 options were not used, output text.
254 HTML is escaped using HTML::Entities::Interpolate.
256 Output is to STDOUT.
258 Clearly, you should not use -v to get logging output when using text or
260 HTML output.
261 o report_as_html()
263 Displays various items as HTML for one or all releases.
264 If the 'release' option to "new()" was not used, displays items for all
266 releases.
267 If 'release' was used, restrict the report to just that
269 release/version.
270 Warning: This method must be called via the "report()" method.
272 Output is to STDOUT.
274 o run()
276 Use the options passed to "new()" to determine what to do.
277 Calling "new(convert => 1)" and then "run()" will cause
279 "writer(reader() )" to be called.
280 If you do not set 'convert' to 1 (i.e. use 0 - the default), "run()"
282 will call "read()" and "report()".
283 Return value: 0.
285 o transform(@line)
287 Transform the memory-based version of Changes/CHANGES into an arrayref
288 of hashrefs, where each array element holds data for 1 version.
289 Must be called by "reader()".
291 The array is the text read in from Changes/CHANGES.
293 "transform()" stores the arrayref of hashrefs in $obj -> changes(), for
295 use by "writer()".
296 Return value: The object, for method chaining.
298 o validate($file_name)
300 This method is used by "read()" to validate the contents of the file
301 read in.
302 "validate()" does not read the file.
304 "validate()" calls die when a validation test fails.
306 The file name is just used for reporting.
308 Return value: The object, for method chaining.
310 o writer([$output_file_name])
312 This method writes the arrayref stored in $obj -> changes(), using
313 Config::IniFiles, to the given file.
314 See "transform()".
316 The $output_file_name is optional. It defaults to 'Changelog.ini'.
318 Return value: The object, for method chaining.
320
322 o Are there any things I should look out for?
323 o Invalid dates
324 Invalid dates in Changes/CHANGES cannot be distinguished from
325 comments. That means that if the output file is missing one or
326 more versions, it is because of those invalid dates.
327 o Invalid day-of-week (dow)
329 If Changes/CHANGES includes the dow, it is not cross-checked
330 with the date, so if the dow is wrong, you will not get an
331 error generated.
332 o How do I display Changelog.ini?
334 See "bin/ini.report.pl". It outputs text or HTML.
335 o What is the format of Changelog.ini?
337 See also the next question.
338 See "scripts/report.names.pl" for sample code.
340 Here is a sample:
342 [Module]
344 Name=CGI::Session
345 Changelog.Creator=Module::Metadata::Changes V 1.00
346 Changelog.Parser=Config::IniFiles V 2.39
347 [V 4.30]
349 Date=2008-04-25T00:00:00
350 Comments= <<EOT
351 * FIX: Patch POD for CGI::Session in various places, to emphasize even more that auto-flushing is
352 unreliable, and that flush() should always be called explicitly before the program exits.
353 The changes are a new section just after SYNOPSIS and DESCRIPTION, and the PODs for flush(),
354 and delete(). See RT#17299 and RT#34668
355 * NEW: Add t/new_with_undef.t and t/load_with_undef.t to explicitly demonstrate the effects of
356 calling new() and load() with various types of undefined or fake parameters. See RT#34668
357 EOT
358 [V 4.10]
360 Date=2006-03-28T00:00:00
361 Deploy.Action=Upgrade
362 Deploy.Reason=Security
363 Comments= <<EOT
364 * SECURITY: Hopefully this settles all of the problems with symlinks. Both the file
365 and db_file drivers now use O_NOFOLLOW with open when the file should exist and
366 O_EXCL|O_CREAT when creating the file. Tests added for symlinks. (Matt LeBlanc)
367 * SECURITY: sqlite driver no longer attempts to use /tmp/sessions.sqlt when no
368 Handle or DataSource is specified. This was a mistake from a security standpoint
369 as anyone on the machine would then be able to create and therefore insert data
370 into your sessions. (Matt LeBlanc)
371 * NEW: name is now an instance method (RT#17979) (Matt LeBlanc)
372 EOT
373 o What are the reserved tokens in this format?
375 I am using tokens to refer to both things in [] such as Module, and
376 things on the left hand side of the = signs, such as Date.
377 And yes, these tokens are case-sensitive.
379 Under the [Module] section, the tokens are:
381 o Changelog.Creator
383 sample: Changelog.Creator=Module::Metadata::Changes V 2.00
384 o Changelog.Parser
386 Sample: Changelog.Parser=Config::IniFiles V 2.66
387 o Name
389 Sample: Name=Manage::Module::Changes
390 Under each version (section), whose name is like [V 1.23], the
392 token are as follows.
393 Config::IniFiles calls the V in [V 1.23] a Group Name.
395 o Comments
397 Sample: Comments=- Original version
398 o Date
400 The datetime of the release, in W3CDTF format.
401 Sample: Date=2008-05-02T15:15:45
403 I know the embedded 'T' makes this format a bit harder to read,
405 but the idea is that such files will normally be processed by a
406 program.
407 o Deploy.Action
409 The module author makes this recommendation to the end user.
410 This enables the end user to quickly grep the Changelog.ini, or
412 the output of "ini.report.pl", for things like security fixes
413 and API changes.
414 Run 'bin/ini.report.pl -h' for help.
416 Suggestions:
418 Deploy.Action=Upgrade
420 Deploy.Reason=(Security|Major bug fix)
421 Deploy.Action=Upgrade with caution
423 Deploy.Reason=(Major|Minor) API change/Development version
424 Alternately, the classic syslog tokens could perhaps be used:
426 Debug/Info/Notice/Warning/Error/Critical/Alert/Emergency.
428 I think the values for these 2 tokens (Deploy.*) should be kept
430 terse, and the Comments section used for an expanded
431 explanation, if necessary.
432 Omitting Deploy.Action simply means the module author leaves it
434 up to the end user to read the comments and make up their own
435 mind.
436 "reader()" called directly, or via "ini.report.pl -c" (i.e. old
438 format to ini format converter), inserts these 2 tokens if it
439 sees the word /Security/i in the Comments. It is a crude but
440 automatic warning to end users. The HTML output options ("-t"
441 and "-w") use red text via CSS to highlight these 2 tokens.
442 Of course security is best handled by the module author
444 explicitly inserting a suitable note.
445 And, lastly, any such note is purely up to the judgement of the
447 author, which means differences in opinion are inevitable.
448 o Deploy.Reason
450 The module author gives this reason for their recommended
451 action.
452 o EOT
454 Config::IniFiles uses EOT to terminate multi-line comments.
455 If "transform()" finds a line beginning with EOT, it jams a '-'
457 in front of it.
458 o Why are there not more reserved tokens?
460 Various reasons:
461 o Any one person, or any group, can standardize on their own tokens
463 Obviously, it would help if they advertised their choice,
464 firstly so as to get as many people as possible using the same
465 tokens, and secondly to get agreement on the interpretation of
466 those choices.
467 Truely, there is no point in any particular token if it is not
469 given a consistent meaning.
470 o You can simply add your own to your Changelog.ini file
472 They will then live on as part of the file.
473 Special processing is normally only relevant when converting an
475 old-style Changes/CHANGES file to a new-style Changelog.ini file.
476 However, if you think the new tokens are important enough to be
478 displayed as part of the text and HTML format reports, let me know.
479 I have deliberately not included the Comments in reports since you
481 can always just examine the Changelog.ini file itself for such
482 items. But that too could be changed.
483 o Are single-line comments acceptable?
485 Sure. Here is one:
486 Comments=* INTERNAL: No Changes since 4.20_1. Declaring stable.
488 The '*' is not special, it is just part of the comment.
490 o What is with the datetime format?
492 It is called W3CDTF format. See:
493 http://search.cpan.org/dist/DateTime-Format-W3CDTF/
495 See also ISO8601 format:
497 http://search.cpan.org/dist/DateTime-Format-ISO8601/
499 o Why this file format?
501 Various reasons:
502 o [Module] allows for [Script], [Library], and so on.
504 o *.ini files are easy for beginners to comprehend
505 o Other formats were considered. I made a decision
506 There is no perfect format which will please everyone.
507 Various references, in no particular order:
509 http://use.perl.org/~miyagawa/journal/34850
511 http://use.perl.org/~hex/journal/34864
513 http://redhanded.hobix.com/inspect/yamlIsJson.html
515 http://use.perl.org/article.pl?sid=07/09/06/0324215
517 http://use.perl.org/comments.pl?sid=36862&cid=57590
519 http://use.perl.org/~RGiersig/journal/34370/
521 o The module Config::IniFiles already existed, for reading and
523 writing this format
524 Specifically, Config::IniFiles allows for here documents, which
525 I use to hold the comments authors produce for most of their
526 releases.
527 o What is the difference between release and version?
529 I am using release to refer not just to the version number, but
530 also to all the notes relating to that version.
531 And by notes I mean everything in one section under the name [V
533 $version].
534 o Will you switch to YAML or XML format?
536 YAML? No, never. It is targetted at other situations, and while it
537 can be used for simple applications like this, it can't be hand-
538 written by beginners.
539 And it's unreasonable to force people to write a simple program to
541 write a simple YAML file.
542 XML? Nope. It is great in some situations, but too visually dense
544 and slow to write for this one.
545 o What about adding Changed Requirements to the file?
547 No. That info will be in the changed "Build.PL" or "Makefile.PL"
548 files.
549 It is a pointless burden to make the module author also add that to
551 Changelog.ini.
552 o Who said you had the power to decide on this format?
554 No-one. But I do have the time and the inclination to maintain
555 Module::Metadata::Changes indefinitely.
556 Also, I had a pressing need for a better way to manage metadata
558 pertaining my own modules, for use in my database of modules.
559 One of the reports I produce from this database is visible here:
561 http://savage.net.au/Perl-modules.html
563 Ideally, there will come a time when all of your modules, if not
565 the whole of CPAN, will have Changelog.ini files, so producing such
566 a report will be easy, and hence will be that much more likely to
567 happen.
568 o Why not use, say, Config::Tiny to process Changelog.ini files?
570 Because Config::Tiny contains this line, 's/\s\;\s.+$//g;', so it
571 will mangle text containing English semi-colons.
572 Also, authors add comments per release, and most "Config::*"
574 modules only handle lines of the type X=Y.
575 o How are the old Changes/CHANGES files parsed?
577 The first line is scanned looking for /X::Y/ or /X\.$/. And yes, it
578 fails for modules which identify themselves like Fuse-PDF not at
579 the end of the line.
580 Then lines looking something like /$a_version_number ...
582 $a_datetime/ are searched for. This is deemed to be the start of
583 information pertaining to a specific release.
584 Everything up to the next release, or EOF, is deemed to belong to
586 the release just identified.
587 This means a line containing a version number without a date is not
589 recognized as a new release, so that that line and the following
590 comments are added to the 'current' release info.
591 For an example of this, process the "Changes" file from
593 CGI::Session (t/Changes), and scan the output for '[4.00_01]',
594 which you will see contains stuff for V 3.12, 3.8 and 3.x.
595 See above, under the list of reserved tokens, for how security
597 advisories are inserted in the output stream.
598 o Is this conversion process perfect?
600 Well, no, actually, but it will be as good as I can make it.
601 For example, version numbers like '3.x' are turned into '3.'.
603 You will simply have to scrutinize (which means 'read carefully')
605 the output of this conversion process.
606 If a Changes/CHANGES file is not handled by the current version,
608 log a bug report on Request Tracker: http://rt.cpan.org/Public/
609 o How are datetimes in old-style files parsed?
611 Firstly try DateTime::Format::HTTP, and if that fails, try these
612 steps:
613 o Strip 'st' from 1st, 'nd' from 2nd, etc
615 o Try DateTime::Format::Strptime
616 o If that fails, strip Monday, etc, and retry
617 DateTime::Format::Strptime
618 I noticed some dates were invalid because the day of the week
619 did not match the day of the month. So, I arbitrarily chop the
620 day of the week, and retry.
621 Other date parsing modules are Date::Manip, Date::Parse and
623 Regexp::Common::time.
624 o Why did you choose these 2 modules?
626 I had a look at a few Changes/CHANGES files, and these made sense.
627 If appropriate, other modules can be added to the algorithm.
629 See the discussion on this page (search for 'parse multiple
631 formats'):
632 http://datetime.perl.org/index.cgi?FAQBasicUsage
634 If things get more complicated, I will reconsider using
636 DateTime::Format::Builder.
637 o What happens for 2 releases on the same day?
639 It depends whether or not the version numbers are different.
640 The "Changes" file for CGI::Session contains 2 references to
642 version 4.06 :-(.
643 As long as the version numbers are different, the date does not
645 actually matter.
646 o Will a new file format mean more work for those who maintain CPAN?
648 Yes, I am afraid so, unless they completely ignore me!
649 But I am hopeful this will lead to less work overall.
651 o Why did you not use the "Template Toolkit" for the HTML?
653 It is too complex for this tiny project.
654 o Where do I go for support?
656 Log a bug report on Request Tracker: http://rt.cpan.org/Public/
657 If it concerns failure to convert a specific Changes/CHANGES file,
659 just provide the name of the module and the version number.
660 It would help - if the problem is failure to parse a specific
662 datetime format - if you could advise me on a suitable
663 "DateTime::Format::*" module to use.
664
666 The file Changes was converted into Changelog.ini by
667 Module::Metadata::Changes.
668
670 Version numbers < 1.00 represent development versions. From 1.00 up,
671 they are production versions.
672
674 <https://github.com/ronsavage/Module-Metadata-Changes>.
675
677 Email the author, or log a bug on RT:
678 <https://rt.cpan.org/Public/Dist/Display.html?Name=Module::Metadata::Changes>.
680
682 App::ParseCPANChanges.
683 CPAN::Changes
685 Module::Changes
687
689 Module::Metadata::Changes was written by Ron Savage <ron@savage.net.au>
690 in 2008.
691 Home page: http://savage.net.au/index.html
693
695 Australian copyright (c) 2008, Ron Savage. All Programs of mine
696 are 'OSI Certified Open Source Software'; you can redistribute
697 them and/or modify them under the terms of The Perl License, a
698 copy of which is available at: http://dev.perl.org/licenses/
699perl v5.28.0 2018-07-15 Module::Metadata::Changes(3)