# Example: Including z_Output in your script
function z_Output() {
  # Copy function implementation from src/_Z_Utils.zsh
}

# Then use it
z_Output info "Starting script execution..."

# Option 1: Source with absolute path
source /path/to/_Z_Utils.zsh

# Option 2: Source with dynamic path detection (more portable)
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
source "${SCRIPT_DIR}/path/to/_Z_Utils.zsh"

# Then use any function
z_Output info "Starting script execution..."
z_Ensure_Parent_Path_Exists "/path/to/output/file.txt"

# Using a specific utility script
./src/examples/setup_git_inception_repo.sh /path/to/new/repo

# Using test verification functions
source ./src/function_tests/z_Output_test.sh

# Basic output examples
z_Output info "Processing file: $filename"
z_Output warn "Disk space is low"
z_Output error "Failed to connect to server"
z_Output debug "Variable value: $value"

# Prompt example
UserInput=$(z_Output prompt "Enter your name" Default="User")

# Problem: Inconsistent user feedback in complex scripts
# Solution: Centralized output management with z_Output

# Initialize output options
typeset -g Output_Color_Enabled=$TRUE
typeset -g Output_Verbose_Mode=$TRUE

# Process stages with consistent feedback
z_Output info "Stage 1: Validating inputs..."
z_Output debug "Input parameters: $@"

if [[ -z "$required_parameter" ]]; then
  z_Output error "Missing required parameter"
  exit 1
fi

z_Output success "Stage 1 complete"
z_Output info "Stage 2: Processing data..."

# Control verbosity for different environments
if [[ "$CI_MODE" == "true" ]]; then
  Output_Verbose_Mode=$FALSE  # Less output in CI environments
fi

if [[ ! -f "$config_file" ]]; then
  z_Report_Error "Configuration file not found: $config_file" $Exit_Status_IO
  return $?
fi

# Problem: Error handling across multiple function calls is inconsistent
# Solution: Standardized error reporting and propagation

# Define error codes
typeset -gi Exit_Status_Success=0
typeset -gi Exit_Status_Error=1
typeset -gi Exit_Status_IO=2
typeset -gi Exit_Status_Invalid_Argument=3

function validate_input() {
  local input="$1"
  
  if [[ -z "$input" ]]; then
    z_Report_Error "Input cannot be empty" $Exit_Status_Invalid_Argument
    return $?  # Propagate error code
  fi
  
  if [[ ! -f "$input" ]]; then
    z_Report_Error "Input file does not exist: $input" $Exit_Status_IO
    return $?  # Propagate error code
  fi
  
  return $Exit_Status_Success
}

# Calling function with error propagation
validate_input "$user_input"
if [[ $? -ne $Exit_Status_Success ]]; then
  # Error already reported by z_Report_Error
  exit $?
fi

# Initialize script environment
z_Setup_Environment || exit $?

# Problem: Scripts behave differently across various environments
# Solution: Standardized environment setup with safety measures

#!/usr/bin/env zsh
# My script that needs to work consistently

# Source Z_Utils for environment setup
source "$(dirname "$0")/_Z_Utils.zsh"

# Initialize environment with safety settings
z_Setup_Environment || exit $?
# Now we have:
# - set -e (exit on error)
# - set -u (error on undefined variables) 
# - IFS standardized
# - PATH sanitized
# - Terminal capabilities detected
# - Color support identified
# - Core environment variables defined

# Script can now run with consistent behavior
process_files "$@"

# Define required tools
typeset -a RequiredTools=("git" "ssh" "jq")
typeset -a OptionalTools=("gh" "fzf")

# Check dependencies
z_Check_Dependencies "RequiredTools" "OptionalTools" || exit $?

# Problem: Scripts fail in unpredictable ways when dependencies aren't available
# Solution: Upfront dependency verification with clear error messages

#!/usr/bin/env zsh
# Script that relies on external tools

# Source Z_Utils
source "$(dirname "$0")/_Z_Utils.zsh"

# Define dependencies with descriptive names
typeset -a RequiredTools=(
  "git:Required for repository operations"
  "ssh:Required for secure connections"
  "gpg:Required for signing commits"
)

typeset -a OptionalTools=(
  "gh:GitHub CLI for enhanced GitHub integration"
  "fzf:Interactive selection capabilities"
)

# Check dependencies - providing array names, not values
z_Check_Dependencies "RequiredTools" "OptionalTools" || exit $?

# Now we can safely use dependencies, and know which optional tools are available
if [[ $HAS_fzf -eq $TRUE ]]; then
  # Use interactive selection with fzf
  SELECTED_FILE=$(find . -type f | fzf --prompt="Select file: ")
else
  # Fallback to basic selection
  echo "Available files:"
  find . -type f | nl
  echo "Enter number: "
  read file_number
  SELECTED_FILE=$(find . -type f | sed -n "${file_number}p")
fi

# Ensure directory exists before writing file
z_Ensure_Parent_Path_Exists "/path/to/output/file.txt" || exit $?

# Get user-friendly path
RelativePath=$(z_Convert_Path_To_Relative "/long/absolute/path/file.txt")

# Problem: File operations fail inconsistently due to missing directories
# Solution: Integrated path validation and creation

#!/usr/bin/env zsh
# Script that writes log files to nested directories

# Source Z_Utils
source "$(dirname "$0")/_Z_Utils.zsh"

# Define log file path with nested directories
LOG_DIR="${HOME}/logs/$(date +%Y)/$(date +%m)/$(date +%d)"
LOG_FILE="${LOG_DIR}/process.log"

# Safely ensure parent directories exist
z_Ensure_Parent_Path_Exists "$LOG_FILE" || exit $?
# Now we can safely write to the log file, knowing all parent directories exist

# For user-friendly output, convert to relative path
DISPLAY_PATH=$(z_Convert_Path_To_Relative "$LOG_FILE")
z_Output info "Writing log to $DISPLAY_PATH"

# Write the log file
echo "Log entry: $(date)" >> "$LOG_FILE"

# Set up cleanup trap
typeset -g Script_Running=$TRUE
trap 'z_Cleanup $FALSE "Script interrupted"' INT TERM
trap 'z_Cleanup $TRUE' EXIT

# Problem: Scripts leave behind temporary files when interrupted
# Solution: Robust trap-based cleanup mechanism

#!/usr/bin/env zsh
# Script that creates temporary resources

# Source Z_Utils
source "$(dirname "$0")/_Z_Utils.zsh"

# Initialize cleanup tracking
typeset -g Script_Running=$TRUE
typeset -a Temp_Files=()

# Register cleanup handlers
trap 'z_Cleanup $FALSE "Script interrupted"' INT TERM
trap 'z_Cleanup $TRUE' EXIT

# Create temporary file that will be automatically cleaned up
TEMP_CONFIG=$(mktemp)
Temp_Files+=("$TEMP_CONFIG")

# Create temporary directory
TEMP_DIR=$(mktemp -d)
Temp_Files+=("$TEMP_DIR")

# Even if the script fails here, cleanup will still happen
process_data "$TEMP_CONFIG" "$TEMP_DIR"

# Define cleanup function that z_Cleanup will call
function cleanup_Handler() {
  local success=$1
  
  # Custom cleanup logic
  if [[ -n "$DB_CONNECTION" ]]; then
    close_database_connection "$DB_CONNECTION"
  fi
  
  # Return success status
  return $success
}