Merge pull request #633 from ChuckDaniels87/documentation

Add file and function documentation
rmarquis · Apr 12, 2017 · 9035f37 · 9035f37
2 parents 433c870 + b920ea1
commit 9035f37
Show file tree

Hide file tree

Showing 9 changed files with 475 additions and 129 deletions.
diff --git a/libpacaur/info.sh → libpacaur/aur.sh b/libpacaur/info.sh → libpacaur/aur.sh
@@ -1,10 +1,68 @@
+#!/bin/bash
+#
+#   aur.sh - functions related to AUR operations
+#
+
+##
+# Upgrade needed AUR packages.
+#
+# usage: UpgradeAur()
+##
+UpgradeAur() {
+    local foreignpkgs allaurpkgs allaurpkgsAver allaurpkgsQver aurforeignpkgs i json
+    # global aurpkgs
+    Note "i" $"${colorW}Starting AUR upgrade...${reset}"
+
+    # selective upgrade switch
+    if [[ $selective && -n ${pkgs[@]} ]]; then
+        aurpkgs+=(${pkgs[@]})
+    else
+        foreignpkgs=($($pacmanbin -Qmq))
+        SetJson ${foreignpkgs[@]}
+        allaurpkgs=($(GetJson "var" "$json" "Name"))
+        allaurpkgsAver=($(GetJson "var" "$json" "Version"))
+        allaurpkgsQver=($(expac -Q '%v' ${allaurpkgs[@]}))
+        for i in "${!allaurpkgs[@]}"; do
+            [[ $(vercmp "${allaurpkgsAver[$i]}" "${allaurpkgsQver[$i]}") -gt 0 ]] && aurpkgs+=(${allaurpkgs[$i]});
+        done
+    fi
+
+    # foreign packages check
+    aurforeignpkgs=($(grep -xvf <(printf '%s\n' "${allaurpkgs[@]}") <(printf '%s\n' "${foreignpkgs[@]}")))
+    for i in "${aurforeignpkgs[@]}"; do
+        Note "w" $"${colorW}$i${reset} is ${colorY}not present${reset} in AUR -- skipping"
+    done
+
+    # add devel packages
+    if [[ $devel ]]; then
+        for i in "${allaurpkgs[@]}"; do
+            [[ -n "$(grep -E "\-(cvs|svn|git|hg|bzr|darcs|nightly.*)$" <<< $i)" ]] && aurpkgs+=($i)
+        done
+    fi
+
+    # avoid possible duplicate
+    aurpkgs=($(tr ' ' '\n' <<< ${aurpkgs[@]} | sort -u))
+
+    NothingToDo ${aurpkgs[@]}
+}
+
+##
+# Search packages in the AUR
+#
+# usage: SearchAur( $packages )
+##
 SearchAur() {
     if [[ -z "$(grep -E "\-\-[r]?sort" <<< ${coweropts[@]})" ]]; then
         [[ $sortorder = descending ]] && coweropts+=("--rsort=$sortby") || coweropts+=("--sort=$sortby");
     fi
     cower ${coweropts[@]} -- $@
 }
 
+##
+# Fetch and print formatted information of AUR packages
+#
+# usage: InfoAur( $aur_packages )
+##
 InfoAur() {
     local aurinfopkgs info infolabel maxlength linfo lbytes
 
@@ -88,3 +146,4 @@ InfoAur() {
         echo
     done
 }
+# vim:set ts=4 sw=2 et:
diff --git a/libpacaur/cache.sh b/libpacaur/cache.sh
@@ -1,3 +1,14 @@
+#!/bin/bash
+#
+#   cache.sh - functions related to cache management
+#
+
+##
+# Clean AUR cache, including sources and clone directories. This function let
+# users select what content is deleted.
+#
+# usage: CleanCache( $packages )
+##
 CleanCache() {
     if [[ $SRCDEST ]]; then
         [[ $count -eq 1 ]] && printf "\n%s\n %s\n" $"Sources to keep:" $"All development packages sources"
@@ -43,3 +54,4 @@ CleanCache() {
     fi
     exit 0
 }
+# vim:set ts=4 sw=2 et:
diff --git a/libpacaur/checks.sh b/libpacaur/checks.sh
@@ -1,3 +1,13 @@
+#!/bin/bash
+#
+#   checks.sh - functions related to checking operations
+#
+
+##
+# Check packages that are ignored on upgrade or installation.
+#
+# usage: IgnoreChecks()
+##
 IgnoreChecks() {
     local checkaurpkgs checkaurpkgsAver checkaurpkgsQver i json
     # global aurpkgs rmaurpkgs
@@ -47,6 +57,49 @@ IgnoreChecks() {
     NothingToDo ${aurpkgs[@]}
 }
 
+##
+# Check ignored packages needed as dependencies.
+#
+# usage: IgnoreDepsChecks()
+##
+IgnoreDepsChecks() {
+    local i
+    # global ignoredpkgs aurpkgs aurdepspkgs rmaurpkgs deps repodepspkgs
+    [[ -z "${ignoredpkgs[@]}" ]] && return
+
+    # add checked targets
+    deps=(${aurpkgs[@]})
+
+    # check dependencies
+    for i in "${repodepspkgs[@]}"; do
+        if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
+            Note "w" $"${colorW}$i${reset}: ignoring package upgrade"
+            Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
+        fi
+    done
+    for i in "${aurdepspkgs[@]}"; do
+        # skip already checked dependencies
+        [[ " ${aurpkgs[@]} " =~ " $i " ]] && continue
+        [[ " ${rmaurpkgs[@]} " =~ " $i " ]] && Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
+
+        if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
+            if [[ ! $noconfirm ]]; then
+                if ! Proceed "y" $"$i dependency is in IgnorePkg/IgnoreGroup. Install anyway?"; then
+                    Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
+                fi
+            else
+                Note "w" $"${colorW}$i${reset}: ignoring package upgrade"
+                Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
+            fi
+        fi
+        deps+=($i)
+    done
+}
+##
+# Check providers of packages and dependencies.
+#
+# usage: ProviderChecks()
+##
 ProviderChecks() {
     local allproviders providersdeps providers repodepspkgsprovided providerspkgs provided nb providersnb rmproviderpkgs providerpkgsrm
     # global repodepspkgs repoprovidersconflictingpkgs repodepsSver repodepsSrepo repodepsQver
@@ -139,6 +192,11 @@ ProviderChecks() {
     fi
 }
 
+##
+# Check conflicting packages and dependencies.
+#
+# usage: ConflictChecks()
+##
 ConflictChecks() {
     local allQprovides allQconflicts Aprovides Aconflicts aurconflicts aurAconflicts Qrequires i j k
     local repodepsprovides repodepsconflicts checkedrepodepsconflicts repodepsconflictsname repodepsconflictsver localver repoconflictingpkgs
@@ -277,6 +335,11 @@ ConflictChecks() {
     done
 }
 
+##
+# Check and notify which packages are marked to be reinstalled.
+#
+# usage: ReinstallChecks()
+##
 ReinstallChecks() {
     local i depsAtmp
     # global aurpkgs aurdepspkgs deps aurconflictingpkgs depsAname depsQver depsAver depsAood depsAmain
@@ -302,6 +365,11 @@ ReinstallChecks() {
     NothingToDo ${deps[@]}
 }
 
+##
+# Check out of date packages.
+#
+# usage: OutofdateChecks()
+##
 OutofdateChecks() {
     local i
     # global depsAname depsAver depsAood
@@ -310,6 +378,11 @@ OutofdateChecks() {
     done
 }
 
+##
+# Check orphaned packages.
+#
+# usage: OrphanChecks()
+##
 OrphanChecks() {
     local i
     # global depsAname depsAver depsAmain
@@ -318,6 +391,11 @@ OrphanChecks() {
     done
 }
 
+##
+# Check which packages need to be updated.
+#
+# usage: CheckUpdates( $packages )
+##
 CheckUpdates() {
     local foreignpkgs foreignpkgsbase repopkgsQood repopkgsQver repopkgsSver repopkgsSrepo repopkgsQgrp repopkgsQignore
     local aurpkgsQood aurpkgsAname aurpkgsAver aurpkgsQver aurpkgsQignore i json
@@ -444,6 +522,11 @@ CheckUpdates() {
     fi
 }
 
+##
+# Check that all dependencies required by the packages are satisfied.
+#
+# usage: CheckRequires( $packages )
+##
 CheckRequires() {
     local Qrequires
     Qrequires=($(expac -Q '%n %D' | grep -E " $@[\+]*[^a-zA-Z0-9_@\.\+-]+" | awk '{print $1}' | tr '\n' ' '))
@@ -452,3 +535,4 @@ CheckRequires() {
         Note "e" $"${Qrequires[@]}: requires $@"
     fi
 }
+# vim:set ts=4 sw=2 et:
diff --git a/libpacaur/deps.sh b/libpacaur/deps.sh
@@ -1,3 +1,14 @@
+#!/bin/bash
+#
+#   deps.sh - functions related to dependency resolution
+#
+
+##
+# Dependency solver that wraps both pacman and AUR packages dependency
+# resolution.
+#
+# usage: DepsSolver()
+##
 DepsSolver() {
     local i aurpkgsname aurpkgsver aurpkgsaurver aurpkgsconflicts
     # global aurpkgs aurpkgsnover aurpkgsproviders aurdeps deps json errdeps errdepsnover foreignpkgs repodeps depsAname depsAver depsAood depsQver
@@ -93,6 +104,11 @@ DepsSolver() {
     FindDepsRepo ${repodeps[@]}
 }
 
+##
+# Find dependencies of AUR packages.
+#
+# usage: FindDepsAur( $aur_packages )
+##
 FindDepsAur() {
     local depspkgs depspkgstmp depspkgsaurtmp repodepstmp builtpkg vcsdepspkgs assumedepspkgs
     local aurversionpkgs aurversionpkgsname aurversionpkgsver aurversionpkgsaurver i j json
@@ -258,6 +274,11 @@ FindDepsAur() {
     fi
 }
 
+##
+# Sort dependencies to ensure correct resolution order.
+#
+# usage: SortDepsAur( $aur_packages )
+##
 SortDepsAur() {
     local i j sortaurpkgs sortdepspkgs sortdepspkgsaur
     # global checkedsortdepspkgsaur allcheckedsortdepspkgsaur json errdepsnover
@@ -307,6 +328,11 @@ SortDepsAur() {
     fi
 }
 
+##
+# Find dependency errors in AUR packages.
+#
+# usage: FindDepsAurError( $sorted_dependencies )
+##
 FindDepsAurError() {
     local i nexterrdep nextallerrdeps
     # global errdepsnover errdepslist tsorterrdeps currenterrdep
@@ -351,6 +377,11 @@ FindDepsAurError() {
     fi
 }
 
+##
+# Find dependencies of repository packages.
+#
+# usage: FindDepsRepo( $repo_packages )
+##
 FindDepsRepo() {
     local allrepopkgs providersrepopkgs providersrepopkgsrm i j
     # global repodeps
@@ -379,37 +410,4 @@ FindDepsRepo() {
 
     repodepspkgs=($($pacmanbin -T ${allrepopkgs[@]} | sort -u))
 }
-
-IgnoreDepsChecks() {
-    local i
-    # global ignoredpkgs aurpkgs aurdepspkgs rmaurpkgs deps repodepspkgs
-    [[ -z "${ignoredpkgs[@]}" ]] && return
-
-    # add checked targets
-    deps=(${aurpkgs[@]})
-
-    # check dependencies
-    for i in "${repodepspkgs[@]}"; do
-        if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
-            Note "w" $"${colorW}$i${reset}: ignoring package upgrade"
-            Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
-        fi
-    done
-    for i in "${aurdepspkgs[@]}"; do
-        # skip already checked dependencies
-        [[ " ${aurpkgs[@]} " =~ " $i " ]] && continue
-        [[ " ${rmaurpkgs[@]} " =~ " $i " ]] && Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
-
-        if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
-            if [[ ! $noconfirm ]]; then
-                if ! Proceed "y" $"$i dependency is in IgnorePkg/IgnoreGroup. Install anyway?"; then
-                    Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
-                fi
-            else
-                Note "w" $"${colorW}$i${reset}: ignoring package upgrade"
-                Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
-            fi
-        fi
-        deps+=($i)
-    done
-}
+# vim:set ts=4 sw=2 et: