docs(dotfiles): 📝 updated documentation and refactoring loaders

lib/README.md

@@ -1,12 +1,86 @@
-<!-- markdownlint-disable MD033 MD041 MD043 -->
-
 <img
   src="https://kura.pro/dotfiles/v2/images/logos/dotfiles.svg"
   alt="dotfiles logo"
   width="66"
   align="right"
 />
 
-<!-- markdownlint-enable MD033 MD041 -->
+# Dotfiles Shell Configuration Scripts
+
+Simply designed to fit your shell life 🐚
+
+![Dotfiles banner][banner]
+
+This repository includes various scripts to enhance your shell experience, manage configurations, and customize behavior. The scripts are organized and detailed below.
+
+## 🔑 Scripts List
+
+<!-- markdownlint-disable MD013-->
+
+### Alias Management
+
+| Script            | Description                                      | Usage                          |
+| :---------------- | :----------------------------------------------- | :----------------------------- |
+| `aliases.sh`      | Manage and load custom shell aliases.            | `source aliases.sh`           |
+
+#### Features
+
+- **Remove All Aliases:** Clears all existing aliases in the current shell environment.
+- **Load Custom Aliases:** Sources alias definitions from a specified directory within `.dotfiles`.
+
+### Configuration Management
+
+| Script            | Description                                      | Usage                          |
+| :---------------- | :----------------------------------------------- | :----------------------------- |
+| `configurations.sh` | Load custom shell configurations.              | `source configurations.sh`    |
+
+#### Features
+
+- **Custom Configurations:** Loads shell-specific configurations from the `.dotfiles` directory.
+- **Error Handling:** Reports missing configuration files or sourcing issues.
+
+### Function Management
+
+| Script            | Description                                      | Usage                          |
+| :---------------- | :----------------------------------------------- | :----------------------------- |
+| `functions.sh`    | Load custom executable functions.                | `source functions.sh`         |
+
+#### Features
+
+- **Custom Functions:** Sources user-defined functions from the `.dotfiles/lib/functions` directory.
+- **Directory Check:** Ensures the functions directory exists before sourcing.
+
+### History Management
+
+| Script            | Description                                      | Usage                          |
+| :---------------- | :----------------------------------------------- | :----------------------------- |
+| `history.sh`      | Manage and configure shell history behavior.     | `source history.sh`           |
+
+#### Features
+
+- **Clear History:** Clears the history file and removes duplicates.
+- **List History:** Displays shell history with enhanced formatting.
+- **History Configuration:** Sets up shell-specific history options for Bash and Zsh.
+
+### Path Management
+
+| Script            | Description                                      | Usage                          |
+| :---------------- | :----------------------------------------------- | :----------------------------- |
+| `paths.sh`        | Load custom path configurations.                 | `source paths.sh`             |
+
+#### Features
+
+- **Load Paths:** Adds directories to the shell `PATH` variable from `.dotfiles/lib/paths`.
+- **Error Reporting:** Alerts the user if the paths directory is missing.
+
+### Usage
+
+| Command                     | Description                              |
+| :-------------------------- | :--------------------------------------- |
+| `source <script>.sh`        | Apply the respective script configuration.|
+| `echo $PATH`                | Verify the current `PATH`.               |
+| `h` or `history`            | Access custom history management.        |
+
+<!-- markdownlint-enable MD013-->
 
-# Dotfiles aliases
+[banner]: https://kura.pro/dotfiles/v2/images/titles/title-dotfiles.svg

lib/configurations.sh

@@ -24,10 +24,22 @@
 #   ShellCheck Documentation: https://github.com/koalaman/shellcheck
 
 load_custom_configurations() {
-  for config in "${HOME}"/.dotfiles/lib/configurations/[!.#]*/*.sh; do
-    # shellcheck source=/dev/null
-    source "${config}"
-  done
+  local config_dir="${HOME}/.dotfiles/lib/configurations"
+
+  # Check if the directory exists
+  if [[ -d "${config_dir}" ]]; then
+    for config in "${config_dir}"/[!.#]*/*.sh; do
+      if [[ -f "${config}" ]]; then
+        # shellcheck source=/dev/null
+        source "${config}" || {
+          echo "Error: Failed to source ${config}" >&2
+          return 1
+        }
+      fi
+    done
+  else
+    echo "Warning: Configuration directory ${config_dir} does not exist." >&2
+  fi
 }
 
 load_custom_configurations

lib/functions.sh

@@ -23,13 +23,24 @@
 #   ShellCheck Documentation: https://github.com/koalaman/shellcheck
 
 load_custom_functions() {
-  for function in "${HOME}"/.dotfiles/lib/functions/*.sh; do
-    # shellcheck source=/dev/null
-    source "${function}" || {
-      echo "Failed to source ${function}" >&2
-      return 1
-    }
-  done
+  local functions_dir="${HOME}/.dotfiles/lib/functions"
+
+  # Check if the directory exists
+  if [[ -d "$functions_dir" ]]; then
+    for function_file in "$functions_dir"/*.sh; do
+      if [[ -f "$function_file" ]]; then
+        # shellcheck source=/dev/null
+        source "$function_file" || {
+          echo "Error: Failed to source $function_file" >&2
+          return 1
+        }
+      fi
+    done
+  else
+    echo "Warning: Functions directory $functions_dir does not exist." >&2
+  fi
 }
 
+# Main Execution
+# ---------------------------------------------------------
 load_custom_functions

lib/history.sh

@@ -24,22 +24,27 @@
 #   Zsh History Documentation: https://www.zsh.org/mla/users/2007/msg00366.html
 #   Bash History Builtins Documentation: https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html#Bash-Builtins
 
-function dotfiles_history {
-  local clear_flag list_flag
-  zparseopts -E c=clear_flag l=list_flag
+dotfiles_history() {
+  local clear_flag="" list_flag=""
+
+  if [[ -n "${ZSH_VERSION:-}" ]]; then
+    zparseopts -E c=clear_flag l=list_flag || true
+  else
+    clear_flag=$( [[ "$1" == "-c" ]] && echo "1" || echo "" )
+    list_flag=$( [[ "$1" == "-l" ]] && echo "1" || echo "" )
+  fi
 
   if [[ -n ${clear_flag} ]]; then
-    # Clear the history file and remove duplicates
     fc -W
     fc -R
     echo "History file deleted and duplicates removed. Reload the session to see its effects." >&2
   elif [[ -n ${list_flag} ]] || [[ $# -ne 0 ]]; then
-    # If -l flag is provided or arguments are passed, run as if calling `fc` directly
+    local fc_output
     fc_output=$(builtin fc "$@")
     printf '%s\n' "$(tput setaf 5)$(tput sgr0)$(tput setaf 2)$(echo "${fc_output//$'\e'/$(tput setaf 2)}" | sed -E "s/^([[:space:]]*[0-9]+)/$(tput setaf 2)\1$(tput sgr0)/")" || true
   else
-    # Ensure the history file has no duplicates and show all history events starting from 1
-    fc -W # Remove duplicates from the history file
+    fc -W
+    local fc_output
     fc_output=$(builtin fc -li 1)
     printf '%s\n' "$(tput setaf 5)$(tput sgr0)$(tput setaf 2)$(echo "${fc_output//$'\e'/$(tput setaf 2)}" | sed -E "s/^([[:space:]]*[0-9]+)/$(tput setaf 2)\1$(tput sgr0)/")" || true
   fi
@@ -54,89 +59,32 @@ function dotfiles_history {
 #   Zsh Options Documentation: https://zsh.sourceforge.io/Doc/Release/Options.html
 #   Bash shopt Documentation: https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html
 
-function configure_history() {
-
+configure_history() {
   fc -W
 
-  # Alias to list recent commands
   alias h='dotfiles_history'
-
-  # Alias to view history
   alias history='dotfiles_history'
-
 }
 
-# Zsh Config
-# ---------------------------------------------------------
-# Explanation of Zsh options:
-#   - hist_ignore_space: Removes command lines from the history list when the first character on the line is a space.
-#   - hist_no_store: Removes the history command from the history list when invoked.
-#   - hist_reduce_blanks: Removes superfluous blanks from each command line being added to the history list.
-
-export HISTFILE="${HOME}/.zsh_history" # History file
-export HISTCONTROL="ignoreboth"        # Ignore duplicate commands and commands that start with a space
-export HISTSIZE="10000"                # Number of commands to save in memory
-export SAVEHIST="1000"                 # Number of commands to save on disk
+# Apply shell-specific configurations
+apply_shell_configurations() {
+  if [[ -n "${ZSH_VERSION:-}" ]]; then
+    setopt hist_ignore_space hist_no_store hist_reduce_blanks hist_expire_dups_first hist_save_no_dups append_history
+    export HISTFILE="${HOME}/.zsh_history"
+    export HISTSIZE="10000"
+    export SAVEHIST="1000"
+  elif [[ -n "${BASH_VERSION}" ]]; then
+    export HISTFILE="${HOME}/.bash_history"
+    export HISTCONTROL="ignoreboth"
+    export HISTSIZE="10000"
+    shopt -s histappend histverify nocaseglob dotglob
+  else
+    echo "Unsupported shell: ${SHELL}" >&2
+    exit 1
+  fi
+}
 
-# Bash Config
+# Main Execution
 # ---------------------------------------------------------
-# Explanation of Bash shopts:
-#   - histappend: Append to the history file, don't overwrite it.
-#   - histverify: Verify commands from history before executing them.
-#   - nocaseglob: Case insensitive globbing.
-
-if [[ -n "${ZSH_VERSION:-}" ]]; then
-  setopt always_to_end          # Move cursor to the end of a completed word.
-  setopt append_history         # Sessions will append their history list to the history file, rather than replace it.
-  setopt auto_cd                # cd to a directory if it's given without a command.
-  setopt auto_list              # Automatically list choices on ambiguous completion.
-  setopt auto_menu              # Show completion menu on a successive tab press.
-  setopt auto_param_keys        # Automatically complements parentheses
-  setopt auto_param_slash       # If completed parameter is a directory, add a trailing slash.
-  setopt auto_pushd             # Automatically push when cd
-  setopt auto_resume            # Resume if you execute the same command name as the suspended process
-  setopt bang_hist              # Perform textual history expansion
-  setopt complete_in_word       # Complete from both ends of a word.
-  setopt correct                # Enable command correction prompts
-  setopt extended_history       # Save each command’s beginning timestamp (in seconds since the epoch) and the duration (in seconds) to the history file.
-  setopt hist_beep              # Beep in ZLE when a widget attempts to access a history entry which isn’t there.
-  setopt hist_expire_dups_first # Cause the oldest history event that has a duplicate to be lost before losing a unique event from the list.
-  setopt hist_ignore_space      # Remove command lines from the history list when the first character on the line is a space, or when one of the expanded aliases contains a leading space.
-  setopt hist_no_store          # Remove the history (fc -l) command from the history list when invoked.
-  setopt hist_reduce_blanks     # Remove superfluous blanks from each command line being added to the history list.
-  setopt hist_save_no_dups      # When writing out the history file, older commands that duplicate newer ones are omitted.
-  setopt hist_verify            # Whenever the user enters a line with history expansion, don’t execute the line directly; instead, perform history expansion and reload the line into the editing buffer.
-  setopt list_packed            # Display with complementary candidates packed
-  setopt list_types             # Mark the file type in the completion candidate list
-  setopt pushd_ignore_dups      # Don’t push multiple copies of the same directory onto the directory stack.
-  setopt share_history          # Imports new commands from the history file, and also causes the typed commands to be appended to the history file
-  setopt transient_rprompt      # Display the right prompt only when the cursor is on the rightmost column.
-
-elif [[ -n "${BASH_VERSION}" ]]; then
-  shopt -s autocd                  # autocd - automatically cd to a directory when it is the only argument to a command
-  shopt -s cdspell                 # cdspell - spell check the path when changing directories.
-  shopt -s checkhash               # checkhash - check hash table for commands before running them.
-  shopt -s checkjobs               # checkjobs - check for stopped jobs after each command and report them to the user.
-  shopt -s checkwinsize            # checkwinsize - check the window size after each command and, if necessary, update the values of LINES and COLUMNS.
-  shopt -s cmdhist                 # cmdhist - save multi-line commands as one entry in history.
-  shopt -s dirspell                # dirspell - spell check the path when changing directories.
-  shopt -s dotglob                 # dotglob - include dotfiles in globbing.
-  shopt -s extglob                 # extglob - extended globbing.
-  shopt -s globstar                # globstar - allow ** to match multiple directories.
-  shopt -s histappend              # histappend - append to the history file, don't overwrite it.
-  shopt -s histverify              # histverify - verify commands from history before executing them.
-  shopt -s hostcomplete            # hostcomplete - complete hostnames when using the ssh command.
-  shopt -s lithist                 # lithist - save multi-line commands as one entry in history.
-  shopt -s huponexit               # huponexit - send SIGHUP to jobs when the shell exits.
-  shopt -s no_empty_cmd_completion # no_empty_cmd_completion - don't complete empty commands.
-  shopt -s nocaseglob              # nocaseglob - case insensitive globbing.
-  shopt -s nocasematch             # nocasematch - case insensitive matching.
-  shopt -s nullglob                # nullglob - if no matches are found, the pattern expands to nothing.
-  shopt -s progcomp                # progcomp - programmable completion.
-  shopt -s promptvars              # promptvars - allow prompt strings to contain shell variables.
-  shopt -s sourcepath              # sourcepath - search the PATH for the directory containing a sourced script before using the current directory.
-
-else
-  echo "Unsupported shell: ${SHELL}"
-  exit 1
-fi
+configure_history
+apply_shell_configurations

lib/paths.sh

@@ -2,11 +2,11 @@
 
 ################################################################################
 # 🅳🅾🆃🅵🅸🅻🅴🆂
-# Script: configurations.sh
+# Script: paths.sh
 # Version: 0.2.469
 # Author: Sebastien Rousseau
 # Copyright (c) 2015-2025. All rights reserved
-# Description: Script to manage shell configurations
+# Description: Script to load custom paths
 # Website: https://dotfiles.io
 # License: MIT
 ################################################################################
@@ -23,10 +23,24 @@
 #   ShellCheck Documentation: https://github.com/koalaman/shellcheck
 
 load_paths() {
-  for path in "${HOME}"/.dotfiles/lib/paths/*.sh; do
-    # shellcheck source=/dev/null
-    source "${path}"
-  done
+  local paths_dir="${HOME}/.dotfiles/lib/paths"
+
+  # Check if the directory exists
+  if [[ -d "$paths_dir" ]]; then
+    for path_file in "$paths_dir"/*.sh; do
+      if [[ -f "$path_file" ]]; then
+        # shellcheck source=/dev/null
+        source "$path_file" || {
+          echo "Error: Failed to source $path_file" >&2
+          return 1
+        }
+      fi
+    done
+  else
+    echo "Warning: Paths directory $paths_dir does not exist." >&2
+  fi
 }
 
+# Main Execution
+# ---------------------------------------------------------
 load_paths