NAME

       dpt-lib.sh -- dpt shell library

DESCRIPTION

       dpt-lib.sh is sourced by 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 .git/ sub directory.

USAGE

       Source the file at the beginning of the shell script as

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

AVAILABLE FUNCTIONS

       "die"
           Parameters: $message

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

       "warn"
           Parameters: $message

           Echos "W: $message" to STDERR.

       "info"
           Parameters: $message

           Echos "I: $message" to STDERR.

       "header"
           Parameters: $title

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

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

       "promptyesno"
           Parameters: $prompt

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

       "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).

       "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.

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

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

       "colored"
           Parameters: $color, $text

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

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

       "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): "BLACK",
           "RED", "GREEN", "YELLOW", "BLUE", "MAGENTA", "CYAN", "WHITE".

AVAILABLE VARIABLES

       "PKG"
           Source package name, from debian/changelog.

       "VER"
           Source package version, from debian/changelog.

       "UVER"
           Upstream version, i.e. source package version  (from debian/changelog) without epoch
           and Debian revision.

       "DIST"
           Source package distribution, from debian/changelog.

       Colors
           Cf. the "colored()" function above.

           For using colors directly, the following variables exist;

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

           For background colors, the same colors exist as "BG_C_foo".

ENVIRONMENT VARIABLES

       "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 variables derived from debian/changelog are not available.

SEE ALSO

       dpt-config(5) for discussion of "$DPT__SCRIPTS".

COPYRIGHT & LICENSE

       Copyright 2022-2023 gregor herrmann gregoa@debian.org

       Copyright 2022 Damyan Ivanov dmn@debian.org

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