Add docs for all files in /misc

docs/misc/core.func/CORE_USAGE_EXAMPLES.md

@@ -0,0 +1,728 @@
+# core.func Usage Examples
+
+## Overview
+
+This document provides practical usage examples for `core.func` functions, covering common scenarios, integration patterns, and best practices.
+
+## Basic Script Setup
+
+### Standard Script Initialization
+
+```bash
+#!/usr/bin/env bash
+# Standard script setup using core.func
+
+# Source core functions
+source core.func
+
+# Run system checks
+pve_check
+arch_check
+shell_check
+root_check
+
+# Optional: Check SSH connection
+ssh_check
+
+# Set up error handling
+trap 'stop_spinner' EXIT INT TERM
+
+# Your script logic here
+msg_info "Starting script execution"
+# ... script code ...
+msg_ok "Script completed successfully"
+```
+
+### Minimal Script Setup
+
+```bash
+#!/usr/bin/env bash
+# Minimal setup for simple scripts
+
+source core.func
+
+# Basic checks only
+pve_check
+root_check
+
+# Simple execution
+msg_info "Running operation"
+# ... your code ...
+msg_ok "Operation completed"
+```
+
+## Message Display Examples
+
+### Progress Indication
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Show progress with spinner
+msg_info "Downloading package..."
+sleep 2
+msg_ok "Download completed"
+
+msg_info "Installing package..."
+sleep 3
+msg_ok "Installation completed"
+
+msg_info "Configuring service..."
+sleep 1
+msg_ok "Configuration completed"
+```
+
+### Error Handling
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Function with error handling
+install_package() {
+    local package="$1"
+
+    msg_info "Installing $package..."
+
+    if silent apt-get install -y "$package"; then
+        msg_ok "$package installed successfully"
+        return 0
+    else
+        msg_error "Failed to install $package"
+        return 1
+    fi
+}
+
+# Usage
+if install_package "nginx"; then
+    msg_ok "Nginx installation completed"
+else
+    msg_error "Nginx installation failed"
+    exit 1
+fi
+```
+
+### Warning Messages
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Show warnings for potentially dangerous operations
+msg_warn "This will modify system configuration"
+read -p "Continue? [y/N]: " confirm
+
+if [[ "$confirm" =~ ^[yY]$ ]]; then
+    msg_info "Proceeding with modification..."
+    # ... dangerous operation ...
+    msg_ok "Modification completed"
+else
+    msg_info "Operation cancelled"
+fi
+```
+
+### Custom Messages
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Custom message with specific icon and color
+msg_custom "🚀" "\e[32m" "Launching application"
+msg_custom "⚡" "\e[33m" "High performance mode enabled"
+msg_custom "🔒" "\e[31m" "Security mode activated"
+```
+
+### Debug Messages
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Enable debug mode
+export var_full_verbose=1
+
+# Debug messages
+msg_debug "Variable value: $some_variable"
+msg_debug "Function called: $FUNCNAME"
+msg_debug "Current directory: $(pwd)"
+```
+
+## Silent Execution Examples
+
+### Package Management
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Update package lists
+msg_info "Updating package lists..."
+silent apt-get update
+
+# Install packages
+msg_info "Installing required packages..."
+silent apt-get install -y curl wget git
+
+# Upgrade packages
+msg_info "Upgrading packages..."
+silent apt-get upgrade -y
+
+msg_ok "Package management completed"
+```
+
+### File Operations
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Create directories
+msg_info "Creating directory structure..."
+silent mkdir -p /opt/myapp/{config,logs,data}
+
+# Set permissions
+msg_info "Setting permissions..."
+silent chmod 755 /opt/myapp
+silent chmod 644 /opt/myapp/config/*
+
+# Copy files
+msg_info "Copying configuration files..."
+silent cp config/* /opt/myapp/config/
+
+msg_ok "File operations completed"
+```
+
+### Service Management
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Start service
+msg_info "Starting service..."
+silent systemctl start myservice
+
+# Enable service
+msg_info "Enabling service..."
+silent systemctl enable myservice
+
+# Check service status
+msg_info "Checking service status..."
+if silent systemctl is-active --quiet myservice; then
+    msg_ok "Service is running"
+else
+    msg_error "Service failed to start"
+fi
+```
+
+### Network Operations
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Test network connectivity
+msg_info "Testing network connectivity..."
+if silent ping -c 1 8.8.8.8; then
+    msg_ok "Network connectivity confirmed"
+else
+    msg_error "Network connectivity failed"
+fi
+
+# Download files
+msg_info "Downloading configuration..."
+silent curl -fsSL https://example.com/config -o /tmp/config
+
+# Extract archives
+msg_info "Extracting archive..."
+silent tar -xzf /tmp/archive.tar.gz -C /opt/
+```
+
+## System Check Examples
+
+### Comprehensive System Validation
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Complete system validation
+validate_system() {
+    msg_info "Validating system requirements..."
+
+    # Check Proxmox version
+    if pve_check; then
+        msg_ok "Proxmox VE version is supported"
+    fi
+
+    # Check architecture
+    if arch_check; then
+        msg_ok "System architecture is supported"
+    fi
+
+    # Check shell
+    if shell_check; then
+        msg_ok "Shell environment is correct"
+    fi
+
+    # Check privileges
+    if root_check; then
+        msg_ok "Running with sufficient privileges"
+    fi
+
+    # Check SSH connection
+    ssh_check
+
+    msg_ok "System validation completed"
+}
+
+# Run validation
+validate_system
+```
+
+### Conditional System Checks
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Check if running in container
+if [[ -f /.dockerenv ]] || [[ -f /run/.containerenv ]]; then
+    msg_warn "Running inside container"
+    # Skip some checks
+else
+    # Full system checks
+    pve_check
+    arch_check
+fi
+
+# Always check shell and privileges
+shell_check
+root_check
+```
+
+## Header Management Examples
+
+### Application Header Display
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Set application information
+export APP="plex"
+export APP_TYPE="ct"
+
+# Display header
+header_info
+
+# Continue with application setup
+msg_info "Setting up Plex Media Server..."
+```
+
+### Custom Header Handling
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Get header content
+export APP="nextcloud"
+export APP_TYPE="ct"
+
+header_content=$(get_header)
+if [[ -n "$header_content" ]]; then
+    echo "Header found:"
+    echo "$header_content"
+else
+    msg_warn "No header found for $APP"
+fi
+```
+
+## Swap Management Examples
+
+### Interactive Swap Creation
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Check and create swap
+if check_or_create_swap; then
+    msg_ok "Swap is available"
+else
+    msg_warn "No swap available - continuing without swap"
+fi
+```
+
+### Automated Swap Check
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Check swap without prompting
+check_swap_quiet() {
+    if swapon --noheadings --show | grep -q 'swap'; then
+        msg_ok "Swap is active"
+        return 0
+    else
+        msg_warn "No active swap detected"
+        return 1
+    fi
+}
+
+if check_swap_quiet; then
+    msg_info "System has sufficient swap"
+else
+    msg_warn "Consider adding swap for better performance"
+fi
+```
+
+## Spinner Usage Examples
+
+### Long-Running Operations
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Long-running operation with spinner
+long_operation() {
+    msg_info "Processing large dataset..."
+
+    # Simulate long operation
+    for i in {1..100}; do
+        sleep 0.1
+        # Update spinner message periodically
+        if (( i % 20 == 0 )); then
+            SPINNER_MSG="Processing... $i%"
+        fi
+    done
+
+    msg_ok "Dataset processing completed"
+}
+
+long_operation
+```
+
+### Background Operations
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Background operation with spinner
+background_operation() {
+    msg_info "Starting background process..."
+
+    # Start spinner
+    SPINNER_MSG="Processing in background..."
+    spinner &
+    SPINNER_PID=$!
+
+    # Do background work
+    sleep 5
+
+    # Stop spinner
+    stop_spinner
+    msg_ok "Background process completed"
+}
+
+background_operation
+```
+
+## Integration Examples
+
+### With build.func
+
+```bash
+#!/usr/bin/env bash
+# Integration with build.func
+
+source core.func
+source build.func
+
+# Use core functions for system validation
+pve_check
+arch_check
+root_check
+
+# Use build.func for container creation
+export APP="plex"
+export CTID="100"
+# ... container creation ...
+```
+
+### With tools.func
+
+```bash
+#!/usr/bin/env bash
+# Integration with tools.func
+
+source core.func
+source tools.func
+
+# Use core functions for UI
+msg_info "Starting maintenance tasks..."
+
+# Use tools.func for maintenance
+update_system
+cleanup_logs
+optimize_storage
+
+msg_ok "Maintenance completed"
+```
+
+### With error_handler.func
+
+```bash
+#!/usr/bin/env bash
+# Integration with error_handler.func
+
+source core.func
+source error_handler.func
+
+# Use core functions for execution
+msg_info "Running operation..."
+
+# Silent execution will use error_handler for explanations
+silent apt-get install -y package
+
+msg_ok "Operation completed"
+```
+
+## Best Practices Examples
+
+### Error Handling Pattern
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Robust error handling
+run_with_error_handling() {
+    local operation="$1"
+    local description="$2"
+
+    msg_info "$description"
+
+    if silent "$operation"; then
+        msg_ok "$description completed successfully"
+        return 0
+    else
+        msg_error "$description failed"
+        return 1
+    fi
+}
+
+# Usage
+run_with_error_handling "apt-get update" "Package list update"
+run_with_error_handling "apt-get install -y nginx" "Nginx installation"
+```
+
+### Verbose Mode Handling
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Handle verbose mode
+if is_verbose_mode; then
+    msg_info "Verbose mode enabled - showing detailed output"
+    # Show more information
+else
+    msg_info "Normal mode - showing minimal output"
+    # Show less information
+fi
+```
+
+### Alpine Linux Detection
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Handle different OS types
+if is_alpine; then
+    msg_info "Detected Alpine Linux"
+    # Use Alpine-specific commands
+    silent apk add --no-cache package
+else
+    msg_info "Detected Debian-based system"
+    # Use Debian-specific commands
+    silent apt-get install -y package
+fi
+```
+
+### Conditional Execution
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Conditional execution based on system state
+if [[ -f /etc/nginx/nginx.conf ]]; then
+    msg_warn "Nginx configuration already exists"
+    read -p "Overwrite? [y/N]: " overwrite
+    if [[ "$overwrite" =~ ^[yY]$ ]]; then
+        msg_info "Overwriting configuration..."
+        # ... overwrite logic ...
+    else
+        msg_info "Skipping configuration"
+    fi
+else
+    msg_info "Creating new Nginx configuration..."
+    # ... create logic ...
+fi
+```
+
+## Advanced Usage Examples
+
+### Custom Spinner Messages
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Custom spinner with progress
+download_with_progress() {
+    local url="$1"
+    local file="$2"
+
+    msg_info "Starting download..."
+
+    # Start spinner
+    SPINNER_MSG="Downloading..."
+    spinner &
+    SPINNER_PID=$!
+
+    # Download with progress
+    curl -L "$url" -o "$file" --progress-bar
+
+    # Stop spinner
+    stop_spinner
+    msg_ok "Download completed"
+}
+
+download_with_progress "https://example.com/file.tar.gz" "/tmp/file.tar.gz"
+```
+
+### Message Deduplication
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Messages are automatically deduplicated
+for i in {1..5}; do
+    msg_info "Processing item $i"
+    # This message will only show once
+done
+
+# Different messages will show separately
+msg_info "Starting phase 1"
+msg_info "Starting phase 2"
+msg_info "Starting phase 3"
+```
+
+### Terminal Control
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Ensure terminal control is available
+ensure_tput
+
+# Use terminal control
+clear_line
+echo "This line will be cleared"
+clear_line
+echo "New content"
+```
+
+## Troubleshooting Examples
+
+### Debug Mode
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Enable debug mode
+export var_full_verbose=1
+export VERBOSE="yes"
+
+# Debug information
+msg_debug "Script started"
+msg_debug "Current user: $(whoami)"
+msg_debug "Current directory: $(pwd)"
+msg_debug "Environment variables: $(env | grep -E '^(APP|CTID|VERBOSE)')"
+```
+
+### Silent Execution Debugging
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Debug silent execution
+debug_silent() {
+    local cmd="$1"
+    local log_file="/tmp/debug.$$.log"
+
+    echo "Command: $cmd" > "$log_file"
+    echo "Timestamp: $(date)" >> "$log_file"
+    echo "Working directory: $(pwd)" >> "$log_file"
+    echo "Environment:" >> "$log_file"
+    env >> "$log_file"
+    echo "--- Command Output ---" >> "$log_file"
+
+    if silent "$cmd"; then
+        msg_ok "Command succeeded"
+    else
+        msg_error "Command failed - check $log_file for details"
+    fi
+}
+
+debug_silent "apt-get update"
+```
+
+### Error Recovery
+
+```bash
+#!/usr/bin/env bash
+source core.func
+
+# Error recovery pattern
+retry_operation() {
+    local max_attempts=3
+    local attempt=1
+
+    while [[ $attempt -le $max_attempts ]]; do
+        msg_info "Attempt $attempt of $max_attempts"
+
+        if silent "$@"; then
+            msg_ok "Operation succeeded on attempt $attempt"
+            return 0
+        else
+            msg_warn "Attempt $attempt failed"
+            ((attempt++))
+
+            if [[ $attempt -le $max_attempts ]]; then
+                msg_info "Retrying in 5 seconds..."
+                sleep 5
+            fi
+        fi
+    done
+
+    msg_error "Operation failed after $max_attempts attempts"
+    return 1
+}
+
+# Usage
+retry_operation "apt-get install -y package"
+```