NAME

Software::Catalog::Role::Software - Role for software

VERSION

This document describes version 1.0.8 of Software::Catalog::Role::Software (from Perl distribution Software-Catalog), released on 2024-07-17.

REQUIRED METHODS

archive_info

Get information about an archive of software download.

Usage:

 my $envres = $swobj->archive_info(%args);
 # sample result:
 # [200, "OK", {
 #   programs => [
 #     {name=>"firefox", path=>"/"},
 #   ],
 # }]

Return enveloped result. The payload is a hash that can contain these keys: programs which is an array of {name=>"PROGRAM_NAME", path=>"/PATH/"} records.

Arguments:

• platform_label

  Str, ...

• format

  Str, optional. If software provides several archive formats that might differ in structure or other aspects (e.g. ".zip" and ".tar.gz"), the user can choose which by passing this argument.

• version

  Str. Optional. If not specified, this role's method modifier will supply the default from "latest_version".

available_versions

List all available versions of a software. This usually means versions available for download. It does not always equate all known versions.

Usage:

 my $envres = $swobj->available_versions(%args);

Return enveloped result.

Arguments:

• platform_label

  Str, ...

If you do not want to provide this functionality, you can return something like:

 [501, "Not implemented"]

cmp_version

Compare two version strings and return -1|0|1 like Perl's cmp() operator.

Usage:

 my $cmp = $swobj->cmp_version($v1, $v2); # -1, 0, or 1

This method can often be supplied by a Versioning::Scheme::* role if your software follows a scheme that is supported.

download_url

Get download URL.

Usage:

 my $envres = $swobj->download_url(%args);
 # sample result:
 # [200, "OK", "https://www.example.org/foo-1.23.tar.gz"]

Return enveloped result.

Arguments:

• platform_label

  Str, ....

• version

  Str. Optional. If not specified, this role's method modifier will supply the default from "latest_version".

homepage_url

Return the homepage URL.

Arguments: none.

is_dedicated_profile

Check whether the software uses "dedicated profile".

Usage:

 my $is_dedicated = $swobj->is_dedicated_profile;

This method is created to support Firefox 67+ but can be used by other software too. If is_dedicated_profile returns a true value, it means the software checks program location for profile and we should not use symlink for latest version, e.g. /opt/firefox -> /opt/firefox-70.0 but should copy /opt/firefox-70.0 (or later version) to /opt/firefox instead, to avoid changing of program location whenever there's a new version.

Arguments: none.

is_valid_version

Check whether a version string is a syntactically valid version string for a particular software. This does not mean that the said version actually exists, just that the syntax is valid.

Usage:

 my $is_valid = $swobj->is_valid_version;

This method can often be supplied by a Versioning::Scheme::* role if your software follows a scheme that is supported.

latest_version

Get latest version information.

Usage:

 my $envres = $swobj->latest_version;
 # sample result:
 # [200, "OK", "80.0.1"]

Return enveloped result.

Arguments:

• platform_label

  Str, ....

• version

  Str. Optional. If not specified, this role's method modifier will supply the default from "latest_version".

platform_label_to_spec

List supporter platforms. Must return a hashref of platform labels as key and platform specifications as values (see Devel::Platform::Match).

release_note

Get release note.

Usage:

 my $envres = $swobj->release_note(%args);
 # sample result:
 # [200, "OK", "..."]

Return enveloped result.

Arguments:

• platform_label

  Str, ...

• format

  Str, optional. If software provides several release note formats, the user can choose which by passing this argument. A sane default will be chosen.

• version

  Str. Optional. If not specified, this role's method modifier will supply the default from "latest_version".

PROVIDED METHODS

available_platform_labels

Return a sorted list of available platforms for a software.

 my @platform_labels = $swobj->available_platform_labels;

This information is retrieved from "platform_label_to_spec".

HOMEPAGE

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

SOURCE

Source repository is at https://github.com/perlancar/perl-Software-Catalog.

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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024, 2020, 2019, 2018, 2015, 2014, 2012 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=Software-Catalog

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.

cpanm Software::Catalog

perl -MCPAN -e shell
install Software::Catalog