=head1 NAME

dpt-lib.sh - dpt shell library

=head1 DESCRIPTION

B<dpt-lib.sh> is sourced by L<dpt(1)> and contains a collection of shell
functions and variables which can be used by dpt subcommands written in
shell. As a side effect, it also sanity checks if the script is run from a
source package directory with a F<.git/> sub directory.

=head1 USAGE

Source the file at the beginning of the shell script as

    . "${DPT__SCRIPTS:-/usr/share/pkg-perl-tools}/lib/dpt-lib.sh"

=head1 AVAILABLE FUNCTIONS

=over

=item C<die>

Parameters: $message

Echos "E: $message" to STDERR and exits 1.

=item C<warn>

Parameters: $message

Echos "W: $message" to STDERR.

=item C<info>

Parameters: $message

Echos "I: $message" to STDERR.

=item C<header>

Parameters: $title

Outputs $title with an empty line before and underlined,
kind of like a header.

=item C<anykey>

Tells the user to press any key and waits for a keypress.

=item C<promptyesno>

Parameters: $prompt

Issues a read() request with y/N options, printing $prompt. Returns true,
if 'y' or 'Y' is pressed, false otherwise.

=item C<is_command>

Parameters: $command, $package (optional)

Checks if $command can be executed (running "command -v"); returns false,
outputs a warning (and optionally a hint to install $package).

=item C<is_installed>

Parameters: $package_name, $minimum_package_version (optional)

Checks if $package_name is installed, optionally at
$minimum_package_version, and returns false with a warning otherwise.

=item C<is_pkg_perl>

Checks if debian/control contains the Debian Perl Group email address.

=item C<gitddiff>

Offers to show the diff against the last debian/ tag, if there is any.

=item C<colored>

Parameters: $color, $text

Outputs $text in $color, unless the NO_COLOR environment variable is set.

Available colors are (in capital letters):
C<BLACK>, C<RED>, C<GREEN>, C<YELLOW>, C<BLUE>, C<MAGENTA>, C<CYAN>, C<WHITE>.

=item C<extra_colored>

Parameters: $color, $bgcolor, $text

Outputs $text in foreground $color on $bgcolor, unless the NO_COLOR environment variable is set.

Available colors for both foreground and background are (in capital letters):
C<BLACK>, C<RED>, C<GREEN>, C<YELLOW>, C<BLUE>, C<MAGENTA>, C<CYAN>, C<WHITE>.

=back

=head1 AVAILABLE VARIABLES

=over

=item C<PKG>

Source package name, from F<debian/changelog>.

=item C<VER>

Source package version, from F<debian/changelog>.

=item C<UVER>

Upstream version, i.e. source package version (from F<debian/changelog>)
without epoch and Debian revision.

=item C<DIST>

Source package distribution, from F<debian/changelog>.

=item Colors

Cf. the C<colored()> function above.

For using colors directly, the following variables exist;

C<C_BLACK>, C<C_RED>, C<C_GREEN>, C<C_YELLOW>, C<C_BLUE>, C<C_MAGENTA>, C<C_CYAN>, C<C_WHITE>,
plus C<C_RESET> to go back from coloring.

For background colors, the same colors exist as C<BG_C_foo>.

=back

=head1 ENVIRONMENT VARIABLES

=over

=item C<OOT>

OOT (as in "out-of-tree"), if set, disables the check if a script is run in
a source package directory and a Git repository.

Can be used as

    OOT=1 . "${DPT__SCRIPTS:-/usr/share/pkg-perl-tools}/lib/dpt-lib.sh"

and is useful for scripts which are run on build results etc.

This also means that the L<variables|/"AVAILABLE VARIABLES"> derived from
F<debian/changelog> are not available.

=back

=head1 SEE ALSO

L<dpt-config(5)> for discussion of C<$DPT__SCRIPTS>.

=head1 COPYRIGHT & LICENSE

Copyright 2022-2024 gregor herrmann L<gregoa@debian.org>

Copyright 2022 Damyan Ivanov L<dmn@debian.org>

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

=cut
