NAME
    App::instopt - Download and install software

VERSION
    This document describes version 0.020 of App::instopt (from Perl
    distribution App-instopt), released on 2021-07-25.

SYNOPSIS
    See instopt script.

FUNCTIONS
  cleanup_download_dir
    Usage:

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

    Remove older versions of downloaded software.

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    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)

  cleanup_install_dir
    Usage:

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

    Remove inactive versions of installed software.

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    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)

  compare_versions
    Usage:

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

    Compare installed vs downloaded vs latest versions of installed
    software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    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)

  download
    Usage:

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

    Download latest version of one or more software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arch => *software::arch*

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   softwares_or_patterns* => *array[str]*

    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)

  download_all
    Usage:

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

    Download latest version of all known software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arch => *software::arch*

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    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)

  is_downloaded_any
    Usage:

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

    Check if any version of a software is downloaded.

    The download does not need to be the latest version. To check if the
    latest version of a software is downloaded, use "is-downloaded-latest".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   quiet => *bool*

    *   software* => *str*

    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)

  is_downloaded_latest
    Usage:

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

    Check if latest version of a software has been downloaded.

    To only check whether any version of a software has been downloaded, use
    "is-downloaded-any".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   quiet => *bool*

    *   software* => *str*

    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)

  is_installed_any
    Usage:

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

    Check if any version of a software is installed.

    The installed version does not need to be the latest. To check whether
    the latest version of a software is installed, use
    "is-installed-latest".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   quiet => *bool*

    *   software* => *str*

    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)

  is_installed_latest
    Usage:

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

    Check if latest version of a software is installed.

    To only check whether any version of a software is installed, use
    "is-installed-any".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   quiet => *bool*

    *   software* => *str*

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

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

    List software.

    Examples:

    *   List software that are installed but out-of-date:

         list(installed => 1, latest_installed => 0);

        Result:

         [
           500,
           "Function died: Failed to change directory to '/home/s1/software': No such file or directory at lib/App/instopt.pm line 331.\n",
           undef,
           {
             logs => [
               {
                 file    => "/home/s1/perl5/perlbrew/perls/perl-5.30.2/lib/site_perl/5.30.2/Perinci/Access/Schemeless.pm",
                 func    => "Perinci::Access::Schemeless::action_call",
                 line    => 501,
                 package => "Perinci::Access::Schemeless",
                 time    => 1627177634,
                 type    => "create",
               },
             ],
           },
         ]

    *   List software that have been downloaded but out-of-date:

         list(downloaded => 1, latest_downloaded => 0); # -> [200, "OK", [], {}]

    *   List software that have their latest version downloaded but not
        installed:

         list(latest_downloaded => 1, latest_installed => 0); # -> [200, "OK", [], {}]

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   detail => *true*

    *   download_dir => *dirname*

    *   downloaded => *bool*

        If true, will only list downloaded software.

    *   install_dir => *dirname*

    *   installed => *bool*

        If true, will only list installed software.

    *   latest_downloaded => *bool*

        If true, will only list software which have their latest version
        downloaded.

        If set to true, a software which is not downloaded, or downloaded
        but does not have the latest version downloaded, will not be
        included.

        If set to false, a software which has no downloaded versions, or
        does not have the latest version downloaded, will be included.

    *   latest_installed => *bool*

        If true, will only list software which have their latest version
        installed.

        If set to true, a software which is not installed, or installed but
        does not have the latest version installed, will not be included.

        If set to false, a software which is not installed, or does not have
        the latest version installed, will be included.

    *   program_dir => *dirname*

    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_downloaded
    Usage:

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

    List all downloaded software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arch => *software::arch*

    *   detail => *true*

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    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_downloaded_versions
    Usage:

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

    List all downloaded versions of a software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arch => *software::arch*

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   software* => *str*

    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_installed
    Usage:

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

    List all installed software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   detail => *true*

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    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_installed_versions
    Usage:

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

    List all installed versions of a software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   software* => *str*

    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)

  update
    Usage:

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

    Update a software to the latest version.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download => *bool* (default: 1)

        Whether to download latest version from URLor just find from
        download dir.

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    *   softwares_or_patterns* => *array[str]*

    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)

  update_all
    Usage:

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

    Update all installed software.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   download => *bool* (default: 1)

        Whether to download latest version from URLor just find from
        download dir.

    *   download_dir => *dirname*

    *   install_dir => *dirname*

    *   program_dir => *dirname*

    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/App-instopt>.

SOURCE
    Source repository is at <https://github.com/perlancar/perl-App-instopt>.

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

    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>

CONTRIBUTORS
    *   James Raspass <jraspass@gmail.com>

    *   liana (on netbook-dell-xps13) <lianamelati88@gmail.com>

    *   perlancar (on pc-office) <perlancar@gmail.com>

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