nps

#!/usr/bin/env bash

VERSION="0.1.6"

HELP="Usage: nps [OPTION]... SEARCH_TERM
Find SEARCH_TERM in available nix packages and sort results by relevance.

List up to three columns, the latter two being optional:
channel.PACKAGE_NAME  [PACKAGE_VERSION]  [PACKAGE_DESCRIPTION]

Mandatory arguments to long options are mandatory for short options too.

  -c, --color=WHEN            highlight search matches in color,
      --colour=WHEN             WHEN=
                                {always} always emit color codes
                                 never   never emit color codes
                                 auto    only emit color codes when stdout
                                         is a terminal
  -C, --columns=COLUMNS       choose columns to show,
                                COLUMNS=
                                {all}         show all columns
                                 none         show only PACKAGE_NAME
                                 version      also show PACKAGE_VERSION
                                 description  also show PACKAGE_DESCRIPTION
  -f, --flip=true|false       flip the order of sorting {false}
  -h, --help                  display a short help message and exit
  -l, --long-help             display a long help message and exit
  -r, --refresh               refresh package cache
  -s, --separator=true|false  separate match types with a newline {true}
  -v, --version               print \`nps\` version and exit"

LONG_HELP="
The \`nps --color=WHEN\` option follows the \`grep\` color option, except that
here the WHEN option is mandatory. Be aware that color codes can trip up
subsequent commands like \`grep\`, if they occur within a match string.

Matches are sorted by type. Show 'exact' matches first, then 'direct' matches,
and finally 'indirect' matches.
  exact     channel.SEARCH_TERM
  direct    channel.SEARCH_TERM-bar
  indirect  channel.foo-SEARCH_TERM-bar (or match other columns)

CONFIGURATION
\`nps\` can be configured with environment variables. You can set these in
the configuration file of your shell, e.g. .bashrc/.zshrc

NIX_PACKAGE_SEARCH_FLIP
  Flip the order of matches? By default most relevant matches appear first.
  Flipping the order makes them appear last and is thus easier to read with
  long output.
  value: true | false
  default: \"false\"

NIX_PACKAGE_SEARCH_FOLDER
  In which folder is the cache located?
  value: path
  default: \"${HOME}/.nix-package-search\"

NIX_PACKAGE_SEARCH_CACHE_FILE
  Name of the cache file
  value: filename
  default: \"nps.cache\"

NIX_PACKAGE_SEARCH_SHOW_PACKAGE_VERSION
  Show the PACKAGE_VERSION column
  value: true | false
  default: \"true\"

NIX_PACKAGE_SEARCH_SHOW_PACKAGE_DESCRIPTION
  Show the PACKAGE_DESCRIPTION column
  value: true | false
  default: \"true\"

NIX_PACKAGE_SEARCH_EXACT_COLOR
  Color of EXACT matches, match channel.PACKAGE_NAME
  value: black, blue, green, red, cyan, magenta, yellow, white
    or true colors, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
  default: \"magenta\"

NIX_PACKAGE_SEARCH_DIRECT_COLOR
  Color of DIRECT matches, match channel.PACKAGE_NAME-bar
  value: black, blue, green, red, cyan, magenta, yellow, white
    for advanced color options, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
  default: \"blue\"

NIX_PACKAGE_SEARCH_INDIRECT_COLOR
  Color of INDIRECT matches, match channel.foo-PACKAGE_NAME-bar
  value: black, blue, green, red, cyan, magenta, yellow, white
    for advanced color options, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
  default: \"green\"

NIX_PACKAGE_SEARCH_COLOR_MODE
  \`grep\` color mode, show search matches in color
  value:
    never   Never show color
    always  Always show color
    auto    Only show color if stdout is in terminal, suppress if e.g. piped
  default: auto

NIX_PACKAGE_SEARCH_PRINT_SEPARATOR
  Separate matches with a newline?
  value: true | false
  default: \"true\""

# Exit script on errors.
set -o errexit

# The return value of a pipeline is the value of the last (rightmost) command
# to exit with a non-zero status. Together with `errexit` it means that an
# error within a pipe will exit the script.
set -o pipefail

# Don't overwrite files with `>`.
set -o noclobber

# Fail if trying to use unbound variables.
set -o nounset

# Flip the order of matches?
# value: true | false
FLIP="${NIX_PACKAGE_SEARCH_FLIP:-false}"

# In which folder is the cache?
# value: path
SEARCH_FOLDER="${NIX_PACKAGE_SEARCH_FOLDER:-"${HOME}/.nix-package-search"}"

# Name of the cache file
# value: filename
CACHE_FILE="${NIX_PACKAGE_SEARCH_CACHE_FILE:-nps.cache}"

# Show the PACKAGE_VERSION column
# value: true | false
SHOW_PACKAGE_VERSION="${NIX_PACKAGE_SEARCH_SHOW_PACKAGE_VERSION:-true}"

# Show the PACKAGE_DESCRIPTION column
# value: true | false
SHOW_PACKAGE_DESCRIPTION="${NIX_PACKAGE_SEARCH_SHOW_PACKAGE_DESCRIPTION:-true}"

# Color of EXACT matches, match channel.PACKAGE_NAME
# value: black, blue, green, red, cyan, magenta, yellow, white,
#    or true colors, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
EXACT_COLOR="${NIX_PACKAGE_SEARCH_EXACT_COLOR:-magenta}"

# Color of DIRECT matches, match channel.PACKAGE_NAME-bar
# value: black, blue, green, red, cyan, magenta, yellow, white,
#    or true colors, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
DIRECT_COLOR="${NIX_PACKAGE_SEARCH_DIRECT_COLOR:-blue}"

# Color of INDIRECT matches, match channel.foo-PACKAGE_NAME-bar
# value: black, blue, green, red, cyan, magenta, yellow, white,
#    or true colors, see https://github.com/BurntSushi/ripgrep/blob/master/FAQ.md#how-do-i-configure-ripgreps-colors
INDIRECT_COLOR="${NIX_PACKAGE_SEARCH_INDIRECT_COLOR:-green}"

# `grep` color mode, show search matches in color
# value:
#   never   Never show color
#   always  Always show color
#   auto    Only show color if stdout is in terminal, suppress if e.g. piped
COLOR_MODE="${NIX_PACKAGE_SEARCH_COLOR_MODE:-auto}"

# Separate matches with a newline?
# value: true | false
PRINT_SEPARATOR="${NIX_PACKAGE_SEARCH_PRINT_SEPARATOR:-true}"

# Replace spaces in the description with this character for easier treatment
# of columns. Here we use the \x01 ASCII control character. It's rare enough
# that it would not appear in package descriptions (fingers crossed).
# value: ASCII character, but don't touch this one
SPACE_PLACEHOLDER="\x01"

# Don't refresh by default.
REFRESH=false

# Test if this version of `getopt` supports long options.
# We can cheat our way around `errexit` by using `if`. To access the
# actual exit status, we now need ${PIPESTATUS[0]}.
if getopt --test > /dev/null; then
    :
fi
if [[ ${PIPESTATUS[0]} -ne 4 ]]; then
    echo
    echo "Error: \`nps\` needs advanced \`getopt\` supporting long options."
    exit 1
fi

LONGOPTS=color:,colour:,columns:,flip:,help,long-help,refresh,separator:,version
OPTIONS=c:C:f:hlrs:v

# Pass arguments only via   -- "$@"   to separate them correctly.
if getopt --options=$OPTIONS --longoptions=$LONGOPTS \
           --name "$0" -- "$@" > /dev/null; then
   PARSED=$(getopt --options=$OPTIONS --longoptions=$LONGOPTS \
           --name "$0" -- "$@")
else
    # If, for example, the return value is 1, then getopt has complained
    # about wrong arguments to stdout
    echo
    echo "$HELP"
    exit 2
fi

# read getopt’s output this way to handle the quoting right:
eval set -- "$PARSED"

# Display help and exit if no command line arguments are given
if [ $# -eq 0 ]; then
    echo "$HELP"
    exit
fi

refresh() {
    # Create cache folder, if not exists
    mkdir -p "$SEARCH_FOLDER"

    echo "Querying and caching packages..."
    # First writing to a tmp file, so the cache is not destroyed
    # if the cache refreshing is interrupted.
    nix-env -qaP --description >| "/tmp/$CACHE_FILE"
    mv "/tmp/$CACHE_FILE" "$SEARCH_FOLDER/$CACHE_FILE"
    echo "Done"
}

version() {
    echo "nps (Nix Package Search) version $VERSION - (C) 2022 Ole Mussmann"
    echo "Released under the MIT license."
    exit 0
}

while true; do
    case "$1" in
        -c|--color|--colour)
            # Remove possible leading '=' sign in option.
            COLOR_MODE="${2#=}"
            case "$COLOR_MODE" in
                none|always|auto)
                    :
                    ;;
                *)
                    echo "Error: invalid color mode option $COLOR_MODE."
                    echo
                    echo "$HELP"
                    exit 1
                esac
            shift 2
            ;;
        -C|--columns)
            # Remove possible leading '=' sign in option.
            COLUMNS="${2#=}"
            shift 2
            case "$COLUMNS" in
                all)
                    SHOW_PACKAGE_VERSION="true"
                    SHOW_PACKAGE_DESCRIPTION="true"
                    ;;
                version)
                    SHOW_PACKAGE_VERSION="true"
                    SHOW_PACKAGE_DESCRIPTION="false"
                    ;;
                description)
                    SHOW_PACKAGE_VERSION="false"
                    SHOW_PACKAGE_DESCRIPTION="true"
                    ;;
                none)
                    SHOW_PACKAGE_VERSION="false"
                    SHOW_PACKAGE_DESCRIPTION="false"
                    ;;
                *)
                    echo "Error: invalid column option $COLUMNS."
                    echo
                    echo "$HELP"
                    exit 1
            esac
            ;;
        -f|--flip)
            # Remove possible leading '=' sign in option.
            FLIP="${2#=}"
            shift 2
            case "$FLIP" in
               true|false)
                   :
                   ;;
               *)
                   echo "Error: invalid flip option $FLIP."
                   exit 1
            esac
            ;;
        -h|--help)
            echo "$HELP"
            exit 0
            ;;
        -l|--long-help)
            echo "$HELP"
            echo "$LONG_HELP"
            exit 0
            ;;
        -r|--refresh)
            REFRESH="true"
            shift
            ;;
        -s|--separator)
            # Remove possible leading '=' sign in option.
            PRINT_SEPARATOR="${2#=}"
            shift 2
            case "$PRINT_SEPARATOR" in
               true|false)
                   :
                   ;;
               *)
                   echo "Error: invalid separator option $PRINT_SEPARATOR."
                   exit 1
            esac
            ;;
        -v|--version)
            version
            ;;
        --)
            shift
            break
            ;;
        *)
            echo "Programming error"
            exit 3
            ;;
    esac
done

# Handle non-option arguments.
if [[ $# -ne 1 ]]; then

    # Still run refresh, even if there is no search term.
    if [[ "$REFRESH" == "true" ]]; then
        refresh;
        exit 0
    fi

    echo "$0: A single search term is required."
    echo
    echo "$HELP"
    exit 4
else
    SEARCH_TERM=$1
fi

# Query packages and store them in the cache file if requested,
# or if the cache file does not exist yet.
if [ "$REFRESH" == "true" ] || ! [ -f "$SEARCH_FOLDER/$CACHE_FILE" ]; then
    refresh;
fi

VERSION_FILTER=
if [ "$SHOW_PACKAGE_VERSION" == "true" ]; then
    VERSION_FILTER="\"\t\" \$2 "
fi

DESCRIPTION_FILTER=
if [ "$SHOW_PACKAGE_DESCRIPTION" == "true" ]; then
    DESCRIPTION_FILTER="\"\t\" \$3"
fi

AWK_FILTER_STRING="{print \$1 $VERSION_FILTER $DESCRIPTION_FILTER}"

# rg      Find any matches in the cache file.
# sed     Replace spaces in the description column (3rd) with a placeholder.
# awk     Choose column to display.
# column  Align columns with minimum amount of spaces in between.
# sed     Put back spaces.
MATCHES=$(rg -N "$SEARCH_TERM" "$SEARCH_FOLDER/$CACHE_FILE" |
    sed "s/  */$SPACE_PLACEHOLDER/3g" |
    awk "$AWK_FILTER_STRING" |
    column -t |
    sed "s/$SPACE_PLACEHOLDER/ /g")

# Reverse line order, if FLIP is "true".
if [ "$FLIP" == "true" ]; then
    MATCHES="$(echo "$MATCHES" | tac)"
fi

# Separate matches
# Search for foo.SEARCH_TERM ending with an end-of-line char or whitespace.
# '|| true' prevents script exit if no matches are found.
EXACT=$(echo "$MATCHES" | rg "^[^.]*.$SEARCH_TERM($|\s)" || true)

# Search for foo.SEARCH_TERM-bar, but exclude the EXACT match.
DIRECT=$(echo "$MATCHES" | rg "^[^\.]*\.$SEARCH_TERM" |
         rg -v "^[^.]*.$SEARCH_TERM($|\s)" || true)

# All the rest, excluding the previous matches.
INDIRECT=$(echo "$MATCHES" | rg -v "^[^.]*.$SEARCH_TERM" || true)

if [ "$FLIP" == "true" ]; then
    # Flipped ordering
    if [ "$INDIRECT" ]; then
        # rg  Highlight INDIRECT matches in their own color, but don't throw
        # away lines without match. This works through the "and" operator `|`.
      echo "$INDIRECT" |
          rg --colors="match:fg:$INDIRECT_COLOR" --color="$COLOR_MODE" \
          "$SEARCH_TERM|"
    fi
    if [ "$DIRECT" ]; then
        # Print separator if requested and needed
        if [ "$INDIRECT" ] && [ "$PRINT_SEPARATOR" == "true" ]; then echo; fi

        # rg  Highlight DIRECT matches in their own color, but don't throw
        # away lines without match. This works through the "and" operator `|`.
        echo "$DIRECT" |
            rg --colors="match:fg:$DIRECT_COLOR" --color="$COLOR_MODE" \
            "$SEARCH_TERM|"
    fi
    if [ "$EXACT" ]; then
        # Print separator if requested and needed
        if [[ ( "$EXACT"  ||  "$DIRECT" ) && \
        "$PRINT_SEPARATOR" == "true" ]]; then
            echo;
        fi

        # rg  Highlight EXACT matches in their own color.
        echo "$EXACT" |
            rg --colors="match:fg:$EXACT_COLOR" --color="$COLOR_MODE" \
            "$SEARCH_TERM"
    fi
else
    # Normal ordering
    if [ "$EXACT" ]; then
        # rg  Highlight EXACT matches in their own color.
        echo "$EXACT" |
            rg --colors="match:fg:$EXACT_COLOR" --color="$COLOR_MODE" \
            "$SEARCH_TERM"
    fi
    if [ "$DIRECT" ]; then
        # Print separator if requested and needed
        if [ "$EXACT" ] && [ "$PRINT_SEPARATOR" == "true" ]; then echo; fi

        # rg  Highlight DIRECT matches in their own color, but don't throw
        # away lines without match. This works through the "and" operator `|`.
        echo "$DIRECT" |
            rg --colors="match:fg:$DIRECT_COLOR" --color="$COLOR_MODE" \
            "$SEARCH_TERM|"
    fi
    if [ "$INDIRECT" ]; then
        # Print separator if requested and needed
        if [[ ( "$EXACT"  ||  "$DIRECT" ) && "$PRINT_SEPARATOR" == "true" ]];
            then
            echo;
        fi

        # rg  Highlight INDIRECT matches in their own color, but don't throw
        # away lines without match. This works through the "and" operator `|`.
        echo "$INDIRECT" |
            rg --colors="match:fg:$INDIRECT_COLOR" --color="$COLOR_MODE" \
            "$SEARCH_TERM|"
    fi
fi