/ 
App-CPANChangesUtils-0.077
River stage one • 1 direct dependent • 1 total dependent
/ parse-cpan-changes

NAME

parse-cpan-changes - Parse CPAN Changes file

VERSION

This document describes version 0.077 of parse-cpan-changes (from Perl distribution App-CPANChangesUtils), released on 2022-06-13.

SYNOPSIS

% parse-cpan-changes [--class=perl::modname] [--debug|--log-level=level|--quiet|--trace|--verbose] [--format=name|--json] [--(no)naked-res] [--page-result[=program]|--view-result[=program]] [--parse-release-metadata|--no-parse-release-metadata|--noparse-release-metadata] [--unbless|--no-unbless|--nounbless] -- [file]

See examples in the "EXAMPLES" section.

DESCRIPTION

This utility is a simple wrapper for CPAN::Changes.

OPTIONS

* marks required options.

Main options

--class=s

Default value:

"CPAN::Changes"
--file=s

If not specified, will look for file called Changes/ChangeLog in current directory.

Can also be specified as the 1st command-line argument.

--no-parse-release-metadata

If set to true (the default), the utility will attempt to parse release metadata in the release note. The release note is the text after the version and date in the first line of a release entry:

0.001 - 2022-06-10 THIS IS THE RELEASE NOTE AND CAN BE ANY TEXT

One convention I use is for the release note to be semicolon-separated of metadata entries, where each metadata is in the form of HTTP-header-like "Name: Value" text where Name is dash-separated words and Value is any text that does not contain newline or semicolon. Example:

0.001 - 2022-06-10  Urgency: high; Backward-Incompatible: yes

Note that Debian changelog also supports "key=value" in the release line.

This option, when enabled, will first check if the release note is indeed in the form of semicolon-separated metadata. If yes, will create a key called metadata in the release result structure containing a hash of metadata:

{ "urgency" => "high", "backward-incompatible" => "yes" }

Note that the metadata names are converted to lowercase.

--no-unbless

If you set this to false, you'll need to use an output format that can handle serializing Perl objects, e.g. on the CLI using --format=perl.

Logging options

--debug

Shortcut for --log-level=debug.

--log-level=s

Set log level.

By default, these log levels are available (in order of increasing level of importance, from least important to most): trace, debug, info, warn/warning, error, fatal. By default, the level is usually set to warn, which means that log statements with level info and less important levels will not be shown. To increase verbosity, choose info, debug, or fatal.

For more details on log level and logging, as well as how new logging levels can be defined or existing ones modified, see Log::ger.

--quiet

Shortcut for --log-level=error.

--trace

Shortcut for --log-level=trace.

--verbose

Shortcut for --log-level=info.

Output options

--format=s

Choose output format, e.g. json, text.

Default value:

undef

Output can be displayed in multiple formats, and a suitable default format is chosen depending on the application and/or whether output destination is interactive terminal (i.e. whether output is piped). This option specifically chooses an output format.

--json

Set output format to json.

--naked-res

When outputing as JSON, strip result envelope.

Default value:

0

By default, when outputing as JSON, the full enveloped result is returned, e.g.:

[200,"OK",[1,2,3],{"func.extra"=>4}]

The reason is so you can get the status (1st element), status message (2nd element) as well as result metadata/extra result (4th element) instead of just the result (3rd element). However, sometimes you want just the result, e.g. when you want to pipe the result for more post-processing. In this case you can use --naked-res so you just get:

[1,2,3]
--page-result

Filter output through a pager.

This option will pipe the output to a specified pager program. If pager program is not specified, a suitable default e.g. less is chosen.

--view-result

View output using a viewer.

This option will first save the output to a temporary file, then open a viewer program to view the temporary file. If a viewer program is not chosen, a suitable default, e.g. the browser, is chosen.

Other options

--help, -h, -?

Display help message and exit.

--version, -v

Display program's version and exit.

COMPLETION

This script has shell tab completion capability with support for several shells.

bash

To activate bash completion for this script, put:

complete -C parse-cpan-changes parse-cpan-changes

in your bash startup (e.g. ~/.bashrc). Your next shell session will then recognize tab completion for the command. Or, you can also directly execute the line above in your shell to activate immediately.

It is recommended, however, that you install modules using cpanm-shcompgen which can activate shell completion for scripts immediately.

tcsh

To activate tcsh completion for this script, put:

complete parse-cpan-changes 'p/*/`parse-cpan-changes`/'

in your tcsh startup (e.g. ~/.tcshrc). Your next shell session will then recognize tab completion for the command. Or, you can also directly execute the line above in your shell to activate immediately.

It is also recommended to install shcompgen (see above).

other shells

For fish and zsh, install shcompgen as described above.

EXAMPLES

Parse with default settings

% parse-cpan-changes
[
   200,
   "OK",
   {
      "months" : {
         "Apr" : 4,
         "Aug" : 8,
         "Dec" : 12,
         "Feb" : 2,
         "Jan" : 1,
         "Jul" : 7,
         "Jun" : 6,
         "Mar" : 3,
         "May" : 5,
         "Nov" : 11,
         "Oct" : 10,
         "Sep" : 9
      },
      "preamble" : "",
      "releases" : {
         "0.01" : {
            "_parsed_date" : "2013-08-05",
            "changes" : {
               "" : {
                  "changes" : [
                     "First version."
                  ],
                  "name" : ""
               }
            },
            "date" : "2013-08-05",
            "metadata" : {
               "released-by" : "SHARYANTO"
            },
            "note" : "Released-By: SHARYANTO",
            "version" : "0.01"
         },
         "0.02" : {
            "_parsed_date" : "2013-08-06",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes. Add missing dep [CT]."
                  ],
                  "name" : ""
               }
            },
            "date" : "2013-08-06",
            "metadata" : {
               "released-by" : "SHARYANTO"
            },
            "note" : "Released-By: SHARYANTO",
            "version" : "0.02"
         },
         "0.03" : {
            "_parsed_date" : "2013-11-01",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes. Mention some other modules and the rationale for the script."
                  ],
                  "name" : ""
               }
            },
            "date" : "2013-11-01",
            "metadata" : {
               "released-by" : "SHARYANTO"
            },
            "note" : "Released-By: SHARYANTO",
            "version" : "0.03"
         },
         "0.04" : {
            "_parsed_date" : "2014-07-22",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes.",
                     "Switch CLI scripts from using Perinci::CmdLine to Perinci::CmdLine::Any to reduce size of dependencies."
                  ],
                  "name" : ""
               }
            },
            "date" : "2014-07-22",
            "metadata" : {
               "released-by" : "SHARYANTO"
            },
            "note" : "Released-By: SHARYANTO",
            "version" : "0.04"
         },
         "0.05" : {
            "_parsed_date" : "2015-09-03",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes.",
                     "[dist] Move spec prereqs from RuntimeRequires to DevelopRecommends to reduce deps but still allow indicating spec requirement."
                  ],
                  "name" : ""
               }
            },
            "date" : "2015-09-03",
            "metadata" : {
               "released-by" : "PERLANCAR"
            },
            "note" : "Released-By: PERLANCAR",
            "version" : "0.05"
         },
         "0.06" : {
            "_parsed_date" : "2016-01-18",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes.",
                     "[build] Rebuild to fix POD section ordering."
                  ],
                  "name" : ""
               }
            },
            "date" : "2016-01-18",
            "metadata" : {
               "released-by" : "PERLANCAR"
            },
            "note" : "Released-By: PERLANCAR",
            "version" : "0.06"
         },
         "0.070" : {
            "_parsed_date" : "2019-07-03",
            "changes" : {
               "" : {
                  "changes" : [
                     "Add option --class to customize parser class."
                  ],
                  "name" : ""
               }
            },
            "date" : "2019-07-03",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "medium"
            },
            "note" : "Released-By: PERLANCAR; Urgency: medium",
            "version" : "0.070"
         },
         "0.071" : {
            "_parsed_date" : "2020-10-06",
            "changes" : {
               "" : {
                  "changes" : [
                     "Add option --no-unbless."
                  ],
                  "name" : ""
               }
            },
            "date" : "2020-10-06",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "medium"
            },
            "note" : "Released-By: PERLANCAR; Urgency: medium",
            "version" : "0.071"
         },
         "0.072" : {
            "_parsed_date" : "2021-05-25",
            "changes" : {
               "" : {
                  "changes" : [
                     "[build] Rebuild to update Sah coercion module names (old Sah coercion modules have been purged from CPAN)."
                  ],
                  "name" : ""
               }
            },
            "date" : "2021-05-25",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "high"
            },
            "note" : "Released-By: PERLANCAR; Urgency: high",
            "version" : "0.072"
         },
         "0.073" : {
            "_parsed_date" : "2021-10-17",
            "changes" : {
               "" : {
                  "changes" : [
                     "Rename module/dist App-ParseCPANChanges -> App-CPANChangesUtils. - Add CLI format-cpan-changes."
                  ],
                  "name" : ""
               }
            },
            "date" : "2021-10-17",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "medium"
            },
            "note" : "Released-By: PERLANCAR; Urgency: medium",
            "version" : "0.073"
         },
         "0.075" : {
            "_parsed_date" : "2022-06-10",
            "changes" : {
               "" : {
                  "changes" : [
                     "[utility parse-cpan-changes] Add option parse_release_metadata (defaults to true) to parse 'key: value' metadata in the release note."
                  ],
                  "name" : ""
               }
            },
            "date" : "2022-06-10",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "medium"
            },
            "note" : "Released-By: PERLANCAR; Urgency: medium",
            "version" : "0.075"
         },
         "0.076" : {
            "_parsed_date" : "2022-06-10",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes.",
                     "[ux] Add an example."
                  ],
                  "name" : ""
               }
            },
            "date" : "2022-06-10",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "low"
            },
            "note" : "Released-By: PERLANCAR; Urgency: low",
            "version" : "0.076"
         },
         "0.077" : {
            "_parsed_date" : "2022-06-13",
            "changes" : {
               "" : {
                  "changes" : [
                     "No functional changes.",
                     "[ux] Show content of Changes file in example."
                  ],
                  "name" : ""
               }
            },
            "date" : "2022-06-13",
            "metadata" : {
               "released-by" : "PERLANCAR",
               "urgency" : "low"
            },
            "note" : "Released-By: PERLANCAR; Urgency: low",
            "version" : "0.077"
         }
      }
   },
   {}
]

Content of Changes file:

0.076   2022-06-10  Released-By: PERLANCAR; Urgency: low

        - No functional changes.

        - [ux] Add an example.


0.075   2022-06-10  Released-By: PERLANCAR; Urgency: medium

        - [utility parse-cpan-changes] Add option parse_release_metadata
          (defaults to true) to parse 'key: value' metadata in the release
          note.


0.073   2021-10-17  Released-By: PERLANCAR; Urgency: medium

    - Rename module/dist App-ParseCPANChanges -> App-CPANChangesUtils.

        - Add CLI format-cpan-changes.


0.072   2021-05-25  Released-By: PERLANCAR; Urgency: high

    - [build] Rebuild to update Sah coercion module names (old Sah coercion
          modules have been purged from CPAN).


0.071   2020-10-06  Released-By: PERLANCAR; Urgency: medium

    - Add option --no-unbless.


0.070   2019-07-03  Released-By: PERLANCAR; Urgency: medium

    - Add option --class to customize parser class.


0.06    2016-01-18  Released-By: PERLANCAR

        - No functional changes.

        - [build] Rebuild to fix POD section ordering.


0.05    2015-09-03  Released-By: PERLANCAR

    - No functional changes.

    - [dist] Move spec prereqs from RuntimeRequires to
      DevelopRecommends to reduce deps but still allow indicating spec
      requirement.


0.04     2014-07-22  Released-By: SHARYANTO

         - No functional changes.

         - Switch CLI scripts from using Perinci::CmdLine to
           Perinci::CmdLine::Any to reduce size of dependencies.


0.03    2013-11-01  Released-By: SHARYANTO

        - No functional changes. Mention some other modules and the rationale
          for the script.


0.02    2013-08-06  Released-By: SHARYANTO

        - No functional changes. Add missing dep [CT].


0.01    2013-08-05  Released-By: SHARYANTO

        - First version.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-CPANChangesUtils.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-CPANChangesUtils.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2021 by perlancar <perlancar@cpan.org>.

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

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-CPANChangesUtils

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.