Merge pull request #105 into master

a817901 container: add `dfi` alias (Aaron Fiore) 0db5566 client: add `dfi` alias (Aaron Fiore) 3230a5b README: add `dfi` alias (Aaron Fiore)
2024-08-06 02:20:35 -07:00
parent b692a6145f a81790108b
commit cb578a2aca
6 changed files with 75 additions and 66 deletions
--- a/README.md
+++ b/README.md
@@ -243,8 +243,6 @@ Supported blockchains (independent of wallet type):

 ### Installation

-[//]: # (TODO: add `dfi` aliases, update README)
-
 `docker-finance` is not your typical Docker image in which you simply pull and containerize, but rather it's an *image-based* accounting system that operates transparently between your client (host) and container; keeping your finances containerized, with all the benefits of containerization.

 `docker-finance` *should* work out-of-the-box on any modern Linux system. For example, if your client (host) is Ubuntu, the default installation of `coreutils`, `shells` and `utils` that came with your system will satisfy requirements. However, you'll still need to manually install Docker (see below).
@@ -307,31 +305,35 @@ Supported blockchains (independent of wallet type):

 5. **Prepare your shell environment**:

-   This will install convenience aliases and command completion to your shell environment (see [install.bash](client/install.bash) for details).
+   The following install convenience aliases and command completion to your shell environment (see [install.bash](client/install.bash) for details).

     ```bash
     ./docker-finance/client/install.bash && source ~/.bashrc
     ```

+   - After your first image is built (step 7), you can use commandline completion for all `docker-finance` images and image-based commands
+   - The `dfi` alias of `docker-finance` is the recommended alias to use for for all client/container operations
+
 6. **Generate client/container environment**:

-   This will generate your Docker-related client/container environment (see [Environment Generation](#environment-generation) for details).
+   The following will generate your Docker-related client/container environment for the default image (see [Environment Generation](#environment-generation) for details):

     ```bash
-     docker-finance archlinux/${USER}:default gen
+     dfi archlinux/${USER}:default gen
     ```
+   > If you would like to use the `ubuntu` image, replace `archlinux` with `ubuntu` here and for all remaining steps

 7. **Build default `docker-finance` image**:
     ```bash
-     docker-finance archlinux/${USER}:default build type=default
+     dfi archlinux/${USER}:default build type=default
     ```
-   > See `docker-finance archlinux/${USER}:default build help` for build options (such as smaller, faster builds)
+   > Use the `build help` command for available options (such as smaller, faster builds)

 8. **Bring up container of default `docker-finance` image**:
     ```bash
-     docker-finance archlinux/${USER}:default up
+     dfi archlinux/${USER}:default up
     ```
-   > You can use tab completion for all commands available to this built image
+   > You can use tab completion for all `dfi <platform/user:tag>` commands (but only for built images). See `dfi help` for commands.

 9. **You're inside!** See [How do I use it?](#how-do-i-use-it) for next steps.

@@ -381,6 +383,9 @@ Although the container environment is a minimum requirement, here you'll have th

 If you're a developer or wish to see the mockup test profile, select 'y' here.

+It should be noted that:
+  - mockup data can be found in the `mockup` directories within this repository
+
 > *Enter profile name (e.g., family in 'family/alice')*
 > *Enter subprofile name (e.g., alice in 'family/alice')*

@@ -475,7 +480,7 @@ The bind-mount is used exclusively for non-essential file sharing (custom script

 The container's `finance` command (useful for experimental implementations).

-Default: `finance.bash` (internally aliased to `finance`)
+Default: `finance.bash` (internally aliased to `finance` and `dfi`)

 - Example: `DOCKER_FINANCE_CONTAINER_CMD=finance.bash`

@@ -622,7 +627,7 @@ See the in-file comments for further documentation:

  - [subprofile.bash.in](client/docker-finance.d/container/shell/subprofile.bash.in)

-After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=shell` (see [Container Command Format](#container-command-format)).
+After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=shell` (see [Container Command Format](#container-command-format)).

 ##### *Fetch*

@@ -632,7 +637,7 @@ See the in-file comments for further documentation:

  - [fetch.yaml.in](client/docker-finance.d/container/fetch/fetch.yaml.in)

-After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=fetch` (see [Container Command Format](#container-command-format)).
+After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=fetch` (see [Container Command Format](#container-command-format)).

 ##### *Meta*

@@ -642,7 +647,7 @@ See the in-file comments for further documentation:

  - [meta.csv.in](client/docker-finance.d/container/meta/meta.csv.in)

-After `gen` is complete, from within the container, you can edit this file with: `finance profile/subprofile edit type=meta` (see [Container Command Format](#container-command-format)).
+After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=meta` (see [Container Command Format](#container-command-format)).

 ## How do I use it?

@@ -657,11 +662,12 @@ These two scripts can be rationalized by the following format:

    <script> <super/sub> <command> [args]

-> Note: for your convenience, command arguments [args] can be arranged in any order.
-
 For example, these [Screenshots](#screenshots) describe a setup with mockup data where the client (host) user named `personal`, along with container `$DOCKER_FINANCE_USER` named `personal`, engage in client/container activity. The container profile named `testprofile` and its subprofile named `testuser` can be described as `<super/sub>` portion of the format (`testprofile/testuser`).

-> Note: mockup data can be found in the `mockup` directories within this repository.
+It should be noted that, for your convenience:
+  - command arguments [args] can be arranged in any order
+  - commandline completion is available for all `<super/sub> command [args]` (so, save your fingers and tab away)
+    - NOTE: for client, an image must first be built

 ---

@@ -681,22 +687,18 @@ Where:
  - `<command>` is the command to pass to `docker.bash`
  - `[args]` are the (optional) arguments to pass to `<command>`

-For a complete list of commands and usage help:
+If the [Installation](#installation) was successful, `docker.bash` is aliased to `docker-finance` and `dfi` (so, either can be used).
+
+For a complete list of commands and usage help (`<platform/user:tag>` *not* required):

 ```bash
-${DOCKER_FINANCE_CLIENT_REPO}/client/docker.bash archlinux/${USER}:default help
+dfi help
 ```

-Or, if the [Installation](#installation) alias was properly created:
+To view the help usage of a specific command, for example; the `edit` command (`<platform/user:tag>` *is* required):

 ```bash
-docker-finance archlinux/${USER}:default help
-```
-
-You can also view the help usage of, for example, the `edit` command:
-
-```bash
-docker-finance archlinux/${USER}:default edit help
+dfi archlinux/${USER}:default edit help
 ```

 ---
@@ -716,20 +718,20 @@ Where:
  - `<command>` is the command to pass to `finance.bash`
  - `[args]` are the (optional) arguments to pass to `<command>`

-By default, `finance.bash` is aliased to `finance` (so, either can be used).
+By default, `finance.bash` is aliased to `finance` and `dfi` (so, either can be used).

-For a complete list of commands (no `<profile/subprofile>` needed):
+For a complete list of commands (`<profile/subprofile>` *not* required):

 ```bash
-finance help
+dfi help
 ```

-You can also view the help usage of, for example, the `fetch` command (notice the need for `<profile/subprofile>`).
+To view the help usage of a specific command, for example; the `fetch` command (`<profile/subprofile>` *is* required):

 Assuming `<profile/subprofile>` is `testprofile/testuser`:

 ```bash
-finance testprofile/testuser fetch help
+dfi testprofile/testuser fetch help
 ```

 Or, use a subprofile alias, as described in [Subprofile](#subprofile):
@@ -738,8 +740,6 @@ Or, use a subprofile alias, as described in [Subprofile](#subprofile):
 testuser_fetch help
 ```

-> Note: the `finance` alias is named to avoid confusion with the client (host) command `docker-finance`, but you can still use the alias `docker-finance` *within* the container in place of all `finance` commands.
-
 ### Flow Layout

 A primary read through of [hledger](https://hledger.org) and [hledger-flow](https://github.com/apauley/hledger-flow/blob/master/README.org) documentation should bring you up to speed on the essentials.
--- a/client/docker-finance.d/container/shell/superscript.bash.in
+++ b/client/docker-finance.d/container/shell/superscript.bash.in
@@ -33,6 +33,7 @@ export PATH="$PATH:${HOME}/.local/bin:${DOCKER_FINANCE_CONTAINER_REPO}:${DOCKER_
 # Base command alias
 alias docker-finance='$DOCKER_FINANCE_CONTAINER_CMD'
 alias finance='$DOCKER_FINANCE_CONTAINER_CMD'
+alias dfi='$DOCKER_FINANCE_CONTAINER_CMD'

 # Traditional aliases
 alias c='clear' # or ctrl+l
--- a/client/install.bash
+++ b/client/install.bash
@@ -23,18 +23,18 @@ aliases=~/.bash_aliases
 function docker-finance::install()
 {
  # Environment expectations
-  local -r _alias="alias docker-finance="
+  local -r _alias=("docker-finance" "dfi")
  local _path # full path to docker-finance repository
  _path="$(dirname "$(realpath -s $0)" | rev | cut -d'/' -f2- | rev)"

-  # Remove previous alias
-  if grep "^${_alias}" "$aliases" &>/dev/null; then
-    sed -i "/^${_alias}/d" "$aliases"
-    unalias docker-finance
-  fi
-
-  # Set new alias
-  echo "${_alias}'${_path}/client/docker.bash'" >>"$aliases"
+  # Install (or re-install) aliases
+  # NOTE: caller must `source` (as `unalias` and `alias` are in subshell)
+  for _a in "${_alias[@]}"; do
+    if grep "^alias ${_a}=" "$aliases" &>/dev/null; then
+      sed -i "/^alias ${_a}=/d" "$aliases"
+    fi
+    echo "alias ${_a}='${_path}/client/docker.bash'" >>"$aliases"
+  done

  # Set bash completion
  _completion="${_path}/client/src/docker/completion.bash"
@@ -57,7 +57,7 @@ else
      fi
    fi
    docker-finance::install \
-      && echo "SUCCESS: installation complete"
+      && echo "SUCCESS: installation complete" \
      || echo "FATAL: could not complete installation"
  else
    echo "FATAL: unsupported bash environment" >&2
--- a/client/src/docker/completion.bash
+++ b/client/src/docker/completion.bash
@@ -97,3 +97,6 @@ function docker-finance::completion()

 complete -F docker-finance::completion docker.bash
 complete -F docker-finance::completion docker-finance
+complete -F docker-finance::completion dfi
+
+# vim: sw=2 sts=2 si ai et
--- a/client/src/docker/docker.bash
+++ b/client/src/docker/docker.bash
@@ -95,57 +95,59 @@ function main()
  \e[37;2m# Finance platform\e[0m
  \e[37;2m#\e[0m

-  \e[37;2m# For the sake of simplicity, recreate the docker-finance alias using <platform${global_arg_delim_1}user:tag>\e[0m
-  $ unalias docker-finance 2>/dev/null \\
-    ; alias docker-finance=\"$0 archlinux${global_arg_delim_1}${USER}:default\"
-
-  \e[37;2m# Generate environment and build default image\e[0m
-  $ docker-finance gen && docker-finance build type${global_arg_delim_2}default
+  \e[37;2m# Generate default environment and build default image\e[0m
+  $ dfi archlinux${global_arg_delim_1}${USER}:default gen \\
+    && dfi archlinux${global_arg_delim_1}${USER}:default build type${global_arg_delim_2}default

  \e[37;2m# Bring up container, open shell (type 'exit' to leave)\e[0m
-  $ docker-finance up
+  $ dfi archlinux${global_arg_delim_1}${USER}:default up

  \e[37;2m# In another shell (or after you exit), open a container root shell\e[0m
-  $ docker-finance shell user${global_arg_delim_2}root
+  $ dfi archlinux${global_arg_delim_1}${USER}:default shell user${global_arg_delim_2}root

  \e[37;2m# In another shell (or after you exit), edit client/container variables\e[0m
-  $ docker-finance edit type${global_arg_delim_2}env
+  $ dfi archlinux${global_arg_delim_1}${USER}:default edit type${global_arg_delim_2}env

  \e[37;2m# Spawn a container with given command (removed after command finishes)\e[0m
  \e[37;2m# NOTE: incredibly useful when used with your host's crontab\e[0m
-  $ docker-finance run 'finance family/alice fetch all${global_arg_delim_2}price'
+  $ dfi archlinux${global_arg_delim_1}${USER}:default run 'dfi family/alice fetch all${global_arg_delim_2}price'

  \e[37;2m# Bring down running container (stop and remove container & network)\e[0m
-  $ docker-finance down
+  $ dfi archlinux${global_arg_delim_1}${USER}:default down

  \e[37;2m# Backup image, delete old image, build new image\e[0m
-  $ docker-finance backup && docker-finance rm && docker-finance build
+  $ dfi archlinux${global_arg_delim_1}${USER}:default backup \\
+    && dfi archlinux${global_arg_delim_1}${USER}:default rm \\
+    && dfi archlinux${global_arg_delim_1}${USER}:default build

  \e[37;2m# Print current version of 'docker-finance' and client/container ('finance') dependencies\e[0m
-  $ docker-finance version type${global_arg_delim_2}all
+  $ dfi archlinux${global_arg_delim_1}${USER}:default version type${global_arg_delim_2}all

  \e[37;2m#\e[0m
  \e[37;2m# Dev-tools platform\e[0m
  \e[37;2m#\e[0m

-  \e[37;2m# For the sake of simplicity, recreate the dev-tools alias using <platform${global_arg_delim_1}user:tag>\e[0m
-  $ unalias dev-tools 2>/dev/null \\
-    ; alias dev-tools=\"$0 dev-tools${global_arg_delim_1}${USER}:default\"
-
-  \e[37;2m# Generate environment and build default image\e[0m
-  $ dev-tools gen && dev-tools build type${global_arg_delim_2}default
+  \e[37;2m# Generate default environment and build default image\e[0m
+  $ dfi dev-tools${global_arg_delim_1}${USER}:default gen \\
+    && dfi archlinux${global_arg_delim_1}${USER}:default build type${global_arg_delim_2}default

  \e[37;2m# Spawn a container with given command (removed after command finishes)\e[0m
-  $ dev-tools run 'shellcheck --version'
+  $ dfi dev-tools${global_arg_delim_1}${USER}:default run 'shellcheck --version'

  \e[37;2m# Lint entire docker-finance source\e[0m
-  $ dev-tools linter type${global_arg_delim_2}bash${global_arg_delim_3}php${global_arg_delim_3}c++
+  $ dfi dev-tools${global_arg_delim_1}${USER}:default linter type${global_arg_delim_2}bash${global_arg_delim_3}php${global_arg_delim_3}c++

  \e[37;2m# Generate Doxygen for docker-finance source\e[0m
-  $ dev-tools doxygen gen
+  $ dfi dev-tools${global_arg_delim_1}${USER}:default doxygen gen

  \e[37;2m# Print current version of 'docker-finance' and client/container ('dev-tools') dependencies\e[0m
-  $ dev-tools version type${global_arg_delim_2}all
+  $ dfi dev-tools${global_arg_delim_1}${USER}:default version type${global_arg_delim_2}all
+
+\e[32mTips:\e[0m
+
+  - Save your fingers! Use tab completion for all images and commands (see README)
+  - Setup aliases for frequently used images (useful for single-user systems)
+    * Depending on your alias design, tab completion may not be available
 "

  #
--- a/container/src/finance/completion.bash
+++ b/container/src/finance/completion.bash
@@ -98,3 +98,6 @@ function docker-finance::completion()
 complete -F docker-finance::completion finance
 complete -F docker-finance::completion finance.bash
 complete -F docker-finance::completion docker-finance
+complete -F docker-finance::completion dfi
+
+# vim: sw=2 sts=2 si ai et