path: root/tldr

#!/bin/sh
# tldr client by Ray Lee, http://github.com/raylee/tldr
# tldr-sh-client version: 2021-12-18  spec: v1.5

# The following is written in a mildly functional style. It makes the code
# marginally slower, but more easily traceable, debuggable, and composable.
# And for me, at least, easier to reason about.

# In scripts "$@" often means 'all the arguments'. Below, it's also used
# for function indirection, executing the first parameter ($1) of $@ as a
# command, $2 onward as parameters, and wrapping it with other behaviors.

# Q: Why implement tldr in a plain POSIX shell script at all? It's nice to have
# a low-dependency way to see the pages, independent of local architecture. For
# some of us, POSIX sh is everywhere.

# silent executes its arguments as a command with args, silently.
silent() {
	>/dev/null 2>&1 "$@"
}

set -uf
# Some shells don't support setting pipefail, so try it silently and
# ignore any errors.
# silent set -o pipefail || true


main() {
	check_requirements

	# Set up the local platform as the default for pages.
	preferred_platform "$(local_platform)"

	# Some people like running this without saving any state.
	cache true
	if [ "${TLDR_CACHE:-}" = no ]; then
		cache false
		debug log Disabling cache
	fi

	Cmd=''
	bool listing
	while [ $# -gt 0 ]; do
		case $1 in
			-h|--help)
				usage > /dev/stderr
				exit 0
				;;
			-l|--list)
				listing true
				;;
			-L|--language)
				preferred_language "$2"
				shift
				;;
			-n|--no-cache)
				cache false
				;;
			-p|--platform)
				preferred_platform "$2"
				shift
				;;
			-u|--update)
				update_tldr_cache
				exit 0
				;;
			-v|--version)
				version_info
				exit 0
				;;
			-*)
				panic "Unrecognized option '$1'"
				;;
			*)
				# By the tldr client spec, the first argument
				# that does not start with a dash signals the
				# start of the command name. Spaces are
				# converted to dashes, and uppercase to lower.
				Cmd=$(printf %s "$*" | tr 'A-Z ' 'a-z-')
				break
				;;
		esac
		shift
	done

	# Download a copy of the pages locally if we don't have them already.
	if ! exists "$(page_cache)/index.json"; then
		update_tldr_cache
	fi

	if listing; then
		list_pages
		exit 0
	fi

	# # as an extension, this script can also parse arbitary md files.
	# if exists "$*"; then
	# 	display_tldr < "$*"
	# 	exit 0
	# fi

	if [ -z "$Cmd" ]; then
		# If stdin is a pipeline or a file, display it as a page.
		if ! interactive; then
			display_tldr "$(cat)"
		else
			usage > /dev/stderr
		fi
		exit 0
	fi

	tldr=$(get_page_md "$Cmd" 2>/dev/null)
	if [ -z "$tldr" ]; then
		panic "tldr page for command $Cmd not found"
	fi
	display_tldr "$tldr"
	echo

	# Freshen our local copy of the pages if they're out of date.
	if ! recent "$(page_cache)/index.json"; then
		update_tldr_cache
	fi
}


# panic exits the script with a final message to stderr.
panic() {
	>/dev/stderr printf "%s\n" "$@"
	exit 1
}

# installed tests the availability of command $1
installed() {
	silent command -v "$1"
}

# Check to see if we have the required external tools.
check_requirements() {
	# if sed is available we assume the smaller utils such as tr, cut,
	# sort, uniq, grep... are as well.
	installed sed    || panic 'tldr requires sed installed and available'
	installed unzip  || panic 'tldr requires unzip installed and available'
	installed curl   || installed wget || panic "tldr requires curl or wget installed and available"
}


# constants and read-only values

base_url() {
	echo https://raw.githubusercontent.com/tldr-pages/tldr/main/pages
}

upstream_pages() {
	echo https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr.zip
}

# cache_dir returns the base path for caching tldr data files.
cache_dir() {
	if [ -n "${XDG_CACHE_HOME:-}" ]; then
		echo "${XDG_CACHE_HOME}/tldr"
		return
	fi

	if [ -n "${HOME:-}" ]; then
		if [ -d "$HOME/.cache" ]; then
			echo "$HOME/.cache/tldr"
		else
			echo "$HOME/.tldr"
		fi
		return
	fi

	echo "/tmp"
}


# page_cache returns the base path for tldr markdown pages.
page_cache() {
	# if [ -z "${page_cache_path:-}" ]; then
	# 	page_cache_path="$(cache_dir)/page-source"
	# fi
	# echo "$page_cache_path"
	echo "$(cache_dir)/page-source"
}

# cache_days is how long to wait before refreshing our local copy.
cache_days() {
	echo 14
}

version_info() {
	grep '^# tldr-sh-client version: ' "$0" | cut -c3-
	echo "Check https://github.com/raylee/tldr-sh-client for updates."
}

# exists tests whether a file exists.
exists() {
	silent test -e "$1"
}

# recent tests whether "$1" exists and is more recent than $(cache_days) old.
recent() {
	exists "$(find "$1" -mtime "-$(cache_days)" 2>/dev/null)"
}

# basename acts like the command of the same name.
basename() {
	fn=${1##*/}
	if [ $# -eq 2 ]; then
		fn=${fn%"$2"}
	fi
	printf "%s\n" "$fn"
}

# extension returns the portion of the filename after the last ., if any.
extension() {
	echo "${1##*.}"
}

# lang_cc returns the ${language}_${country_code} portion of a locale.
# example: lang_cc en_DK.utf8 => en_DK
lang_cc() {
	for arg; do
		echo "${arg%.*}"
	done
}

Get() {
	if installed curl; then
		curl -sfL "$1"
	else
		wget -O - "$1"
	fi
}


# Calling `cache true` enables the cache, any other parameter disables it.
# Calling `cache` with no parameters changes the success code to true or false.
cache() {
	case $# in
		0) [ "${cache_bool:-}" = true ] ;;
		1) cache_bool=$1 ;;
	esac
}

get_page_md() {
	if cache; then
		cat "$(page_path "$1")"
	else
		Get "$(base_url)/{$(local_platform),common}/$1.md"
	fi
}

# Update the local cached copy of the tldr source pages.
update_tldr_cache() {
	if cache; then
		mkdir -p "$(page_cache)"
		Get "$(upstream_pages)" > "$(cache_dir)/tldr.zip"
		silent unzip -o -d "$(page_cache)" -u "$(cache_dir)/tldr.zip"
	fi
}

# # list the languages used in the current tldr zip archive.
# tldr_languages() {
# 	for path in "$(page_cache)"/pages.*; do
# 		extension "$path"
# 	done
# }

# Call preferred_platform with no arguments to get the current value, or pass
# values to set.
preferred_platform() {
	case $# in
		0) echo "$preferred_platform_name" ;;
		*) preferred_platform_name="$*" ;;
	esac
}

# platform_order returns a list of search paths, with one (harmless) duplicate.
platform_order() {
	echo "$(preferred_platform)" common linux osx windows sunos android
}

# Call preferred_language with no arguments to get the current value, or pass
# values to set.
preferred_language() {
	case $# in
		0) echo "${preferred_language_code:-}" ;;
		*) preferred_language_code="$*" ;;
	esac
}

# i18n_paths returns the prioritized list of language page paths to search.
i18n_paths() {
	if [ -n "$(preferred_language)" ]; then
		echo pages."$(preferred_language)"
		# by the spec, if a preferred language is set, English is no
		# longer a fallback.
		return
	fi

	# if $LANG is unset or empty, English is the fallback.
	if [ -z "${LANG:-}" ]; then
		debug log i18n: LANGless
		echo pages
		return
	fi

	# else the languages are ordered by $LANGUAGE, then $LANG, then English.
	for i in $(split : "${LANGUAGE:-}") $LANG; do
		case $i in
			C|POSIX) continue ;;
		esac
		i=$(lang_cc "$i")
		echo "pages.$i"
		debug log i18n: pages."$i"
	done
	echo pages
}

# split separates the arguments based on a single split character in $1.
split() {
	IFS="$1"
	shift
	# shellcheck disable=2048
	for x in $*; do
		echo "$x"
	done
}

# page_path takes a (normalized) page name in $1, and localizes it for language
# and platform. Platform pages are given preference over languages per the tldr
# client spec. The path to the first page found in that order is returned.
page_path() {
	for p in $(platform_order); do
		for l in $(i18n_paths); do
			if exists "$(page_cache)/$l/$p/$1.md"; then
				echo "$(page_cache)/$l/$p/$1.md"
				return
			fi
		done
	done
}

# term emits termcodes for style names passed as arguments.
term() {
	for arg; do
		# shellcheck disable=2086
		case $arg in
			reset)        tput sgr0 || tput me ;;
			bold)         tput bold || tput md ;;
			underline)<