NAME

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

VERSION

This document describes version 1.0.7 of Software::Catalog::Role::Software (from Perl distribution Software-Catalog), released on 2020-10-02.

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:

• arch

  Str, must be one of known architectures (see "canon2native_arch_map"). Optional. If not specified, this role's method modifier will supply the default (the architecture the perl interpreter is built on).

• 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:

• arch

  Str, must be one of known architectures (see "canon2native_arch_map"). Optional. If not specified, this role's method modifier will supply the default (the architecture the perl interpreter is built on).

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

 [501, "Not implemented"]

canon2native_arch_map

Return a mapping of architecture names from canonical to native.

 my $hashref = $swobj->canon2native_arch_map;

The canonical architecture names are:

 linux-x86        (Linux, Intel x86 32bit)
 linux-x86_64     (Linux, AMD/Intel 64bit)
 win32            (Windows, Intel x86 32bit)
 win64            (Windows, AMD/Intel 64bit)

Since each software might label the architectures differently, you will need to provide a mapping. For example:

 sub canon2native_arch_map {
     return +{
         'linux-x86_64' => 'linux64',
         'win64' => 'win64',
     },
 }

When an architecture is not mapped, it is assumed to be unsupported by the software.

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:

• arch

  Str, must be one of known architectures (see "canon2native_arch_map"). Optional. If not specified, this role's method modifier will supply the default (the architecture the perl interpreter is built on).

• 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:

• arch

  Str, must be one of known architectures (see "canon2native_arch_map"). Optional. If not specified, this role's method modifier will supply the default (the architecture the perl interpreter is built on).

• version

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

release_note

Get release note.

Usage:

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

Return enveloped result.

Arguments:

• arch

  Str, must be one of known architectures (see "canon2native_arch_map"). Optional. If not specified, this role's method modifier will supply the default (the architecture the perl interpreter is built on).

• 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_archs

Return a sorted list of available architectures for a software.

 my @archs = $swobj->available_archs;

This information is retrieved from "canon2native_arch_map".

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.

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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

cpanm Software::Catalog

perl -MCPAN -e shell
install Software::Catalog