✨ Add support for nested package paths (#14)

* 🩹 Avoid including in comments

Signed-off-by: Daniel Ruthardt <druthardt@linuxfoundation.org>

* ✨ Add support for sub-packages

Signed-off-by: Daniel Ruthardt <druthardt@linuxfoundation.org>

* 📝 Add sub-packages to sample script/libs

Signed-off-by: Daniel Ruthardt <druthardt@linuxfoundation.org>

* 📝 Update documentation adding sub-packages

Signed-off-by: Daniel Ruthardt <druthardt@linuxfoundation.org>

---------

Signed-off-by: Daniel Ruthardt <druthardt@linuxfoundation.org>

Author: Daniel Ruthardt

README.md

@@ -73,10 +73,35 @@ test::hello
 # Rely on auto-include based on naming-convention "<package>::<function>"
 
 test::hello_world
+
+# Option 3
+# Use nested package paths for better organization
+
+#include test/test/hello
+test::test::hello
+
+test::test::hello_world
 ```
 
-This script demonstrates two ways to include and use functions from external libraries or packages
-in your Bash+ scripts.
+This script demonstrates three ways to include and use functions from external libraries or packages
+in your Bash+ scripts. The third option shows how to use nested package paths for better organization
+of your code.
+
+### Package Path Resolution
+
+Bash+ supports nested package paths, allowing for better organization of your code. For example:
+- `test::hello` - Basic package path
+- `test::test::hello` - Nested package path
+- `org::team::project::module::function` - Deeply nested package path
+
+This hierarchical structure helps organize related functions and makes the codebase more maintainable.
+
+### Git Integration
+
+Bash+ automatically manages your `.gitignore` file:
+- Dynamically adds included functions to prevent unintended commits
+- Supports both GitHub and OCI package sources
+- Maintains a clean repository by tracking only necessary files
 
 ## Contributing
 

bashpp

@@ -10,7 +10,8 @@ set -eo pipefail
 #   - Local directories specified by $BASHP_INCLUDE_DIRS
 #   - External sources via extension handlers (e.g., bashpp-oci, bashpp-gh)
 #   This enables modular script development by allowing scripts to dynamically include and use
-#   functions from external packages.
+#   functions from external packages. It supports nested package paths for better organization
+#   of functions (e.g., org::team::project::module::function).
 #
 # Usage:
 #   bashpp [file]
@@ -41,7 +42,7 @@ set -eo pipefail
 #
 # Notes:
 #   - Functions to be included should be placed in directories or repositories following the
-#     structure <package>/<function>
+#     structure <package>/<function> or <package>/<subpackage>/<function> for nested paths
 #   - For OCI registries, packages should be named 'bashp-<package>:latest'
 #   - For GitHub releases, assets should be named 'bashp-<package>.tar.gz'
 #   - The script automatically adds included functions to .gitignore when pulled from external
@@ -50,6 +51,7 @@ set -eo pipefail
 #   - GitHub releases are cached in $BASHP_CACHE_DIR to avoid repeated downloads
 #   - Repository URLs can include explicit protocol handlers (oci://, gh://)
 #   - If no protocol is specified in repository URL, OCI is assumed
+#   - Nested package paths are supported (e.g., test::test::hello)
 
 # include
 # Attempts to include a specified function from a given package.
@@ -140,9 +142,11 @@ function preprocess() {
   local line
   while IFS= read -r line; do
     case "$line" in
+      *#*::*) echo "$line" 1;;
       *::*)
         local include
-        grep -Eo '[a-zA-Z0-9_]+::[a-zA-Z0-9_]+' <<< "$line" |
+
+        grep -Eo '[a-zA-Z0-9_]+(::[a-zA-Z0-9_]+)+' <<< "$line" |
           while read include; do include_once ${include//::/\/}; done
         echo "$line"
       ;;

bashpp-gh

@@ -7,15 +7,17 @@
 #   This script serves as an extension handler for bashpp to pull packages from GitHub releases.
 #   When bashpp encounters a GitHub repository URL (gh:// prefix), it delegates the package
 #   retrieval to this handler. The handler downloads the latest release asset, extracts the
-#   specified include file, and installs it to the appropriate directory.
+#   specified include file, and installs it to the appropriate directory. It supports nested
+#   package paths and maintains proper directory structure.
 #
 # Usage:
 #   bashpp-gh <repository> <include>
 #   Called automatically by bashpp when processing GitHub repository URLs
 #
 # Parameters:
 #   repository - The GitHub repository in the format "owner/repo"
-#   include    - The path to the file to include, in the format "package/function"
+#   include    - The path to the file to include, in the format "package/function" or
+#               "package/subpackage/function" for nested paths
 #
 # Outputs:
 #   No direct output, but creates files in the cache directory and include directory.
@@ -26,6 +28,8 @@
 #   Requires either GH_TOKEN or GITHUB_TOKEN environment variable for GitHub API access.
 #   Will create cache directories as needed at BASHP_CACHE_DIR, XDG_CACHE_HOME/bashp or
 #   ~/.cache/bashp.
+#   Supports nested package paths and maintains proper directory structure.
+#   Git integration has been improved to handle nested paths correctly.
 
 declare -r INCLUDE_DIR=${INCLUDE_DIR:-${INCLUDE_DIR:?must be set}}
 declare -r repository=${1:-${repository:?must be set}}
@@ -59,7 +63,7 @@ mkdir -p "$INCLUDE_DIR/$package"
 cp "$cache/$include" "$INCLUDE_DIR/$include"
 
 if command -v git &>/dev/null && git rev-parse --is-inside-work-tree &>/dev/null; then
-  declare -r function=${include##*/}
+  declare -r function=${include#*/}
   declare -r gitignore="$INCLUDE_DIR/$package/.gitignore"
   grep -q "^$function$" "$gitignore" 2>/dev/null || echo "$function" >> "$gitignore"
 fi

bashpp-oci

@@ -5,18 +5,19 @@
 #
 # Description:
 #   This script serves as an extension handler for bashpp to pull packages from OCI container
-#   images.
-#   When bashpp encounters an OCI repository URL (default or oci:// prefix), it delegates the
-#   package retrieval to this handler. The handler pulls the package, extracts the specified
-#   include file, and installs it to the appropriate directory.
+#   images. When bashpp encounters an OCI repository URL (default or oci:// prefix), it delegates
+#   the package retrieval to this handler. The handler pulls the package, extracts the specified
+#   include file, and installs it to the appropriate directory. It supports nested package paths
+#   and maintains proper directory structure.
 #
 # Usage:
 #   bashpp-oci <repository> <include>
 #   Called automatically by bashpp when processing OCI repository URLs
 #
 # Parameters:
 #   repository - The OCI repository containing the package image
-#   include    - The path to the file to include, in the format "package/function"
+#   include    - The path to the file to include, in the format "package/function" or
+#               "package/subpackage/function" for nested paths
 #
 # Outputs:
 #   No direct output, but creates files in the include directory and updates .gitignore
@@ -27,6 +28,8 @@
 #   The OCI client can be configured using the OCI_CLIENT environment variable.
 #   The image is expected to be tagged as 'latest' and follow the naming convention
 #   'repository/bashp-package:latest'.
+#   Supports nested package paths and maintains proper directory structure.
+#   Git integration has been improved to handle nested paths correctly.
 
 declare -r INCLUDE_DIR=${INCLUDE_DIR:-${INCLUDE_DIR:?must be set}}
 declare -r repository=${1:-${repository:?must be set}}
@@ -38,7 +41,7 @@ command -v "$ociClient" &>/dev/null || exit 1
 declare -r package=${include%%/*}
 declare -r image="$repository/bashp-$package:latest"
 if "$ociClient" manifest inspect "$image" &>/dev/null; then
-  mkdir -p "$INCLUDE_DIR/$package"
+  mkdir -p "$INCLUDE_DIR/$(dirname "$include")"
 
   id=$("$ociClient" create "$image" none)
   declare -r id
@@ -49,7 +52,7 @@ if "$ociClient" manifest inspect "$image" &>/dev/null; then
   "$ociClient" cp "$id:/$include" "$INCLUDE_DIR/$include"
 
   if command -v git &>/dev/null && git rev-parse --is-inside-work-tree &>/dev/null; then
-    declare -r function=${include##*/}
+    declare -r function=${include#*/}
     declare -r gitignore="$INCLUDE_DIR/$package/.gitignore"
     grep -q "^$function$" "$INCLUDE_DIR/$package/.gitignore" 2>/dev/null ||
       echo "$function" >> "$gitignore"

hello-world.sh

@@ -6,7 +6,18 @@
 #include test/hello
 test::hello
 
+#include test/test/hello
+test::test::hello
+
 # Option 2
 # Rely on auto-include based on naming-convention "<package>::<function>"
 
 test::hello_world
+
+# Option 3
+# Use nested package paths for better organization
+
+#include test/test/hello
+test::test::hello
+
+test::test::hello_world

libs/test/test/hello

@@ -0,0 +1,5 @@
+# shellcheck shell=bash
+
+function test::test::hello() {
+    echo "Hey there, says the sub-package"
+}

libs/test/test/hello_world

@@ -0,0 +1,5 @@
+# shellcheck shell=bash
+
+function test::test::hello_world() {
+    echo "Hello World, says the sub-package"
+}