{"id":26225506,"url":"https://github.com/christophera/z_utils","last_synced_at":"2026-04-24T17:05:22.235Z","repository":{"id":281219862,"uuid":"944423301","full_name":"ChristopherA/z_Utils","owner":"ChristopherA","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-07T16:44:43.000Z","size":208,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-07T17:30:01.905Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChristopherA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-07T10:16:30.000Z","updated_at":"2025-03-07T16:44:47.000Z","dependencies_parsed_at":"2025-03-07T17:40:43.575Z","dependency_job_id":null,"html_url":"https://github.com/ChristopherA/z_Utils","commit_stats":null,"previous_names":["christophera/z_utils"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopherA%2Fz_Utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopherA%2Fz_Utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopherA%2Fz_Utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristopherA%2Fz_Utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChristopherA","download_url":"https://codeload.github.com/ChristopherA/z_Utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243277500,"owners_count":20265352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-12T19:16:56.539Z","updated_at":"2026-04-24T17:05:22.213Z","avatar_url":"https://github.com/ChristopherA.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Z_Utils: Zsh Utility Library\n\n\u003e - _did_: `did:repo:b0c5cd0d85b29543c604c093dd83a1a20eb17af1/blob/main/README.md`\n\u003e - _github_: [`z_Utils/README.md`](https://github.com/ChristopherA/z_Utils/blob/main/README.md)\n\u003e - _purpose_: Provide overview of the Z_Utils Zsh utility library\n\u003e - _copyright_: ©2025 by @ChristopherA, licensed under the [BSD 2-Clause Plus Patent License](https://spdx.org/licenses/BSD-2-Clause-Patent.html)\n\u003e - _created_: 2025-03-19 by @ChristopherA \u003cChristopherA@LifeWithAlacrity.com\u003e\n\u003e - _last-updated_: 2025-03-31 by @ChristopherA \u003cChristopherA@LifeWithAlacrity.com\u003e\n\n[![License](https://img.shields.io/badge/License-BSD_2--Clause--Patent-blue.svg)](https://spdx.org/licenses/BSD-2-Clause-Patent.html)\n[![Project Status: WIP](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![Version](https://img.shields.io/badge/version-0.1.01-blue.svg)](CHANGELOG.md)\n\n## Project Overview\n\nZ_Utils is a powerful, comprehensive collection of reusable Zsh utility functions that deliver professional-grade shell scripting capabilities. This library enables developers to create more reliable, maintainable, and efficient shell scripts through standardized patterns for common operations.\n\n## Key Benefits\n\n- **Improved Script Reliability**: Consistent error handling and environment validation\n- **Professional Output**: Standardized user messaging with proper formatting\n- **Development Efficiency**: Avoid rewriting common utility functions\n- **Better Maintainability**: Standardized patterns for common operations\n- **Reduced Errors**: Well-tested utility functions reduce script bugs\n\n## Integration Patterns\n\nZ_Utils offers multiple ways to leverage its functionality in your scripts:\n\n### Direct Function Usage (Most Common)\nCopy specific functions you need directly into your scripts:\n```bash\n# Example: Including z_Output in your script\nfunction z_Output() {\n  # Copy function implementation from src/_Z_Utils.zsh\n}\n\n# Then use it\nz_Output info \"Starting script execution...\"\n```\n\n### Library Source (For Multiple Functions)\nSource the library in your Zsh scripts when you need multiple functions:\n```bash\n# Option 1: Source with absolute path\nsource /path/to/_Z_Utils.zsh\n\n# Option 2: Source with dynamic path detection (more portable)\nSCRIPT_DIR=\"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" \u0026\u003e /dev/null \u0026\u0026 pwd )\"\nsource \"${SCRIPT_DIR}/path/to/_Z_Utils.zsh\"\n\n# Then use any function\nz_Output info \"Starting script execution...\"\nz_Ensure_Parent_Path_Exists \"/path/to/output/file.txt\"\n```\n\n### Individual Script Usage (For Specific Tools)\nRun the example scripts directly when you need their specific functionality:\n```bash\n# Using a specific utility script\n./src/examples/setup_git_inception_repo.sh /path/to/new/repo\n\n# Using test verification functions\nsource ./src/function_tests/z_Output_test.sh\n```\n\n## Key Features\n\n### Output Management *(v0.1.00+)*\n\nThe `z_Output` function provides standardized output with:\n- Multiple message types (info, warning, error, debug)\n- Consistent formatting with colors and emoji\n- Verbosity levels and quiet mode support\n- Text wrapping and indentation\n- User prompts with defaults\n\n```bash\n# Basic output examples\nz_Output info \"Processing file: $filename\"\nz_Output warn \"Disk space is low\"\nz_Output error \"Failed to connect to server\"\nz_Output debug \"Variable value: $value\"\n\n# Prompt example\nUserInput=$(z_Output prompt \"Enter your name\" Default=\"User\")\n```\n\n**Real-world example:** Standardizing user feedback in complex multi-stage scripts\n```bash\n# Problem: Inconsistent user feedback in complex scripts\n# Solution: Centralized output management with z_Output\n\n# Initialize output options\ntypeset -g Output_Color_Enabled=$TRUE\ntypeset -g Output_Verbose_Mode=$TRUE\n\n# Process stages with consistent feedback\nz_Output info \"Stage 1: Validating inputs...\"\nz_Output debug \"Input parameters: $@\"\n\nif [[ -z \"$required_parameter\" ]]; then\n  z_Output error \"Missing required parameter\"\n  exit 1\nfi\n\nz_Output success \"Stage 1 complete\"\nz_Output info \"Stage 2: Processing data...\"\n\n# Control verbosity for different environments\nif [[ \"$CI_MODE\" == \"true\" ]]; then\n  Output_Verbose_Mode=$FALSE  # Less output in CI environments\nfi\n```\n\n### Error Handling *(v0.1.00+)*\n\nThe `z_Report_Error` function provides centralized error reporting:\n- Consistent error formatting\n- Integration with output system\n- Support for exit codes\n- Standard error propagation\n\n```bash\nif [[ ! -f \"$config_file\" ]]; then\n  z_Report_Error \"Configuration file not found: $config_file\" $Exit_Status_IO\n  return $?\nfi\n```\n\n**Real-world example:** Managing errors in complex script hierarchies\n```bash\n# Problem: Error handling across multiple function calls is inconsistent\n# Solution: Standardized error reporting and propagation\n\n# Define error codes\ntypeset -gi Exit_Status_Success=0\ntypeset -gi Exit_Status_Error=1\ntypeset -gi Exit_Status_IO=2\ntypeset -gi Exit_Status_Invalid_Argument=3\n\nfunction validate_input() {\n  local input=\"$1\"\n  \n  if [[ -z \"$input\" ]]; then\n    z_Report_Error \"Input cannot be empty\" $Exit_Status_Invalid_Argument\n    return $?  # Propagate error code\n  fi\n  \n  if [[ ! -f \"$input\" ]]; then\n    z_Report_Error \"Input file does not exist: $input\" $Exit_Status_IO\n    return $?  # Propagate error code\n  fi\n  \n  return $Exit_Status_Success\n}\n\n# Calling function with error propagation\nvalidate_input \"$user_input\"\nif [[ $? -ne $Exit_Status_Success ]]; then\n  # Error already reported by z_Report_Error\n  exit $?\nfi\n```\n\n### Environment Setup *(v0.1.00+)*\n\nThe `z_Setup_Environment` function initializes script environments:\n- Safe shell options\n- Terminal capability detection\n- Environment variable initialization\n- Version compatibility checks\n\n```bash\n# Initialize script environment\nz_Setup_Environment || exit $?\n```\n\n**Real-world example:** Ensuring consistent environment across different systems\n```bash\n# Problem: Scripts behave differently across various environments\n# Solution: Standardized environment setup with safety measures\n\n#!/usr/bin/env zsh\n# My script that needs to work consistently\n\n# Source Z_Utils for environment setup\nsource \"$(dirname \"$0\")/_Z_Utils.zsh\"\n\n# Initialize environment with safety settings\nz_Setup_Environment || exit $?\n# Now we have:\n# - set -e (exit on error)\n# - set -u (error on undefined variables) \n# - IFS standardized\n# - PATH sanitized\n# - Terminal capabilities detected\n# - Color support identified\n# - Core environment variables defined\n\n# Script can now run with consistent behavior\nprocess_files \"$@\"\n```\n\n### Dependency Checking *(v0.1.00+)*\n\nThe `z_Check_Dependencies` function verifies required external tools:\n- Check for mandatory dependencies\n- Optional dependency support\n- User-friendly error reporting\n\n```bash\n# Define required tools\ntypeset -a RequiredTools=(\"git\" \"ssh\" \"jq\")\ntypeset -a OptionalTools=(\"gh\" \"fzf\")\n\n# Check dependencies\nz_Check_Dependencies \"RequiredTools\" \"OptionalTools\" || exit $?\n```\n\n**Real-world example:** Avoiding runtime failures due to missing tools\n```bash\n# Problem: Scripts fail in unpredictable ways when dependencies aren't available\n# Solution: Upfront dependency verification with clear error messages\n\n#!/usr/bin/env zsh\n# Script that relies on external tools\n\n# Source Z_Utils\nsource \"$(dirname \"$0\")/_Z_Utils.zsh\"\n\n# Define dependencies with descriptive names\ntypeset -a RequiredTools=(\n  \"git:Required for repository operations\"\n  \"ssh:Required for secure connections\"\n  \"gpg:Required for signing commits\"\n)\n\ntypeset -a OptionalTools=(\n  \"gh:GitHub CLI for enhanced GitHub integration\"\n  \"fzf:Interactive selection capabilities\"\n)\n\n# Check dependencies - providing array names, not values\nz_Check_Dependencies \"RequiredTools\" \"OptionalTools\" || exit $?\n\n# Now we can safely use dependencies, and know which optional tools are available\nif [[ $HAS_fzf -eq $TRUE ]]; then\n  # Use interactive selection with fzf\n  SELECTED_FILE=$(find . -type f | fzf --prompt=\"Select file: \")\nelse\n  # Fallback to basic selection\n  echo \"Available files:\"\n  find . -type f | nl\n  echo \"Enter number: \"\n  read file_number\n  SELECTED_FILE=$(find . -type f | sed -n \"${file_number}p\")\nfi\n```\n\n### Path Management *(v0.1.00+)*\n\nPath utility functions include:\n- `z_Ensure_Parent_Path_Exists`: Create directories as needed\n- `z_Convert_Path_To_Relative`: User-friendly path conversion\n\n```bash\n# Ensure directory exists before writing file\nz_Ensure_Parent_Path_Exists \"/path/to/output/file.txt\" || exit $?\n\n# Get user-friendly path\nRelativePath=$(z_Convert_Path_To_Relative \"/long/absolute/path/file.txt\")\n```\n\n**Real-world example:** Safe file operations with path management\n```bash\n# Problem: File operations fail inconsistently due to missing directories\n# Solution: Integrated path validation and creation\n\n#!/usr/bin/env zsh\n# Script that writes log files to nested directories\n\n# Source Z_Utils\nsource \"$(dirname \"$0\")/_Z_Utils.zsh\"\n\n# Define log file path with nested directories\nLOG_DIR=\"${HOME}/logs/$(date +%Y)/$(date +%m)/$(date +%d)\"\nLOG_FILE=\"${LOG_DIR}/process.log\"\n\n# Safely ensure parent directories exist\nz_Ensure_Parent_Path_Exists \"$LOG_FILE\" || exit $?\n# Now we can safely write to the log file, knowing all parent directories exist\n\n# For user-friendly output, convert to relative path\nDISPLAY_PATH=$(z_Convert_Path_To_Relative \"$LOG_FILE\")\nz_Output info \"Writing log to $DISPLAY_PATH\"\n\n# Write the log file\necho \"Log entry: $(date)\" \u003e\u003e \"$LOG_FILE\"\n```\n\n### Resource Cleanup *(v0.1.00+)*\n\nThe `z_Cleanup` function provides automatic resource cleanup:\n- Temporary file management\n- Trap-based cleanup on script exit\n- Error state handling\n\n```bash\n# Set up cleanup trap\ntypeset -g Script_Running=$TRUE\ntrap 'z_Cleanup $FALSE \"Script interrupted\"' INT TERM\ntrap 'z_Cleanup $TRUE' EXIT\n```\n\n**Real-world example:** Ensuring cleanup even when scripts fail\n```bash\n# Problem: Scripts leave behind temporary files when interrupted\n# Solution: Robust trap-based cleanup mechanism\n\n#!/usr/bin/env zsh\n# Script that creates temporary resources\n\n# Source Z_Utils\nsource \"$(dirname \"$0\")/_Z_Utils.zsh\"\n\n# Initialize cleanup tracking\ntypeset -g Script_Running=$TRUE\ntypeset -a Temp_Files=()\n\n# Register cleanup handlers\ntrap 'z_Cleanup $FALSE \"Script interrupted\"' INT TERM\ntrap 'z_Cleanup $TRUE' EXIT\n\n# Create temporary file that will be automatically cleaned up\nTEMP_CONFIG=$(mktemp)\nTemp_Files+=(\"$TEMP_CONFIG\")\n\n# Create temporary directory\nTEMP_DIR=$(mktemp -d)\nTemp_Files+=(\"$TEMP_DIR\")\n\n# Even if the script fails here, cleanup will still happen\nprocess_data \"$TEMP_CONFIG\" \"$TEMP_DIR\"\n\n# Define cleanup function that z_Cleanup will call\nfunction cleanup_Handler() {\n  local success=$1\n  \n  # Custom cleanup logic\n  if [[ -n \"$DB_CONNECTION\" ]]; then\n    close_database_connection \"$DB_CONNECTION\"\n  fi\n  \n  # Return success status\n  return $success\n}\n```\n\n## Documentation\n\nComprehensive documentation is available in the repository:\n\n- Function specifications: `requirements/project/functions/`\n- General guidelines: `requirements/shared/zsh_scripting/`\n- Example scripts: `src/examples/`\n- Function tests: `src/function_tests/`\n- Developer workflows: [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)\n\n## Compatibility\n\n- Requires Zsh 5.8+ *(core functionality)*\n- Git functions require Git 2.28+ *(for initial branch setting)*\n- Tested on macOS and Linux\n- Terminal-aware with fallbacks for limited environments\n- Minimal external dependencies\n- All functions include fallback implementations when possible\n\n## Additional Capabilities\n\nZ_Utils includes specialized functionality for:\n\n### Git Operations *(v0.1.01+)*\n- Repository initialization with proper signatures\n- DID (Decentralized Identifier) generation\n- SSH key fingerprint extraction\n- Allowed signers configuration\n- Commit signature verification\n- First commit hash extraction\n- Git configuration validation\n\n### Testing Framework *(v0.1.00+)*\n- Comprehensive test environment setup\n- Test result validation functions\n- ANSI color handling in test output\n- Test suite organization tools\n- Automated test reporting\n- Sandbox isolation for Git tests\n\n### Filesystem Operations *(v0.1.00+)*\n- Safe directory creation\n- Path normalization and validation\n- Path conversion (absolute/relative)\n- Path existence verification\n- Consistent error handling for path operations\n\n## Developer Resources\n\nFor developers interested in contributing to Z_Utils:\n\n- [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) - Detailed development workflows\n- [WORK_STREAM_TASKS.md](WORK_STREAM_TASKS.md) - Current project status and task tracking\n\nZ_Utils maintains comprehensive documentation:\n- Function specifications in `requirements/project/functions/`\n- Scripting guidelines in `requirements/shared/zsh_scripting/`\n- Working examples in `src/examples/`\n- Function tests in `src/function_tests/`\n\n## License\n\nThis project is licensed under the [BSD 2-Clause Plus Patent License](https://spdx.org/licenses/BSD-2-Clause-Patent.html).\n\n## Contributing\n\nContributions are welcome! Z_Utils follows a structured development process with focus on quality and maintainability. Please see the project workflow guides in `requirements/guides/` for more information on the development process.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristophera%2Fz_utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristophera%2Fz_utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristophera%2Fz_utils/lists"}