NAME
    Module::Abstract::Cwalitee - Calculate the cwalitee of your module
    Abstract

VERSION
    This document describes version 0.007 of Module::Abstract::Cwalitee
    (from Perl distribution Module-Abstract-Cwalitee), released on
    2021-06-06.

SYNOPSIS
     use Module::Abstract::Cwalitee qw(
         calc_module_abstract_cwalitee
         list_module_abstract_cwalitee_indicators
     );

     my $res = calc_module_abstract_cwalitee(
         abstract => 'Calculate the cwalitee of your module Abstract',
     );

DESCRIPTION
    What is module abstract cwalitee? A metric to attempt to gauge the
    quality of your module's Abstract. Since actual quality is hard to
    measure, this metric is called a "cwalitee" instead. The cwalitee
    concept follows "kwalitee" [1] which is specifically to measure the
    quality of CPAN distribution. I pick a different spelling to avoid
    confusion with kwalitee. And unlike kwalitee, the unqualified term
    "cwalitee" does not refer to a specific, particular subject. There can
    be "module abstract cwalitee" (which is handled by this module), "CPAN
    Changes cwalitee", and so on.

FUNCTIONS
  calc_module_abstract_cwalitee
    Usage:

     calc_module_abstract_cwalitee(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Examples:

    *   Example of a good Abstract:

         calc_module_abstract_cwalitee(abstract => "Calculate the frobnitz of thromblemeisters");

        Result:

         [
           200,
           "OK",
           [
             {
               indicator => "not_empty",
               num => 1,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "language_english",
               num => 2,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "no_shouting",
               num => 3,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_end_with_dot",
               num => 4,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_module_name",
               num => 5,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_multiline",
               num => 6,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_redundant",
               num => 7,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_start_with_lowercase_letter",
               num => 8,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_template",
               num => 9,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_too_long",
               num => 10,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_too_short",
               num => 11,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "Score",
               result => "100.00",
               result_summary => "11 out of 11",
             },
           ],
           {},
         ]

    *   Example of a not-so-good Abstract:

         calc_module_abstract_cwalitee(abstract => "PERL MODULE TO DO SOMETHING");

        Result:

         [
           200,
           "OK",
           [
             {
               indicator => "not_empty",
               num => 1,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "language_english",
               num => 2,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "no_shouting",
               num => 3,
               result => 0,
               result_summary => "All-caps",
               severity => 3,
             },
             {
               indicator => "not_end_with_dot",
               num => 4,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_module_name",
               num => 5,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_multiline",
               num => 6,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_redundant",
               num => 7,
               result => 0,
               result_summary => "Saying 'PERL MODULE TO' is redundant, omit it",
               severity => 3,
             },
             {
               indicator => "not_start_with_lowercase_letter",
               num => 8,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_template",
               num => 9,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_too_long",
               num => 10,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             {
               indicator => "not_too_short",
               num => 11,
               result => 1,
               result_summary => "",
               severity => 3,
             },
             { indicator => "Score", result => 81.82, result_summary => "9 out of 11" },
           ],
           {},
         ]

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   abstract* => *str*

    *   exclude_indicator => *array[str]*

        Do not use these indicators.

    *   exclude_indicator_module => *array[perl::modname]*

        Do not use indicators from these modules.

    *   exclude_indicator_status => *array[str]*

        Do not use indicators having these statuses.

    *   include_indicator => *array[str]*

        Only use these indicators.

    *   include_indicator_module => *array[perl::modname]*

        Only use indicators from these modules.

    *   include_indicator_status => *array[str]* (default: ["stable"])

        Only use indicators having these statuses.

    *   min_indicator_severity => *uint* (default: 1)

        Minimum indicator severity.

    *   module => *perl::modname*

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  list_module_abstract_cwalitee_indicators
    Usage:

     list_module_abstract_cwalitee_indicators(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Examples:

    *   List all installed indicators from all modules:

         list_module_abstract_cwalitee_indicators();

        Result:

         [
           200,
           "OK",
           [
             "language_english",
             "no_shouting",
             "not_empty",
             "not_end_with_dot",
             "not_module_name",
             "not_multiline",
             "not_redundant",
             "not_start_with_lowercase_letter",
             "not_template",
             "not_too_long",
             "not_too_short",
           ],
           {},
         ]

    *   List only certain names, show details:

         list_module_abstract_cwalitee_indicators(
           detail  => 1,
           include => ["not_too_short", "not_too_long", "not_template"]
         );

        Result:

         [
           200,
           "OK",
           [
             {
               module   => "Module::Abstract::Cwalitee::Core",
               name     => "not_template",
               priority => 50,
               severity => 3,
               status   => "stable",
               summary  => undef,
             },
             {
               module   => "Module::Abstract::Cwalitee::Core",
               name     => "not_too_long",
               priority => 50,
               severity => 3,
               status   => "stable",
               summary  => undef,
             },
             {
               module   => "Module::Abstract::Cwalitee::Core",
               name     => "not_too_short",
               priority => 50,
               severity => 3,
               status   => "stable",
               summary  => undef,
             },
           ],
           {},
         ]

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   detail => *bool*

    *   exclude => *array[str]*

        Exclude by name.

    *   exclude_module => *array[perl::modname]*

        Exclude by module.

    *   exclude_status => *array[str]*

        Exclude by status.

    *   include => *array[str]*

        Include by name.

    *   include_module => *array[perl::modname]*

        Include by module.

    *   include_status => *array[str]* (default: ["stable"])

        Include by status.

    *   max_severity => *int* (default: 5)

        Maximum severity.

    *   min_severity => *int* (default: 1)

        Minimum severity.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Module-Abstract-Cwalitee>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Module-Abstract-Cwalitee>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Abstract-Cwali
    tee>

    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.

SEE ALSO
    [1] <https://cpants.cpanauthors.org/>

    App::ModuleAbstractCwaliteeUtils for the CLI's.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2021, 2019 by 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.

