docs: Fix docs to use 'bpm-load'

Eventually, 'package-path', will be removed for custom output string
parsing for the 'list' subcommand

Author: hyperupcall

README.md

@@ -60,15 +60,26 @@ Why not use `bpkg` or `Basher`? Because `hyperupcall/bpm`...
 
 I forked Basher because it had an excellent test suite and its behavior for installing packages made more sense to me, compared to `bpkg`
 
+Prior art
+
 | Software        | Deps | Versions | Locations          | Completions |
 |---------------- |------|----------|--------------------| ----------- |
 | hyperupcall/bpm | Yes  | Yes      | Global, User, Repo | Yes         |
 | [basher]        | Yes  | No       | Global, User       | Yes         |
 | [bpkg]          | Yes  | Yes      | Global, User, Repo | Yes         |
 | [bpm-rocks/bpm] | Yes  | No       | Global, User, Repo | No          |
 | [Themis]        | Yes  | Yes      | Global, User, Repo | No          |
-
+| [xsh-lib/core]  | ?    | ?        |                    |             |
+| [shpkg]         |      |          |                    |             |
+| [jean]          |      |          |                    |             |
+| [sparrow]       |      |          |                    |             |
+| [tarp]          |      |          |                    |             |
 [basher]: https://github.com/basherpm/basher
 [bpkg]: https://github.com/bpkg/bpkg
 [bpm-rocks/bpm]: https://github.com/bpm-rocks/bpm/
 [Themis]: https://github.com/ByCh4n-Group/themis
+[xsh]: https://github.com/alexzhangs/xsh
+[shpkg]: https://github.com/shpkg/shpkg
+[jean]: https://github.com/ziyaddin/jean
+[sparrow]: https://github.com/melezhik/sparrow
+[tarp]: https://code.google.com/archive/p/tarp-package-manager/

docs/getting-started.md

@@ -73,14 +73,15 @@ But it doesn't work - this is standard behavior. When looking for binaries, bpm
 The authors of `z` did not mark the file as executable because they did not intend for you to execute the file - you are supposed to `source` it. This is why the `bpm-load` command exists:
 
 ```sh
-$ bpm --global package-path rupa/z
-/home/username/bpm/cellar/packages/rupa/z
+$ bpm-load --global --dry rupa/z z.sh
+bpm-load: Would source file '/home/edwin/data/bpm/cellar/packages/github.com/rupa/z/z.sh'
 ```
 
-Now, use the `package-path` to source `z.sh`. Note that `z.sh` only supports either Bash or Zsh, so you need to currently be in one of those shells for this to work
+Now, use the `bpm-load` to source `z.sh`. Note that `z.sh` only supports either Bash or Zsh, so you need to currently be in one of those shells for this to work. We `source 'bpm-source` because the PATH contains a file called `bpm-source`, which contains the `bpm-source` function that we use
 
 ```sh
-$ source "$(bpm --global package-path rupa/z)/z.sh"
+$ source 'bpm-source'
+$ bpm-source --global 'rupa/z' 'z.sh'
 $ z
 common:    /tmp/tmp.MBF063fdlK/completions
 29988      /tmp/tmp.MBF063fdlK/completions
@@ -114,6 +115,6 @@ $ bpm --global remove \
 $ bpm --global list
 ```
 
-Note that we specified the SSH URL and the HTTPS URL when removing. You can specify the package this way with all commands, including the `add`, `package-path`, and `upgrade` commands
+Note that we specified the SSH URL and the HTTPS URL when removing. You can specify the package this way with all commands, including the `add`, `remove`, and `upgrade` commands
 
 And you are done! To learn more, see [Recepies](./.recepies.md), [Reference](./reference.md), or [Tips](./tips.md)

pkg/lib/cmd/bpm-load.sh

@@ -25,6 +25,32 @@ bpm-load() {
 				__bpm_flag_dry='yes'
 				shift
 				;;
+			--help|-h)
+				cat <<-"EOF"
+				bpm-load
+
+				Usage:
+				  bpm-load <flags> <package> [file]
+
+				Flags:
+				  --global
+				    Use packages installed globally, rather than local packages
+
+				  --dry
+				    Only print what would have been sourced
+
+				  --help
+				    Print help menu
+
+				Example:
+				  bpm-load --global 'github.com/rupa/z' 'z.sh'
+				EOF
+				return
+				;;
+			-*)
+				printf '%s\n' "bpm-load: Error: Flag '$arg' not recognized"
+				return 1
+				;;
 		esac
 	done
 
@@ -79,12 +105,19 @@ bpm-load() {
 		__bpm_cellar="${BPM_CELLAR:-"${XDG_DATA_HOME:-$HOME/.local/share}/bpm/cellar"}"
 	else
 		if ! __bpm_cellar="$(util.get_project_root_dir)/bpm_packages"; then
-			printf '%s\n' "bpm-load: Error: Unexpected error calling function 'util.get_project_root_dir' with PWD '$PWD'"
+			printf '%s\n' "bpm-load: Error: Unexpected error calling function 'util.get_project_root_dir' with \$PWD '$PWD'"
 			__bpm_bpm_load_restore_options
 			return 4
 		fi
 	fi
 
+	# Ensure package is actually installed
+	if [ ! -d "$__bpm_cellar/packages/$__bpm_site/$__bpm_package" ]; then
+		printf '%s\n' "bpm-load: Error: Package '$__bpm_site/$__bpm_package' is not installed. Does the '--global' flag apply?"
+		__bpm_bpm_load_restore_options
+		return 3
+	fi
+
 	# Source file, behavior depending on whether it was specifed
 	if [ -n "$__bpm_file" ]; then
 		local __bpm_full_path="$__bpm_cellar/packages/$__bpm_site/$__bpm_package/$__bpm_file"
@@ -117,6 +150,7 @@ bpm-load() {
 		for __bpm_file in 'load.bash'; do
 			local __bpm_full_path="$__bpm_cellar/packages/$__bpm_site/$__bpm_package/$__bpm_file"
 
+			echo "$__bpm_full_path"
 			if [ -f "$__bpm_full_path" ]; then
 				__bpm_file_was_sourced='yes'
 
@@ -136,7 +170,7 @@ bpm-load() {
 		done
 
 		if [ "$__bpm_file_was_sourced" = 'no' ]; then
-			printf '%s\n' "bpm-load: Error: Could not automatically find package file to source"
+			printf '%s\n' "bpm-load: Error: Could not automatically find package file to source. Did you mean to pass the file to source as the second argument?"
 			__bpm_bpm_load_restore_options
 			return 3
 		fi
@@ -160,3 +194,9 @@ __bpm_bpm_load_restore_options() {
 		shopt -u extglob
 	fi
 }
+
+# @description Internal functions might call 'die', so this prevents 'bash: die: command not found' errors,
+# but still allows the error be exposed at the callsite
+die() {
+	return 1
+}