en-US/about_ColorScripts-Enhanced.help.txt
|
# ColorScripts-Enhanced Module Help
## about_ColorScripts-Enhanced ### SHORT DESCRIPTION Enhanced PowerShell ColorScripts with high-performance caching system for displaying beautiful ANSI art in your terminal. ### LONG DESCRIPTION ColorScripts-Enhanced is a PowerShell module that provides a collection of 295+ beautiful ANSI colorscripts for terminal display. It features an intelligent caching system that provides 6-19x performance improvements over traditional script execution. The module automatically caches script output to a centralized location in your AppData folder, enabling instant display on subsequent runs. Cache files are automatically validated and regenerated when source scripts are modified. ### FEATURES - 295+ beautiful pre-made colorscripts - High-performance caching system (6-19x faster) - Centralized cache location (works from any directory) - Automatic cache invalidation on script changes - UTF-8 encoding support for perfect rendering - Random colorscript selection - Easy script discovery and listing - Profile helper for one-line startup integration - Persistent configuration helpers for cache and startup behaviour - Metadata export and scaffolding workflows for custom scripts ### INSTALLATION #### From PowerShell Gallery (Recommended) ```powershell Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser ``` Add the module to your profile automatically: ```powershell Add-ColorScriptProfile # Import + Show-ColorScript Add-ColorScriptProfile -SkipStartupScript ``` #### Manual Installation 1. Download the module from GitHub 2. Extract to a PowerShell module path: - User: `$HOME\Documents\PowerShell\Modules\ColorScripts-Enhanced` - System: `C:\Program Files\PowerShell\Modules\ColorScripts-Enhanced` 3. Import the module: ```powershell Import-Module ColorScripts-Enhanced ``` ### QUICK START Display a random colorscript: ```powershell Show-ColorScript # or use the alias scs ``` Display a specific colorscript: ```powershell Show-ColorScript -Name hearts scs mandelbrot-zoom ``` List all available colorscripts: ```powershell Show-ColorScript -List Get-ColorScriptList ``` Pre-build cache for all scripts: ```powershell Build-ColorScriptCache ``` ### COMMANDS The module exports the following commands: - `Show-ColorScript` - Display colorscripts (alias: scs) - `Get-ColorScriptList` - List available colorscripts - `Build-ColorScriptCache` - Pre-generate cache files - `Clear-ColorScriptCache` - Remove cache files - `Add-ColorScriptProfile` - Append module startup snippet to a PowerShell profile - `Get-ColorScriptConfiguration` - Inspect cache and startup defaults - `Set-ColorScriptConfiguration` - Persist custom configuration values - `Reset-ColorScriptConfiguration` - Restore configuration defaults - `Export-ColorScriptMetadata` - Export script metadata for automation - `New-ColorScript` - Scaffold a new colorscript and metadata snippet Use `Get-Help <CommandName> -Full` for detailed help on each command. ### CACHE SYSTEM The caching system works automatically: 1. **First Run**: Script executes normally and output is cached 2. **Subsequent Runs**: Cached output displays instantly (6-19x faster) 3. **Auto-Refresh**: Cache regenerates when script is modified **Cache Location**: `$env:APPDATA\ColorScripts-Enhanced\cache` **Cache Benefits**: - Instant display of complex colorscripts - Reduced CPU usage - Consistent performance - Works from any directory ### CONFIGURATION #### Add to PowerShell Profile Display a random colorscript on every terminal launch: ```powershell Add-ColorScriptProfile # Import + Show-ColorScript Add-ColorScriptProfile -SkipStartupScript ``` #### Customize Cache Location The cache location is automatically set based on your platform: Windows: ```powershell $env:APPDATA\ColorScripts-Enhanced\cache ``` macOS: ```powershell ~/Library/Application Support/ColorScripts-Enhanced/cache ``` Linux: ```powershell ~/.cache/ColorScripts-Enhanced ``` ### NERD FONT GLYPHS Some scripts display Nerd Font icons (developer glyphs, powerline separators, checkmarks). Install a patched font so those characters render correctly: 1. Download a font from https://www.nerdfonts.com/ (popular choices: Cascadia Code, JetBrainsMono, FiraCode). 2. Windows: extract the `.zip`, select the `.ttf` files, right-click → **Install for all users**. macOS: `brew install --cask font-caskaydia-cove-nerd-font` or add via Font Book. Linux: copy `.ttf` files to `~/.local/share/fonts` (or `/usr/local/share/fonts`) and run `fc-cache -fv`. 3. Set your terminal profile to use the installed Nerd Font. 4. Verify glyphs with: ```powershell Show-ColorScript -Name nerd-font-test ``` ### EXAMPLES #### Example 1: Random Colorscript on Startup ```powershell # In your $PROFILE file: Import-Module ColorScripts-Enhanced Show-ColorScript ``` #### Example 2: Daily Different Colorscript ```powershell # Use the date as seed for consistent daily script $seed = (Get-Date).DayOfYear Get-Random -SetSeed $seed Show-ColorScript ``` #### Example 3: Build Cache for Favorite Scripts ```powershell Build-ColorScriptCache -Name hearts,mandelbrot-zoom,galaxy-spiral ``` #### Example 4: Force Cache Rebuild ```powershell Build-ColorScriptCache -Force ``` ### TROUBLESHOOTING #### Scripts not displaying correctly Ensure your terminal supports UTF-8 and ANSI escape codes: ```powershell [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 ``` #### Cache not working Clear and rebuild cache: ```powershell Clear-ColorScriptCache -All Build-ColorScriptCache ``` #### Performance issues The first run of each script will be slower as it builds cache. Pre-build all caches: ```powershell Build-ColorScriptCache ``` ### PERFORMANCE Typical performance improvements with caching: | Script Type | Without Cache | With Cache | Speedup | |------------|---------------|------------|---------| | Simple | ~50ms | ~8ms | 6x | | Medium | ~150ms | ~12ms | 12x | | Complex | ~300ms | ~16ms | 19x | ### SCRIPT CATEGORIES The module includes scripts in various categories: - **Geometric**: mandelbrot-zoom, apollonian-circles, sierpinski-carpet - **Nature**: galaxy-spiral, aurora-bands, crystal-drift - **Artistic**: kaleidoscope, rainbow-waves, prismatic-rain - **Gaming**: doom, pacman, space-invaders - **System**: colortest, nerd-font-test, terminal-benchmark - **Logos**: arch, debian, ubuntu, windows ### SEE ALSO - GitHub Repository: https://github.com/Nick2bad4u/ps-color-scripts-enhanced - Original inspiration: shell-color-scripts - PowerShell Documentation: https://docs.microsoft.com/powershell/ ### KEYWORDS - ANSI - Terminal - Art - ASCII - Color - Scripts - Cache - Performance ### VERSION HISTORY #### Version 2025.10.09 - Enhanced caching system with OS-wide cache - 6-19x performance improvement - Centralized cache location in AppData - 295+ colorscripts included - Full comment-based help documentation - Module manifest improvements ### COPYRIGHT Copyright (c) 2025. All rights reserved. ### LICENSE Licensed under MIT License. See LICENSE file for details. |