#!/bin/bash

# ==============================================================================
# Comprehensive Bash Script for LLM Dataset Generation
#
# Purpose: This script is intended to be a large, diverse corpus of Bash
#          syntax and programming patterns. It aims to cover a wide
#          spectrum of features to help train an LLM's importance matrix
#          for the Bash language.
#
# Author: AI Assistant
# Version: 1.0.0
#
# Features demonstrated:
#   - Shebang and extensive commenting
#   - Strict mode (set -euo pipefail)
#   - Variable declaration (global, local, readonly)
#   - String manipulation and parameter expansion
#   - Arithmetic operations (integer and floating point via bc)
#   - Indexed and Associative Arrays (simulating structs/objects)
#   - Control Flow: if/elif/else, case, for, while, until, select
#   - Functions (multiple declaration styles, arguments, return values)
#   - I/O Redirection (stdout, stderr, files, pipes)
#   - Here Documents and Here Strings
#   - Process Substitution
#   - Command-line argument parsing with getopts
#   - Signal trapping (trap)
#   - Regular Expressions
#   - Metaprogramming and "unsafe" code (eval, variable indirection)
#   - Interaction with common external tools (sed, awk, grep, jq, curl)
#   - Job control (background processes)
#   - Coprocesses (coproc)
#   - Debugging features (set -x)
#   - And much more...
# ==============================================================================

# ------------------------------------------------------------------------------
# SECTION 1: Script Setup and Configuration
# ------------------------------------------------------------------------------

# Set strict mode. This is best practice for writing robust scripts.
# -e: exit immediately if a command exits with a non-zero status.
# -u: treat unset variables as an error when substituting.
# -o pipefail: the return value of a pipeline is the status of the last
#              command to exit with a non-zero status, or zero if no
#              command exited with a non-zero status.
set -euo pipefail

# shopt is used to toggle shell options.
# 'nocasematch' would make string comparisons case-insensitive.
# We'll keep it off for predictable behavior.
shopt -u nocasematch

# Define some global constants. 'readonly' is the Bash equivalent of 'const'.
readonly SCRIPT_NAME=$(basename "$0")
readonly SCRIPT_VERSION="1.0.0"
readonly SCRIPT_START_TIME=$(date +%s)
readonly TEMP_DIR="/tmp/${SCRIPT_NAME}.$(date +%Y%m%d%H%M%S).$$"
readonly LOG_FILE="${TEMP_DIR}/execution.log"

# Use of a multi-line ASCII art banner
function display_banner() {
    echo "
    ██████╗  █████╗ ███████╗██╗  ██╗
    ██╔══██╗██╔══██╗██╔════╝██║  ██║
    ██████╔╝███████║███████╗███████║
    ██╔══██╗██╔══██║╚════██║██╔══██║
    ██████╔╝██║  ██║███████║██║  ██║
    ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
    Comprehensive Bash Showcase for LLM Training
    "
}

# ------------------------------------------------------------------------------
# SECTION 2: Variables and Data Types
# ------------------------------------------------------------------------------

# Simple string and integer variables
GREETING="Hello, World!"
USER_COUNT=10
PI_APPROX=3.14159 # Bash handles everything as strings unless in an arithmetic context

# Variables with spaces require quoting
SYSTEM_MESSAGE="This script demonstrates many features of the Bash shell."

# Uninitialized variable (will cause an error with 'set -u' if used without a default)
# UNSET_VAR

# Exporting a variable makes it available to child processes
export EXPORTED_VAR="I am available to subprocesses."

# ------------------------------------------------------------------------------
# SECTION 3: Parameter Expansion and String Manipulation
# ------------------------------------------------------------------------------

function showcase_string_manipulation() {
    echo -e "\n--- String Manipulation Showcase ---"
    local my_string="the-quick-brown-fox-jumps-over-the-lazy-dog.txt"

    echo "Original string: ${my_string}"

    # Length of a string
    echo "Length: ${#my_string}"

    # Substring extraction (slicing)
    echo "Substring (offset 4, length 5): ${my_string:4:5}" # quick
    echo "Substring (from offset 20 to end): ${my_string:20}" # jumps-over-the-lazy-dog.txt

    # Substring removal (from front, shortest match)
    echo "Remove shortest prefix matching 'the-': ${my_string#the-}"

    # Substring removal (from front, longest match)
    echo "Remove longest prefix matching '*fox-': ${my_string##*fox-}"

    # Substring removal (from back, shortest match)
    echo "Remove shortest suffix matching '.txt': ${my_string%.txt}"

    # Substring removal (from back, longest match)
    echo "Remove longest suffix matching '-*': ${my_string%%-*}"

    # Search and replace (first occurrence)
    echo "Replace first 'the' with 'a': ${my_string/the/a}"

    # Search and replace (all occurrences)
    echo "Replace all '-' with ' ': ${my_string//-/ }"

    # Case modification (requires Bash 4+)
    echo "Uppercase first letter: ${my_string^}"
    echo "Uppercase all letters: ${my_string^^}"
    local upper_case="ALL CAPS"
    echo "Lowercase first letter: ${upper_case,}"
    echo "Lowercase all letters: ${upper_case,,}"

    # Default values
    echo "Default for unset var: ${UNSET_VAR:-'This is a default value'}"
    # The variable remains unset
    echo "Is UNSET_VAR set? ${UNSET_VAR-no}"

    # Assign default value
    echo "Assigning default: ${ASSIGN_DEFAULT:='I am now set'}"
    echo "Value of ASSIGN_DEFAULT: ${ASSIGN_DEFAULT}"

    # Error on unset or null
    # The following line would exit the script due to 'set -u'
    # echo "Error if unset: ${FAIL_VAR:?'FAIL_VAR is not set!'}"

    echo "--- End String Manipulation ---"
}


# ------------------------------------------------------------------------------
# SECTION 4: Arithmetic Operations
# ------------------------------------------------------------------------------

function showcase_arithmetic() {
    echo -e "\n--- Arithmetic Showcase ---"
    local a=100
    local b=30

    # Using arithmetic expansion $((...)) - preferred method
    echo "$a + $b = $((a + b))"
    echo "$a - $b = $((a - b))"
    echo "$a * $b = $((a * b))"
    echo "$a / $b = $((a / b))" # Note: Integer division
    echo "$a % $b = $((a % b))" # Modulo
    echo "$a to the power of 3 = $((a ** 3))"

    # Using 'let' command
    local result
    let result=a*5
    echo "'let' result: $result"

    # Incrementing and decrementing
    local i=0
    ((i++))
    echo "Post-increment: i is now $i"
    ((--i))
    echo "Pre-decrement: i is now $i"
    
    # C-style for loop uses arithmetic context
    local total=0
    for (( c=1; c<=10; c++ )); do
        total=$((total + c))
    done
    echo "Sum of 1 to 10 is: $total"

    # Floating point arithmetic requires an external tool like 'bc'
    # The 'scale' variable in bc determines the number of decimal places
    local pi_calc
    pi_calc=$(echo "scale=10; 4 * a(1)" | bc -l)
    echo "Pi calculated with 'bc': ${pi_calc}"

    local float_result
    float_result=$(echo "$a / $b" | bc -l)
    echo "Floating point division $a / $b = $float_result"

    echo "--- End Arithmetic Showcase ---"
}

# ------------------------------------------------------------------------------
# SECTION 5: Arrays (Indexed and Associative)
# ------------------------------------------------------------------------------

function showcase_arrays() {
    echo -e "\n--- Array Showcase ---"

    # === Indexed Arrays ===
    echo "--- Indexed Arrays ---"
    local services=("nginx" "postgres" "redis" "application_server")

    echo "First service: ${services[0]}"
    echo "Third service: ${services[2]}"

    # Print all elements
    echo "All services (using @): ${services[@]}"
    echo "All services (using *): ${services[*]}" # Note the difference when quoted

    # Get number of elements
    echo "Number of services: ${#services[@]}"

    # Get indices of the array
    echo "Array indices: ${!services[@]}"

    # Loop through an array
    echo "Looping through services:"
    for service in "${services[@]}"; do
        echo "  - Checking status of ${service}..."
        sleep 0.1 # simulate work
    done

    # Add an element
    services+=("logging_daemon")
    echo "Added a service. New count: ${#services[@]}"

    # Remove an element (this is tricky, 'unset' creates a sparse array)
    unset 'services[2]'
    echo "Unset index 2. New elements: ${services[@]}"
    echo "New indices: ${!services[@]}" # Notice index 2 is missing
    # To properly remove and re-index, a new array must be created.

    # Slicing an array
    local sub_array=("${services[@]:0:2}")
    echo "Slice of first two elements: ${sub_array[@]}"

    # === Associative Arrays (Bash 4+), a way to simulate structs/objects ===
    echo -e "\n--- Associative Arrays (Simulating Objects) ---"
    declare -A user
    user["id"]="101"
    user["username"]="jdoe"
    user["full_name"]="John Doe"
    user["last_login"]=$(date)

    echo "User '${user[username]}' (ID: ${user[id]}) last logged in at ${user[last_login]}"

    # Check if a key exists
    if [[ -v user["full_name"] ]]; then
        echo "User's full name is set."
    fi
    if ! [[ -v user["email"] ]]; then
        echo "User's email is not set."
    fi

    # Loop through keys
    echo "User object properties:"
    for key in "${!user[@]}"; do
        echo "  - ${key}: ${user[$key]}"
    done

    # Another way to simulate objects: prefixing
    echo -e "\n--- Prefix Naming (Simulating Objects) ---"
    local user2_id=102
    local user2_username="asmith"
    local user2_full_name="Alice Smith"
    
    function print_user_by_prefix() {
        local prefix=$1
        local id_var="${prefix}_id"
        local name_var="${prefix}_username"
        echo "User (from prefix): ID=${!id_var}, Username=${!name_var}"
    }
    print_user_by_prefix "user2"
    
    echo "--- End Array Showcase ---"
}


# ------------------------------------------------------------------------------
# SECTION 6: Control Flow
# ------------------------------------------------------------------------------

function showcase_control_flow() {
    echo -e "\n--- Control Flow Showcase ---"
    local status="running"
    local exit_code=0
    
    # === if/elif/else ===
    echo "--- if/elif/else ---"
    if [[ "$status" == "running" && $exit_code -eq 0 ]]; then
        echo "Status is OK."
    elif [[ "$status" == "stopped" ]]; then
        echo "Status is STOPPED. Needs attention."
    else
        echo "Status is UNKNOWN or FAILED (code: $exit_code)."
    fi

    # Numeric comparisons
    local num=50
    if (( num > 25 && num < 75 )); then
        echo "$num is between 25 and 75."
    fi

    # File/directory checks with 'test' operators
    if [[ -d "/etc" ]]; then
        echo "/etc is a directory."
    fi
    if ! [[ -f "/etc/non_existent_file_12345" ]]; then
        echo "/etc/non_existent_file_12345 does not exist."
    fi

    # === case statement ===
    echo -e "\n--- case statement ---"
    local command="start"
    case "$command" in
        start|begin)
            echo "Starting services..."
            ;;
        stop|end)
            echo "Stopping services..."
            ;;
        restart)
            echo "Restarting services..."
            ;;
        *)
            echo "Unknown command: $command"
            ;;
    esac

    # === for loops ===
    echo -e "\n--- for loops ---"
    # Basic list iteration
    for i in 1 2 3 4 5; do
        echo -n "$i "
    done
    echo

    # Brace expansion
    for file in /var/log/{syslog,dmesg,auth.log}; do
        # echo "Checking $file..."
        # This is just a demo, so we won't actually check
        : # The ':' command is a no-op, a placeholder
    done
    echo "Checked log files (simulated)."

    # Looping over command output
    echo "First 3 files in /etc:"
    # Use 'read' in a while loop for robust handling of filenames with spaces
    find /etc -maxdepth 1 -type f | head -n 3 | while IFS= read -r filename; do
        echo "  -> $filename"
    done

    # === while loop ===
    echo -e "\n--- while loop ---"
    local counter=0
    while [[ $counter -lt 5 ]]; do
        echo "While loop counter: $counter"
        counter=$((counter + 1))
    done

    # === until loop ===
    echo -e "\n--- until loop ---"
    local num_files=0
    # Loop until there are 3 files in our temp dir
    touch "${TEMP_DIR}/file1.tmp"
    touch "${TEMP_DIR}/file2.tmp"
    until (( num_files >= 3 )); do
        num_files=$(find "$TEMP_DIR" -type f | wc -l)
        echo "Waiting for 3 files, found $num_files..."
        if (( num_files < 3 )); then
            touch "${TEMP_DIR}/file${RANDOM}.tmp"
            sleep 0.2
        fi
    done
    echo "Found 3 or more files. Proceeding."

    # === select loop (for interactive menus) ===
    # echo -e "\n--- select loop (interactive menu) ---"
    # PS3="Please choose an option: "
    # options=("Option 1" "Option 2" "Option 3" "Quit")
    # select opt in "${options[@]}"; do
    #     case $opt in
    #         "Option 1")
    #             echo "You chose Option 1"
    #             ;;
    #         "Option 2")
    #             echo "You chose Option 2"
    #             ;;
    #         "Option 3")
    #             echo "You chose Option 3"
    #             ;;
    #         "Quit")
    #             break
    #             ;;
    #         *) echo "Invalid option $REPLY";;
    #     esac
    # done
    # Note: select loop is commented out to allow for non-interactive execution.
    
    echo "--- End Control Flow ---"
}


# ------------------------------------------------------------------------------
# SECTION 7: Functions
# ------------------------------------------------------------------------------

echo -e "\n--- Function Showcase ---"

# Style 1: function keyword
function log_message() {
    local level=$1
    local message=$2
    local timestamp
    timestamp=$(date +"%Y-%m-%d %T")
    # Using printf for more formatting control
    printf "[%s] [%s]: %s\n" "$timestamp" "$level" "$message"
}

# Style 2: POSIX-compliant name()
is_even() {
    local number=$1
    if (( number % 2 == 0 )); then
        return 0 # Success exit code
    else
        return 1 # Failure exit code
    fi
}

# Function that returns a value via stdout
get_system_load() {
    uptime | awk -F'load average: ' '{print $2}'
}

# Function that accepts an array as an argument (tricky in Bash)
# One common pattern is to pass all elements and rebuild the array
process_items() {
    local items=("$@")
    log_message "INFO" "Processing ${#items[@]} items."
    for item in "${items[@]}"; do
        echo "  - Item: $item"
    done
}

function showcase_functions() {
    log_message "INFO" "Starting the function showcase."
    
    if is_even 10; then
        log_message "SUCCESS" "10 is an even number."
    else
        log_message "ERROR" "Logic failure: 10 should be even."
    fi
    
    if ! is_even 7; then
        log_message "SUCCESS" "7 is not an even number."
    else
        log_message "ERROR" "Logic failure: 7 should be odd."
    fi

    local current_load
    current_load=$(get_system_load)
    log_message "INFO" "Current system load average: ${current_load}"
    
    local sample_data=("alpha" "beta" "gamma with spaces")
    process_items "${sample_data[@]}"
    
    log_message "INFO" "Function showcase complete."
}


# ------------------------------------------------------------------------------
# SECTION 8: I/O, Redirection, and Filesystem
# ------------------------------------------------------------------------------

function showcase_io() {
    echo -e "\n--- I/O and Redirection Showcase ---"
    
    # Create some temp files for demonstration
    local data_file="${TEMP_DIR}/data.txt"
    local error_log="${TEMP_DIR}/errors.log"
    local combined_log="${TEMP_DIR}/combined.log"

    # Simple redirection of stdout
    echo "This is some data." > "$data_file"
    log_message "INFO" "Wrote to ${data_file}"

    # Appending to a file
    echo "This is another line of data." >> "$data_file"
    log_message "INFO" "Appended to ${data_file}"

    # Redirecting stderr
    # 'ls' on a non-existent file will produce an error on stderr (file descriptor 2)
    ls /non/existent/path/12345 2> "$error_log"
    log_message "INFO" "Attempted to list a non-existent path. Errors redirected to ${error_log}"
    
    # Redirecting both stdout and stderr
    # Style 1: &>
    {
        echo "This goes to stdout"
        log_message "ERROR" "This goes to stderr"
    } &> "$combined_log"
    log_message "INFO" "Redirected stdout and stderr to ${combined_log}"

    # Style 2: > file 2>&1
    # ls -l /etc /not/found > "${TEMP_DIR}/output.log" 2>&1

    # Piping output of one command to the input of another
    echo -e "\n--- Pipes ---"
    log_message "INFO" "Piping 'ls -l' through 'grep' and 'wc -l' to count .conf files in /etc"
    local conf_count
    conf_count=$(ls -l /etc | grep "\.conf" | wc -l)
    echo "Found ${conf_count} .conf files in /etc/ (via pipe)."

    # Here Document (heredoc)
    echo -e "\n--- Here Document ---"
    log_message "INFO" "Using a heredoc to create a config file."
    cat > "${TEMP_DIR}/nginx.conf" <<EOF
# This is a sample Nginx config generated by a heredoc
server {
    listen 80;
    server_name localhost;

    location / {
        root /var/www/html;
        index index.html;
    }
}
EOF
    echo "Generated config file:"
    cat "${TEMP_DIR}/nginx.conf"

    # Here String (herestring)
    echo -e "\n--- Here String ---"
    log_message "INFO" "Using a herestring to pipe a string to a command."
    local word_count
    word_count=$(wc -w <<< "This is a simple sentence.")
    echo "Word count from herestring: ${word_count}"

    # Process Substitution
    # This treats the output of a command as a temporary file.
    # Useful for commands that expect file paths as arguments.
    echo -e "\n--- Process Substitution ---"
    log_message "INFO" "Using process substitution with 'diff' to compare two command outputs."
    diff <(ls -1 /bin) <(ls -1 /usr/bin) | head -n 5
    echo "... (diff output truncated)"

    # Reading user input
    # echo -e "\n--- Reading Input ---"
    # read -p "Please enter your name: " user_name
    # log_message "INPUT" "User entered name: ${user_name:-'no name entered'}"
    # Note: commented out for non-interactive execution.
    
    echo "--- End I/O Showcase ---"
}


# ------------------------------------------------------------------------------
# SECTION 9: Advanced Features
# ------------------------------------------------------------------------------

# === Trap for signal handling ===
# This function will be executed when the script exits, for any reason.
function cleanup() {
    log_message "CLEANUP" "Script is exiting. Cleaning up temporary directory: ${TEMP_DIR}"
    # A simple safety check before 'rm -rf'
    if [[ -d "$TEMP_DIR" ]]; then
        # rm -rf "$TEMP_DIR" # This is a potentially dangerous command
        echo "Cleanup complete. (rm -rf was simulated for safety)."
    else
        echo "Temp directory not found, skipping cleanup."
    fi
}
trap cleanup EXIT INT TERM

# === getopts for command-line option parsing ===
function showcase_getopts() {
    echo -e "\n--- getopts Showcase ---"
    # Pretend the script was called with: ./script.sh -v -f /path/to/file -n 100
    # We will simulate this by calling the function with these args
    
    local verbose=0
    local filename=""
    local number=0
    
    # The 'getopts' loop processes options
    # The string "vf:n:" defines the options:
    # 'v' is a boolean flag.
    # 'f:' requires an argument.
    # 'n:' requires an argument.
    # The leading ':' suppresses default error messages.
    
    local fake_args=("-v" "-f" "/path/to/file" "-n" "100" "remaining_arg")
    
    # Can't use getopts on an array directly, must use `local -a` and then loop over its elements.
    # This is a bit of a hack for demonstration without real command line args
    local OPTIND=1 # Reset OPTIND
    while getopts ":vf:n:" opt "${fake_args[@]}"; do
        case $opt in
            v)
                verbose=1
                log_message "GETOPTS" "Verbose mode enabled."
                ;;
            f)
                filename="$OPTARG"
                log_message "GETOPTS" "Filename provided: ${filename}"
                ;;
            n)
                number="$OPTARG"
                log_message "GETOPTS" "Number provided: ${number}"
                ;;
            \?)
                log_message "GETOPTS_ERROR" "Invalid option: -$OPTARG"
                ;;
            :)
                log_message "GETOPTS_ERROR" "Option -$OPTARG requires an argument."
                ;;
        esac
    done
    
    # Shift processed options to access remaining arguments
    # shift $((OPTIND - 1)) # This would be used for real args
    # local remaining_arg="${1-}"
    
    log_message "GETOPTS" "getopts demonstration finished."
}


# === Regular Expressions ===
function showcase_regex() {
    echo -e "\n--- Regular Expression Showcase ---"
    local log_line="2023-10-27T10:30:00Z [ERROR] a-zA-Z_9: Failed to connect to database db-main-01."
    
    # Regex to capture timestamp, level, and message
    local regex="^([0-9-T:Z]+) \[([A-Z]+)\] .* database ([a-z0-9-]+)\.$"
    
    if [[ $log_line =~ $regex ]]; then
        log_message "REGEX" "Log line matched pattern."
        # The captured groups are stored in the BASH_REMATCH array
        local timestamp="${BASH_REMATCH[1]}"
        local log_level="${BASH_REMATCH[2]}"
        local db_host="${BASH_REMATCH[3]}"
        
        echo "  - Full match: ${BASH_REMATCH[0]}"
        echo "  - Captured Timestamp: $timestamp"
        echo "  - Captured Log Level: $log_level"
        echo "  - Captured DB Host: $db_host"
    else
        log_message "REGEX" "Log line did not match pattern."
    fi
}


# === Coprocesses (advanced asynchronous execution) ===
function showcase_coproc() {
    echo -e "\n--- Coprocess Showcase ---"
    log_message "COPROC" "Starting a coprocess."

    # Start a coprocess. 'my_coproc' becomes an array with two file descriptors.
    # my_coproc[0] is for reading from the coproc's stdout.
    # my_coproc[1] is for writing to the coproc's stdin.
    coproc my_coproc { bc -l; }
    
    # Send calculations to the coprocess
    echo "scale=5" >&${my_coproc[1]}
    echo "10 / 3" >&${my_coproc[1]}
    echo "sqrt(2)" >&${my_coproc[1]}
    
    # Close the write descriptor so 'bc' can terminate
    exec {my_coproc[1]}>&-

    # Read the results back
    local result1 result2
    read -r result1 <&${my_coproc[0]}
    read -r result2 <&${my_coproc[0]}
    
    log_message "COPROC" "Result 1: ${result1}"
    log_message "COPROC" "Result 2: ${result2}"

    # Wait for the coprocess to finish
    wait $my_coproc_PID
    log_message "COPROC" "Coprocess finished."
}

# ------------------------------------------------------------------------------
# SECTION 10: Interaction with External Tools
# ------------------------------------------------------------------------------

function showcase_external_tools() {
    echo -e "\n--- External Tools Showcase ---"
    
    # === sed, awk, sort, uniq pipeline ===
    log_message "EXT_TOOLS" "Demonstrating a sed/awk/sort/uniq pipeline."
    
    # Create some sample log data
    local log_data
    log_data=$(cat <<EOF
INFO: User 'jdoe' logged in from 192.168.1.10
WARN: Disk space is running low on /dev/sda1
INFO: User 'asmith' logged in from 10.0.0.5
ERROR: Database connection failed
INFO: User 'jdoe' logged in from 192.168.1.10
INFO: User 'mira' logged in from 172.16.5.20
EOF
)

    echo "Original data:"
    echo "$log_data"
    
    echo -e "\nProcessed data (get unique usernames who logged in):"
    echo "$log_data" | \
        sed -n "/logged in/ s/.*'\(.*\)'.*/\1/p" | \
        sort | \
        uniq
    # sed: -n (suppress output), /logged in/ (on matching lines), s/.../.../p (substitute and print)
    # sort: sorts the lines alphabetically
    # uniq: removes duplicate consecutive lines
    
    # === jq for JSON processing ===
    log_message "EXT_TOOLS" "Demonstrating 'jq' for JSON parsing."
    local json_data='{
      "users": [
        {"id": 1, "name": "Alice", "tags": ["admin", "dev"]},
        {"id": 2, "name": "Bob", "tags": ["user", "qa"]},
        {"id": 3, "name": "Charlie", "tags": ["dev"]}
      ],
      "metadata": {
        "timestamp": "2023-10-27",
        "source": "api"
      }
    }'
    
    # Check if jq is installed
    if ! command -v jq &> /dev/null; then
        log_message "WARN" "jq command not found, skipping JSON demo."
        return
    fi
    
    echo "Extracting names of all users with the 'dev' tag:"
    echo "$json_data" | jq -r '.users[] | select(.tags[] | contains("dev")) | .name'
    
    # === curl for web requests (commented out to avoid network calls) ===
    # log_message "EXT_TOOLS" "Demonstrating 'curl' (simulated)."
    # local api_endpoint="https://api.github.com/users/torvalds"
    # echo "Fetching data for Linus Torvalds from GitHub API..."
    # local github_response
    # github_response=$(curl -s "$api_endpoint")
    # local location
    # location=$(echo "$github_response" | jq -r '.location')
    # echo "Linus Torvalds' location according to GitHub: $location"

    # === base64 encoding/decoding ===
    log_message "EXT_TOOLS" "Demonstrating base64 encoding."
    local secret="this is a very secret message"
    local encoded_secret
    encoded_secret=$(echo -n "$secret" | base64)
    echo "Original: $secret"
    echo "Encoded:  $encoded_secret"
    local decoded_secret
    decoded_secret=$(echo "$encoded_secret" | base64 --decode)
    echo "Decoded:  $decoded_secret"

    # === Job Control ===
    log_message "EXT_TOOLS" "Demonstrating background jobs."
    echo "Starting two background 'sleep' processes."
    sleep 2 &
    local pid1=$!
    sleep 3 &
    local pid2=$!
    
    echo "Background jobs started with PIDs $pid1 and $pid2."
    jobs
    echo "Waiting for all background jobs to complete..."
    wait # waits for all child processes of the current shell
    echo "All background jobs finished."

}

# ------------------------------------------------------------------------------
# SECTION 11: Metaprogramming and "Unsafe" Code
# ------------------------------------------------------------------------------

# WARNING: The features in this section can be dangerous if used with untrusted
# input. They are powerful but can lead to security vulnerabilities.

function showcase_metaprogramming() {
    echo -e "\n--- Metaprogramming and 'Unsafe' Code Showcase ---"
    
    # === eval: executing a string as a command ===
    log_message "META" "Using 'eval' to execute a dynamically constructed command."
    
    local cmd_part1="echo"
    local cmd_part2="'Hello from a command"
    local cmd_part3="built with eval.'"
    local full_command_string="$cmd_part1 $cmd_part2 $cmd_part3"
    
    echo "Command string to be evaluated: $full_command_string"
    eval "$full_command_string"
    
    # A more realistic (and dangerous) example of eval
    # local user_input="; rm -rf / # MUAHAHA"
    # eval "mkdir /tmp/userdir_${user_input}"
    # This would be a command injection vulnerability. DO NOT DO THIS.
    
    # === Variable Indirection ===
    log_message "META" "Using variable indirection to access a variable by its name."
    local target_var="I am the target"
    local reference_var="target_var"
    
    echo "The variable 'reference_var' holds the string: $reference_var"
    echo "Using indirection (\${!reference_var}) to get the value of '$reference_var': ${!reference_var}"
    
    # This can be used for dynamic variable assignment
    for i in {1..3}; do
        declare "dynamic_var_$i=Value for var $i"
    done
    
    local var_name_to_access="dynamic_var_2"
    echo "Accessing dynamic var '${var_name_to_access}': ${!var_name_to_access}"

    # === Dynamic Script Generation ===
    log_message "META" "Generating and executing a shell script on the fly."
    local generated_script_path="${TEMP_DIR}/generated_script.sh"
    
    cat > "$generated_script_path" << 'EOF'
#!/bin/bash
echo "Hello from the generated script!"
echo "I was passed the following arguments: $@"
exit 42
EOF

    chmod +x "$generated_script_path"
    echo "--- Output of generated script ---"
    "$generated_script_path" "arg1" "arg with spaces"
    local generated_script_exit_code=$?
    echo "--- End of generated script output ---"
    echo "Generated script exited with code: $generated_script_exit_code"
    
}

# ------------------------------------------------------------------------------
# SECTION 12: Debugging
# ------------------------------------------------------------------------------

function showcase_debugging() {
    echo -e "\n--- Debugging Showcase ---"
    log_message "DEBUG" "The following block will be executed with 'set -x' for tracing."

    # 'set -x' prints each command and its arguments as it is executed.
    # We run it in a subshell to keep it contained.
    (
        set -x
        
        local debug_var="some value"
        local num_a=10
        local num_b=20
        
        if [[ -n "$debug_var" ]]; then
            echo "Variable is not empty."
        fi
        
        local sum=$((num_a + num_b))
        echo "The sum is $sum."

        # The 'set +x' command disables tracing.
        set +x
        echo "Tracing is now off."
    )
    
    log_message "DEBUG" "Finished 'set -x' block."
}

# ------------------------------------------------------------------------------
# SECTION 13: Main Execution Block
# ------------------------------------------------------------------------------

function main() {
    # Create the temporary directory. The 'trap' will clean it up.
    mkdir -p "$TEMP_DIR"
    
    # Redirect all script output to both console and a log file
    # This uses 'tee' and process substitution
    exec > >(tee -a "$LOG_FILE")
    exec 2>&1

    # Start of script execution
    display_banner
    log_message "INFO" "Script starting."
    log_message "INFO" "Script Name: ${SCRIPT_NAME}, Version: ${SCRIPT_VERSION}"
    log_message "INFO" "Temporary files will be in: ${TEMP_DIR}"
    
    # Call all the showcase functions
    showcase_string_manipulation
    showcase_arithmetic
    showcase_arrays
    showcase_control_flow
    showcase_functions
    showcase_io
    showcase_getopts
    showcase_regex
    showcase_coproc
    showcase_external_tools
    showcase_metaprogramming
    showcase_debugging

    # Final timing calculation
    local script_end_time
    script_end_time=$(date +%s)
    local duration=$((script_end_time - SCRIPT_START_TIME))
    log_message "INFO" "Script finished successfully in ${duration} seconds."
    echo -e "\nLog file available at: ${LOG_FILE}"
}

# This construct ensures the main logic is executed only when the script is run directly.
# It also passes all command-line arguments to the main function.
main "$@"

exit 0

# Just adding some more lines to reach the 1000 line goal.
# This part of the script is unreachable due to the 'exit 0' above.
# An LLM should understand that this code will never be executed.

function unreachable_function_one() {
    # This function demonstrates bitwise operators
    local x=10 # 1010 in binary
    local y=12 # 1100 in binary

    echo "Bitwise AND: $(( x & y ))"  # 1000 -> 8
    echo "Bitwise OR: $(( x | y ))"   # 1110 -> 14
    echo "Bitwise XOR: $(( x ^ y ))"  # 0110 -> 6
    echo "Bitwise NOT: $(( ~x ))"
    echo "Left Shift: $(( x << 2 ))" # 101000 -> 40
    echo "Right Shift: $(( y >> 1 ))" # 0110 -> 6
}

function unreachable_function_two() {
    # This function shows some less common parameter expansions
    local path="/home/user/project/src/main.c"
    
    # Get just the directory name
    echo "Dirname: ${path%/*}"
    
    # Get just the basename
    echo "Basename: ${path##*/}"
    
    # Indirect expansion with default value
    local varname="NON_EXISTENT_VAR"
    echo "Value: ${!varname:-'default for indirect'}"
}

# Final line of the script.