docs: Overhaul docs

Author: hyperupcall

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+	"files.watcherExclude": {
+		"**/target": true
+	}
+}

docs/how-to/local-projects.md

@@ -1,84 +1,89 @@
 # Local Projects
 
-TODO: WARNING: This is out of date
+Similar to `cargo`, `yarn` etc., Basalt allows for the installation of packages on a per-project basis. This page details how to do it with Basalt
 
-Similar to `npm`, `carto`, etc. `basalt` allows for the installation of packages on a per-project basis. Use `basalt.toml` for this
+First, create a project directory
 
 ```sh
 mkdir 'my-project' && cd 'my-project'
-
-# Creating a 'basalt.toml' is required so basalt knows where
-# the root of the project is
-touch 'basalt.toml'
 ```
 
-Let's take a look at the installed packages
+Now, initialize a new project. We'll be passing in `--full`; if you want a more minimalist template, pass `--bare` instead
 
 ```sh
-$ basalt list
-Info: Operating in context of local basalt.toml
+$ basalt init --full
+       Info Cloned github.com/hyperupcall/template-bash
 ```
 
-So far, none are installed. Let's install [bash-args](https://github.com/hyperupcall/bash-args). To do this, modify `dependencies` in your `basalt.toml`
+Naturally, the most important part of Basalt packages is the `basalt.toml` file
 
 ```toml
-# basalt.toml
-dependencies = [ "hyperupcall/bash-args" ]
+[package]
+name = 'fox-track'
+slug = 'fox_track'
+version = '0.1.0'
+authors = ['Edwin Kofler <edwin@kofler.dev>']
+description = 'A template to get started writing Bash applications and projects'
+
+[run]
+dependencies = ['https://github.com/hyperupcall/bats-common-utils.git@v3.0.0']
+sourceDirs = ['pkg/lib/public', 'pkg/lib']
+builtinDirs = []
+binDirs = ['pkg/bin']
+completionDirs = ['completions']
+manDirs = []
+
+[run.shellEnvironment]
+
+[run.setOptions]
+
+[run.shoptOptions]
 ```
 
-Now, install it
+In short, `name` is the pretty name for the package. Often, it has the same name as the repository. `slug` is the string used to prefix *all of* your functions when you want your package to be consumed as a library. Lastly, `sourceDirs` are all the directories containing shell files you wish to source. Note that `pkg/lib/cmd` is *not* added since it contains files that are entrypoints for new Bash processes
 
-```sh
-$ basalt add --all
-Info: Operating in context of local basalt.toml
-Info: Adding all dependencies
-Info: Adding 'hyperupcall/bash-args'
-  -> Cloning Git repository
-  -> Symlinking bin files
-```
+A detailed description for each key can be found at [`reference/basalt_toml`](./docs/reference/basalt_toml.md)
 
-It now shows up in the `list` subcommand
+To execute this program, simply run
 
 ```sh
-$ basalt list
-Info: Operating in context of local basalt.toml
-github.com/hyperupcall/bash-args
-  Branch: main
-  Revision: 2087e87
-  State: Up to date
-```
+$ basalt run fox-track --help
+fox-track: A fox tracking sample application
 
-You'll notice a `.basalt` directory has been created. Since the project is now installed, let's use it
+Commands:
+  show
+    Shows the current fox count
 
-Create a `script.sh` file
+  set <number>
+    Sets the current fox count
 
-```sh
-#!/usr/bin/env bash
+  add [number]
+    Adds a number to the current fox count. If number is not specified, it defaults to 1
 
-# @file script.sh
-# @brief Demonstration of the bash-args library
+  remove [number]
+    Adds a number to the current fox count. If number is not specified, it defaults to 1
 
-# Append to the PATH so we have access to `bash-args` in the PATH
-PATH="$PWD/.basalt/bin:$PATH"
+Flags:
+  --help
+    Shows the help menu
+```
 
-# Declare an associative array for storing the argument flags
-declare -A args=()
+This is similar to running `./pkg/bin/fox-track` directly, but using `basalt run` has another benefit: Basalt will look for commands of the specified name not just for the current project, but for all subdependencies as well
 
-# 'bash-args' requires that we use `source`, so it can
-# set fields in the 'args' associative array
-source bash-args parse "$@" <<-"EOF"
-@flag [port.p] {3000} - The port to open on
-EOF
+If you wish to add a dependency to the project, use the `add` subcommand
 
-printf '%s\n' "Using port '${args[port]}'"
+```sh
+$ basalt add 'hyperupcall/bats-common-utils'
+ Downloaded github.com/hyperupcall/bats-common-utils@v3.0.0
+  Extracted github.com/hyperupcall/bats-common-utils@v3.0.0
+Transformed github.com/hyperupcall/bats-common-utils@v3.0.0
 ```
 
-Cool, now let's try it
+Basalt will automatically find and download the version corresponding to the _latest GitHub release_. If there are no GitHub releases, it will use the latest commit. In this case, `v3.0.0` was the latest GitHub release
+
+You can view the dependencies by looking in `basalt.toml` or running
 
 ```sh
-$ chmod +x './script.sh'
-$ ./script.sh
-Using port '3000'
-$ ./script.sh --port 4000
-Using port '4000'
+$ basalt list
+https://github.com/hyperupcall/bats-common-utils.git@v3.0.0
 ```

docs/internals/history.md

@@ -6,11 +6,12 @@ After contributing a few PR's to Basher, I decided to fork the project, calling
 
 I essentially rewrote most of the codebase, authoring an additional ~100 tests. Some of the features at this point included
 
-- Support for a `bpm.toml` file (in addition to backwards-compatible `package.sh` support)
-- Substantiallly better help output
+- Support for a `bpm.toml` file (in addition to backwards-compatible support for `package.sh`)
+- Substantially better help output
 - Completion scripts
 - Support for installing many more repositories
 - Support for installing transitive dependencies
+- Improved support for installing different branches / versions
 - Over 250+ tests
 
 Although the code was heavily tested, I didn't really like _how_ packages were installed. It was inefficient and had the potential for bugs. When I had this realization, I decided to essentially start from scratch again, coding the design that is implemented today. I threw out the 250+ custom tests, implementations of commands, and nearly everything with the exception of a few low-level parsing functions. Contemporaneously, I renamed the project to `basalt`, and worked on the from-scratch implementation in a branch called `wip` until it was subsequently merged into `main`

docs/internals/motivation.md

@@ -2,11 +2,13 @@
 
 A mechanism to facilitate composability within the Bash ecosystem, á la a package manager
 
-The general idea isn't new; there exist two prominent package managers (`bpkg` and `Basher`) along with a slew of other highly prolific Bash/shell projects (`oh-my-zsh`, `bash-it`, `bash-oo-framework`) that aim to solve similar problems. How is Basalt different?
+The general idea isn't new; there are many similar projects, but Basalt fills a unique void
 
-1. `oh-my-zsh`, `bash-it`, and friends are more geared towards reusability (not composability) in the context of shell initialization
-2. `bash-oo-framework` contains a lot of useful functionality, but as the name implies, it must be used as a framework rather than a library; this doesn't mame it very composable. Furthermore, the project itself recommends directly copying and pasting code from the repository as a usage pattern, which is highly laborious and frictious
-3. `bpkg` and `Basher` are two projects that fit the criteria, but have some disadvantages in my opinion
+- It is not meant to be a replacement for `oh-my-zsh`, `bash-it`, etc. The aforementioned are used only in the context of shell initialization and are more geared towards reusability (not composability)
+
+- It is unlike `bash-oo-framework` in that it facilitates the creation of _packages like_ `bash-oo-framework`. That is, cool features that are a part of `bash-oo-framework` like stack traces can be installable as a library rather than a greater framework
+
+- The two existing prominent package managers (`bpkg` and `Basher`) are most similar, but fall short. Some gripes are listed below
 
 ### `bpkg` disadvantages
 
@@ -28,4 +30,5 @@ The general idea isn't new; there exist two prominent package managers (`bpkg` a
 - Cannot install local, per-project dependencies
 - Have subpar completion scripts
 
-These disadvantages gave me reason to create a new package manager that was significantly improved. I originally forked Basher because it had an excellent test suite and its behavior for installing packages made more sense to me. However, since a massive refactoring effort in addition to a near-complete rewrite took effect, there is almost no original Basher code that exists currently
+
+For each tool, the issues were systemic so I forked Basher and made heavy modifications, eventually doing a complete rewrite

docs/internals/package-installation.md

@@ -4,33 +4,36 @@ This page provides information on how and where packages are installed.
 
 The installation of packages is split into four phases. Each of these phases corresponds to a function in `pkg.sh`
 
-1. Package download
-2. Package extraction
-3. Package global integration
-4. Package local integration (recursive)
-5. Package local integration (non-recursive)
+1. Package download `pkg.phase_download_tarball()`
+2. Package extraction `pkg.phase_extract_tarball()`
+3. Package global integration (recursive) `pkg.phase_local_integration_recursive() "$BASALT_GLOBAL_DATA_DIR..."`
+4. Package global integration (non-recursive) `pkg.phase_local_integration_nonrecursive() "$BASALT_GLOBAL_DATA_DIR..."`
+5. Package local integration (recursive) `pkg.phase_local_integration_recursive() "$BASALT_LOCAL_PROJECT_DIR..."`
+6. Package local integration (non-recursive) `pkg.phase_local_integration_nonrecursive() "$BASALT_LOCAL_PROJECT_DIR..."`
 
 ## 1. Package download
 
 During this stage, tarballs files are downloaded from the internet to `$BASALT_GLOBAL_DATA_DIR/store/tarballs`
 
-In most cases, tarballs can be downloaded directly. From the point of view of a consumer, you can access these types of tarballs by specifying a revision like `@v0.3.0'` in `dependencies`. From the point of view of a package maintainer, enable this behavior by authoring a GitHub release based on a release commit of a Git repository. Doing this is most efficient since the whole Git repository does not need to be downloaded
+In most cases, tarballs can be downloaded directly. From the point of view of a consumer, you can access these types of tarballs by specifying a revision like `@v0.3.0'` in `dependencies`. From the point of view of a package maintainer, enable this behavior by authoring a GitHub release based on a git tag of a Git repository. Doing this is most efficient since the whole Git repository does not need to be downloaded
 
 Sometimes, a package consumer may want to use a revision that is not a release (e.g. `@e5466e6c3998790ebd99768cf0f910e161b84a95`). When this type of revision is specified, Basalt will clone the entire repository, then use `git-archive(1)` to extract the revision in the form of a tarball
 
 ## 2. Package extraction
 
 During this stage, tarball files located in `$BASALT_GLOBAL_DATA_DIR/store/tarballs` are simply extracted and placed in `$BASALT_GLOBAL_DATA_DIR/store/packages`
 
-### 3. Global integration
+### 3. Global integration (recursive)
 
-For each package in `$BASALT_GLOBAL_DATA_DIR/store/packages`, modifications are done. This includes but is not limited to
+For each package in `$BASALT_GLOBAL_DATA_DIR/store/packages`, modifications are done. Find more information about the modifications in "recursive local integration"
 
-- Appending version numbers to all functions
-- Creating a local `./.basalt` directory (local integration)
-- Converting the runtime essence of the `./basalt.toml` file into other files that are either sourceable or easier to parse
 
-### 4. Local integration (recursive)
+
+### 4. Global integration (non-recursive)
+
+For each package in `$BASALT_GLOBAL_DATA_DIR/store/packages`, modifications are done that don't require recursively resolving subdependencies. Find more information about the modifications in "non-recursive local integration"
+
+### 5. Local integration (recursive)
 
 This step involves creating a `.basalt` directory so the functionality of all dependencies can be properly exposed. The directory is located at `$BASALT_LOCAL_PROJECT_DIR/.basalt` for local dependencies and at `$BASALT_GLOBAL_DATA_DIR/global/.basalt` for global dependencies
 
@@ -47,6 +50,9 @@ This step involves creating a `.basalt` directory so the functionality of all de
     - packages/
 ```
 
-### 5. Local integration (non-recursive)
+### 6. Local integration (non-recursive)
 
 This is similar to the previous step, except it performs functionalities that are inherently non recursive. This includes creating the `./basalt/generated` subdirectory and the files within it
+
+- Appending version numbers to all functions
+- Converting the runtime essence of the `./basalt.toml` file into other files that are either sourceable or easier to parse

docs/reference/environment.md renamed to docs/reference/api.md

@@ -1,6 +1,6 @@
 # Environment
 
-## Global Environment Variables
+## Global
 
 Global environment variables are both valid globally (after `eval "$(basalt global init bash)"`) and locally (after `eval "$(basalt-package-init)"; basalt.package-init`)
 
@@ -12,10 +12,30 @@ The location of the source code. By default (when using the `install.sh` script)
 
 The directory Basalt stores nearly all data. This includes downloaded tarballs, directories extracted from tarballs, and the directories that contain global installations of packages. By default, this has the value of `${XDG_DATA_HOME:-$HOME/.local/share}/basalt`
 
-## Local Environment Variables
+### `basalt.load`
+
+Sources a particular file of a particular package
+
+For example, the below example sources the `z.sh` file that is present at the root of [rupa/z](https://github.com/rupa/z). Note that you must pass in the website, as well as the repository owner and repository name
+
+```sh
+basalt.load --global 'github.com/rupa/z' 'z.sh'
+```
+
+If you do not pass a file, it will automatically source a `load.bash` at the root of the repository, if it exists
+
+## Local
 
 Local environment variables are only valid within a Bash package (after `eval "$(basalt-package-init)"; basalt.package-init`)
 
 ### `BASALT_PACKAGE_DIR`
 
 The full path to the current project. It is calculated by walking up the file tree from `$PWD`, only stopping after detecting a `./basalt.toml`. The directory that was stopped at is the new value of `BASALT_PACKAGE_DIR`
+
+### `basalt.package-load`
+
+Loads all Basalt dependencies
+
+```sh
+basalt.package-load
+```