Beautify function descriptions and more

improve function descriptions
- add a few
- give them a regular syntax

also:
- add a few TODOs and similar
- move a few TODOs into the respective global section
- rename pkgdepstr -> pkgstr
- rename (rpc) type -> qtype
- provide a local variable for all function parameters (mostly)
- fix typo (resolve_dependecies -> resolve_deps)

1 files changed, 109 insertions, 65 deletions

diff --git a/auria.sh b/auria.sh
index c2cb441..9775c3b 100755
--- a/auria.sh
+++ b/auria.sh
@@ -51,10 +51,15 @@
 #       lists
 # TODO: modify and use parse for info.
 # TODO: Be consistent in the usage of test / [.] / [[.]].
+# TODO: (ask:MARK 1) Handle "" and .
+# TODO: (info) parse properly (parse.c)
 # CONSIDER: (repo_deps) array vs. (newline separated string)
 # CONSIDER: (repo_deps) (space vs. newline) separated string
+# CONSIDER: (print_localver,print_repover) removal
+# CONSIDER: Use `local var=value' at beginning of functions.
 # Q?: When to set retstr to ''. 
 # Q?: Is aur_itype[] needed?
+# IDEA: (print_restriction) consider to use sed.
 #
 # NOTE: (jq) `// empty' converts null to empty, which becomes "".
 
@@ -120,6 +125,7 @@ typeset -A aur_pkgbase
 typeset -A aur_pkgver
 typeset -a aur_pkgorder		# properly ordered array of to be installed pkgs.
 
+# note: Only for debugging purposes.
 function reset_vars
 {
 	repo_deps=()
@@ -150,6 +156,7 @@ function main
 		search)
 			search "${@:2}";;
 		rpc)
+			# For debugging.
 			rpc "${@:2}";;
 		*)
 			error "Functionality ${1} not implemented."
@@ -182,12 +189,15 @@ function prepare
 	#CARCH="$(uname -m)"
 }
 
+# $1 package: name [. pkgver-comparator . version string]
+# interactive (<- install_full).
 function update
 {
 	install_full "$1" update
 }
 
-# $1 
+# $1 package: name [. pkgver-comparator . version string]
+# interactive (<- resolve_deps, present_files).
 function install_full
 {
 	local pkg pkgbase update a ver localver itype
@@ -208,7 +218,7 @@ function install_full
 
 	#inform "Fetching package information from AUR..."
 	inform "Resolving dependencies..."
-	resolve_dependencies "$pkg" "$itype"
+	resolve_deps "$pkg" "$itype"
 	# TODO: Make order.
 
 	# TODO: Do this for each dep (in proper order).
@@ -235,7 +245,8 @@ function install_full
 	makepkg "${makepkg_options[@]}" -i || return 2
 }
 
-# $1 
+# $1 package: name
+# interactive (<- get_pkgbase, present_files).
 function install_single
 {
 	local pkg pkgbase update a ver localver
@@ -280,9 +291,10 @@ function install_single
 	makepkg "${makepkg_options[@]}" -i || return 2
 }
 
-# $1 pkgname: string
-# $2 json file: string
-# returns on success [$retstr] result_id: int
+# $1 package: name
+# $2 json file: filename
+# $retstr result: numeric id {on success}
+# interactive.
 function get_pkgbase
 {
 	retstr=''
@@ -324,9 +336,9 @@ function get_pkgbase
 	fi
 }
 
-# $1 pkgbase: string
-# returns on success [$retstr] old_pkgbuild_exists: bool
-# note: Changes working directory to "${git_dir}/${pkgbase}" upon success.
+# $1 pkgbase: name
+# $retstr old_pkgbuild_exists: boolean {on success}
+# action: cd ${git_dir}/${pkgbase} {on success}
 function get_sources
 {
 	retstr=''
@@ -354,15 +366,18 @@ function get_sources
 	retstr=$old_pkgbuild_exists
 }
 
-# $1 old_pkgbuild_exists: bool
-# $2 pkgname: string
-# Requires $PWD = ${git_dir}/${pkgbase}
-# Requires ${tmp}/PKGBUILD if $old_pkbuild_exists
+# $1 old_pkgbuild_exists: boolean
+# $2 package: name
+# requires: $PWD == ${git_dir}/${pkgbase}
+# requires: ${tmp}/PKGBUILD (if $old_pkbuild_exists)
+# interactive.
 function present_files
 {
-	local pkgname="$2"
+	local old_pkgbuild_exists pkgname
+	old_pkgbuild_exists=$1
+	pkgname="$2"
 
-	if $1
+	if $old_pkgbuild_exists
 	then
 		if cmp "${tmp}/PKGBUILD" PKGBUILD
 		then
@@ -391,26 +406,27 @@ function present_files
 	done
 }
 
-# Any call for explicit packages must be made before any call for
-# non-explicit ones.
-# $1 package string: string[+ comparator, version string]
+# note: Any call for explicit packages must be made before any call for
+#       non-explicit ones.
+# $1 package: name [. pkgver-comparator . version string]
 # $2 installation type: (dep|explicit|update)
+# interactive (<- get_pkgbase).
 function resolve_deps
 {
-	local itype pkgdepstr pkg pkgbase pkgver rst rst_kind rst_ver existed new
+	local itype pkgstr pkg pkgbase pkgver rst rst_kind rst_ver existed new
 
-	pkgdepstr="$1"
+	pkgstr="$1"
 	itype="$2"
 
 	# Check for version restriction.
-	rst=( $(print_restriction "$pkgdepstr") )
+	rst=( $(print_restriction "$pkgstr") )
 	pkg="${rst[0]}"
 	rst_kind="${rst[1]}"
 	rst_ver="${rst[2]}"
 
 	# Search locally and in the repos first (for deps).
 	# This does also populate the $repo_deps array.
-	[[ "$itype" == dep ]] && depsearch_noaur "$pkg" "$pkgdepstr" && return 0
+	[[ "$itype" == dep ]] && depsearch_noaur "$pkg" "$pkgstr" && return 0
 
 	# Search the AUR.
 	if [[ -n "${aur_itype["$pkg"]}" ]]
@@ -424,7 +440,7 @@ function resolve_deps
 		then
 			if [[ "$itype" == dep ]]
 			then
-				error "Dependency ${pkgdepstr} could not be resolved."
+				error "Dependency ${pkgstr} could not be resolved."
 			else
 				error "[RPC] ${retstr}"
 			fi
@@ -442,7 +458,7 @@ function resolve_deps
 
 	if ! cmp_ver "$pkgver" "$rst_ver" "$rst_kind"
 	then
-		error "Dependency ${pkgdepstr} could not be resolved."
+		error "Dependency ${pkgstr} could not be resolved."
 		return 2
 	fi
 
@@ -466,30 +482,30 @@ function resolve_deps
 	fi
 }
 
-# $1 pkgname: string
-# $2 pkgdepstr: string [+ comparator + version string]
+# $1 package: name
+# $2 package: name [. pkgver-comparator . version string]
 function depsearch_noaur
 {
-	local pkg pkgdepstr
+	local pkg pkgstr
 	pkg="$1"
-	pkgdepstr="$2"
+	pkgstr="$2"
 
 	# In case of no dep restriction, look up in list first.
-	[[ "$pkg" == "$pkgdepstr" ]] \
-		&& match "$pkg" "${repo_deps[@]}" && return 0
+	[[ "$pkg" == "$pkgstr" ]] && match "$pkg" "${repo_deps[@]}" && return 0
 
-	qpacman -T "$pkgdepstr" && return 0
+	qpacman -T "$pkgstr" && return 0
 
-	qpacman -Sp "$pkgdepstr" \
+	qpacman -Sp "$pkgstr" \
 		&& { match "$pkg" "${repo_deps[@]}" || repo_deps+=("$pkg"); } \
 		&& return 0
 
 	return 1
 }
 
-# $1 ver1: version string
-# $2 ver2: version string
-# $3 comparator: (-gt|-lt|-ge|-le|-eq)
+# $1 version 1: [version string] {required if -n $comparator}
+# $2 version 2: [version string] {required if -n $comparator}
+# $3 comparator: [(-gt|-lt|-ge|-le|-eq)]
+# returns result: (0|1)
 function cmp_ver
 {
 	test -z "$3" && return 0
@@ -498,8 +514,9 @@ function cmp_ver
 	return $?
 }
 
-# $1 pkgname, possibly with restriction: string[(<|>|<=|>=|=)ver]
-# IDEA: consider to use sed instead.
+# $1 package: name [. pkgver-comparator . version string]
+# prints package and restriction: name + (-gt|-lt|-ge|-le|-eq)
+#                                 + version string
 function print_restriction
 {
 	local v
@@ -517,27 +534,29 @@ function print_restriction
 	printf "%s\n" "$1"
 }
 
-# $1 pkgname: string
-# TODO: needed?
-# TODO: case pkg is only provided.
+# $1 package: name
+# prints local version: version string
 function print_localver
 {
 	pacman -R --print-format "%v" "$1"
 }
 
-# $1 pkgname: string
+# $1 package: name
+# prints repository version: version string
 function print_repover
 {
 	pacman -S --print-format "%v" "$1"
 }
 
-# $1 pkgname: string
+# $1 package: name
+# returns guess: (0|1)
 function guess_vcs
 {
 	[[ "$1" =~ -(git|svn|hg|bzr|cvs|fossil|darcs|rcs|arch|mtn)$ ]]
 }
 
 function update_all
+# interactive (<- update).
 {
 	for pkg in "$(pacman -Qmq)"
 	do
@@ -570,26 +589,26 @@ function error
 	printf "${nbred}error:${nocolor} %s\n" "$*" >&2
 }
 
-# $1 type: (info|search(:(name|name-desc|maintainer)),
-# $2 output-file: string
-# $3 sound: [quiet|loud]
-# ${@:4} args: (string)*
-# returns if ! $print_error [$retstr] error: [string]
+# $1 query type: (info | search:(name|name-desc|maintainer)),
+# $2 output file: filename
+# $3 sound: (quiet|loud)
+# ${@:4} args: (string)+
+# $retstr error: string {on failure if $quiet}
 function rpc
 {
 	retstr=''
 	# According to the website (/rpc/), arg should be subsituted by arg[]
-	# if type is info.
+	# if the query type is info.
 
-	local type search_by quiet args
-	type=${1%:*}
+	local qtype search_by quiet args
+	qtype=${1%:*}
 	search_by=${1#*:}
 	file="$2"
 	test "$3" = quiet && quiet=true || quiet=false
 	args=( "${@:4}" )
 
 	local -a cargs
-	if [[ "$type" == info ]]
+	if [[ "$qtype" == info ]]
 	then
 		for arg in "${args[@]}"
 		do
@@ -616,6 +635,8 @@ function rpc
 	fi
 }
 
+# $* match conditions: (string)+
+# prints search results: formatted string
 function search
 {
 	rpc search:name-desc "${tmp}/json" loud "$*" || return $?
@@ -625,6 +646,8 @@ function search
 		| parse 4 0 $($color && echo color)
 }
 
+# $* packages: (string)+
+# prints info results: formatted string
 function info
 {
 	rpc info "${tmp}/json" loud "$@" || return $?
@@ -654,28 +677,36 @@ function info
 		"${tmp}/json"
 }
 
-# $1 default: y/n/x, $2 question: string
+# $1 default answer: (y|n|x)
+# $2 question: string
+# returns yes / no: (0|1)
+# interactive.
 function ask
 {
 	# -l auto-converts everything to lower case.
 	local -l default
+	local question
 	default=$1
+	question="$2"
 
 	while true
 	do
 		if [[ "$default" == "y" ]]
 		then
-			printf "${nbblue}::${nocolor} ${bwhite}%s [Y/n]?${nocolor} " "$2"
+			printf "${nbblue}::${nocolor} ${bwhite}%s [Y/n]?${nocolor} " \
+				"$question"
 		elif [[ "$default" == "n" ]]
 		then
-			printf "${nbblue}::${nocolor} ${bwhite}%s [y/N]?${nocolor} " "$2"
+			printf "${nbblue}::${nocolor} ${bwhite}%s [y/N]?${nocolor} " \
+				"$question"
 		else
-			printf "${nbblue}::${nocolor} ${bwhite}%s [y/n]?${nocolor} " "$2"
+			printf "${nbblue}::${nocolor} ${bwhite}%s [y/n]?${nocolor} " \
+				"$question"
 			default="x"
 		fi
 
 		local -l reply
-		read reply
+		read reply			# MARK 1
 
 		if [[ "$reply" =~ ^y(es)?$ ]]
 		then
@@ -689,33 +720,46 @@ function ask
 		elif [[ "$default" == "y" ]]
 		then
 			return 0
-		else # "$default" = "n"
+		else # "$default" == "n"
 			return 1
 		fi
 	done
 }
 
-# $1 default answer: string, $2: options: string, $3 question: string
-# returns answer [$retstr]: string
+# $1 default answer: string
+# $2 options: string
+# $3 question: string
+# $retstr answer: string
+# interactive.
 function ask_general
 {
-	if test -z "$2"
+	retstr=''
+	local default options question
+	default="$1"
+	options="$2"
+	question="$3"
+
+	if test -z "$opts"
 	then
-		if test -z "$1"
+		if test -z "$default"
 		then
-			set "$1" "..." "$3"
+			options='...'
 		else
-			set "$1" "${1}/..." "$3"
+			options="${default}/..."
 		fi
 	fi
 
 	local reply
-	printf "${nbblue}::${nocolor} ${bwhite}%s [%s]?${nocolor} " "$3" "$2"
+	printf "${nbblue}::${nocolor} ${bwhite}%s [%s]?${nocolor} " "$question" \
+		"$options"
 	read reply
 
-	test -n "$reply" && retstr="$reply" || retstr="$1"
+	test -n "$reply" && retstr="$reply" || retstr="$default"
 }
 
+# $1 needle: string
+# ${@:2} haystack: (string)*
+# returns yes / no: (0|1)
 function match
 {
 	printf "%s\n" "${@:2}" | grep -q "^${1}$"