Merge pull request #19 from richardwilkes/v2-wip

Sweeping changes to reorganize the packages, fix some things, improve others, and drop some old functionality that was no longer needed by any of my projects.

Going forward, I'll try to adhere to the normal version compatibility guidelines for Go code, unlike with the v1 code base.

I hope to find time in the near future to add a V1-TO-V2-MIGRATION.md file to the repo to help existing users of v1 make the transition. If you need help finding something or understanding a change, feel free to reach out to me in the meantime.

Author: richardwilkes

.github/copilot-instructions.md

@@ -0,0 +1,87 @@
+# Copilot Instructions for Toolbox
+
+## Project Overview
+
+This is a comprehensive Go utility library (v2) providing extended functionality for common patterns. The codebase follows a strict "x-prefix" convention where packages extending standard library functionality are prefixed with "x" (e.g., `xmath`, `xio`, `xhttp`).
+
+## Key Architecture Patterns
+
+### Generics-First Design
+
+-   Heavy use of Go generics with type constraints (see `xmath.Numeric` interface)
+-   Generic data structures like `Point[T xmath.Numeric]`, `Tree[K, V any]`, `Int[T fixed.Dx]`
+-   Type conversion functions like `ConvertPoint[T, F xmath.Numeric](pt Point[F]) Point[T]`
+
+### Error Handling Convention
+
+-   Use `errs.Error` for structured errors with stack traces instead of basic Go errors
+-   All errors include source location and can be chained: `errs.NewWithCause("message", causeErr)`
+-   The `errs` package provides `ErrorWrapper` and `StackError` interfaces
+-   Use `xos.PanicRecovery()` for panic handling in defer statements
+
+### Testing Patterns
+
+-   Use the internal `check` package instead of raw testing.T: `c := check.New(t)`
+-   Testing methods: `c.Equal(expected, actual)`, `c.HasPrefix()`, `c.NoError()`, `c.HasError()`
+-   Example tests follow `ExampleFunction` naming for documentation
+-   All test files use `package_test` naming convention
+
+### Fixed-Point Arithmetic
+
+-   `fixed64.Int[T]` and `fixed128.Int[T]` for precise decimal calculations
+-   Always use `.Mul()` and `.Div()` methods, never direct operators for multiplication/division
+-   Different precision types via type parameters: `fixed64.Int[fixed.D2]` for 2 decimal places
+
+### Command-Line Applications
+
+-   Use `xflag.SetUsage()` for rich CLI help with version info and formatting
+-   Set app metadata in main(): `xos.AppIdentifier`, `xos.CopyrightStartYear`, etc.
+-   Use `i18n.Text()` for all user-facing strings for localization support
+
+## Build and Development
+
+### Build System
+
+```bash
+./build.sh --all    # Full build with linting and race-checked tests
+./build.sh --lint   # Run golangci-lint (auto-installs latest version)
+./build.sh --test   # Run tests
+./build.sh --race   # Run tests with race detection
+```
+
+### Dependencies
+
+-   Minimal external dependencies: only `golang.org/x/*` and `gopkg.in/yaml.v3`
+-   Self-contained utilities - avoid adding new external deps without strong justification
+
+## Package-Specific Notes
+
+### Geometry (`geom/`)
+
+-   All geometric types are generic: `Point[T]`, `Rect[T]`, `Size[T]` with `xmath.Numeric` constraint
+-   Conversion between numeric types via `ConvertPoint`, `ConvertRect`, etc.
+
+### Collections (`collection/`)
+
+-   Red-black tree: `redblack.New[K, V any](compareFunc)` - requires comparison function
+-   Bitset and quadtree implementations available
+
+### Extended Standard Library
+
+-   `xmath`: Generic math functions with proper type constraints
+-   `xio`: BOM stripping, safe file operations
+-   `xstrings`: Enhanced string utilities
+-   `xhttp`: HTTP utilities with metadata and compression helpers
+
+### 128-bit Numbers (`num128/`)
+
+-   `Int` and `UInt` types for 128-bit arithmetic
+-   Always check for overflow in mathematical operations
+-   String conversion methods handle different bases
+
+## File Organization
+
+-   Each package should have comprehensive tests (`*_test.go`)
+-   Example tests for public APIs to serve as documentation
+-   License header on all files (Mozilla Public License 2.0)
+-   Internal utilities in appropriate x-prefixed packages

.golangci.yml

@@ -37,6 +37,9 @@ linters:
         - fmt.Fprintf
         - fmt.Fprintln
         - (fmt.State).Write
+        - (*github.com/richardwilkes/toolbox/v2/xterm.AnsiWriter).Write
+        - (*github.com/richardwilkes/toolbox/v2/xterm.AnsiWriter).WriteByte
+        - (*github.com/richardwilkes/toolbox/v2/xterm.AnsiWriter).WriteString
     goconst:
       min-len: 3
       min-occurrences: 3
@@ -52,6 +55,7 @@ linters:
     gosec:
       excludes:
         - G103
+        - G104
         - G115
         - G204
         - G301

README.md

@@ -1,11 +1,108 @@
 # toolbox
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/richardwilkes/toolbox.svg)](https://pkg.go.dev/github.com/richardwilkes/toolbox)
-[![Go Report Card](https://goreportcard.com/badge/github.com/richardwilkes/toolbox)](https://goreportcard.com/report/github.com/richardwilkes/toolbox)
+[![Go Reference](https://pkg.go.dev/badge/github.com/richardwilkes/toolbox/v2.svg)](https://pkg.go.dev/github.com/richardwilkes/toolbox/v2)
+[![Go Report Card](https://goreportcard.com/badge/github.com/richardwilkes/toolbox/v2)](https://goreportcard.com/report/github.com/richardwilkes/toolbox/v2)
 
-Toolbox for Go. Contains a wide variety of packages I've found useful in my own projects over the years.
+Toolbox for Go.
 
-> [!NOTE]
-> This library already had a v1.x.y when Go modules were first introduced. Due to this, it doesn't follow the
-> normal convention and instead treats its releases as if they are of the v0.x.y variety (i.e. it could introduce
-> breaking API changes). Keep this in mind when deciding whether or not to use it.
+Contains a wide variety of code I've found useful in my own projects over the years. For cases where code exists to help
+use standard library code, the package has been named the same as the standard library one, but with a preceeding "x"
+(for extended). This allows both to be used in the same file without having to do import renaming.
+
+## Package Overview
+
+### Core Utilities
+
+- **`check`** - Enhanced testing utilities that wrap Go's standard testing interface with more informative error messages and convenient assertion methods.
+
+- **`errs`** - Structured error handling with stack traces, error chaining, and detailed error objects that provide source locations and nested causes for better debugging.
+
+- **`i18n`** - Internationalization support for applications, providing localization capabilities for user-facing text and messages.
+
+- **`notifier`** - Event notification system for implementing the observer pattern, allowing objects to register for and receive notifications about events.
+
+- **`tid`** - Thread-safe unique identifier generation using cryptographically secure random values encoded in base64.
+
+### Mathematical and Numerical
+
+- **`xmath`** - Extended mathematical functions with generic type constraints (e.g., `Numeric` interface) that work across integer and floating-point types.
+
+- **`num128`** - 128-bit integer arithmetic with signed (`Int`) and unsigned (`UInt`) types for high-precision calculations that exceed native Go integer limits.
+
+- **`fixed`** - Fixed-point decimal arithmetic for precise financial and monetary calculations, with separate packages for 64-bit (`fixed64`) and 128-bit (`fixed128`) precision.
+
+### Geometry and Graphics
+
+- **`geom`** - Generic geometric primitives including `Point[T]`, `Rect[T]`, `Size[T]`, `Line[T]`, `Matrix[T]`, and `Insets[T]` with type conversion utilities.
+
+- **`geom/poly`** - Provides polygon operations using fixed-point arithmetic for reliable geometric computations.
+
+- **`geom/visibility`** - 2D visibility polygon computation for line-of-sight calculations.
+
+### Data Structures and Collections
+
+- **`collection/bitset`** - Efficient bitset implementation for working with sets of bits.
+
+- **`collection/quadtree`** - Spatial data structure for efficient 2D range queries and collision detection.
+
+- **`collection/redblack`** - Generic red-black tree implementation providing balanced binary search tree functionality.
+
+### Extended Standard Library
+
+- **`xbytes`** - Extended byte manipulation utilities including BOM (Byte Order Mark) handling and buffer utilities.
+
+- **`xcrc64`** - Extended CRC64 checksum utilities for data integrity verification.
+
+- **`xcrypto`** - Cryptographic utilities including stream encryption/decryption helpers.
+
+- **`xfilepath`** - Extended file path utilities with filename manipulation, root detection, and cross-platform path splitting.
+
+- **`xflag`** - Enhanced command-line flag parsing with rich usage formatting, automatic version flags, and post-parse function handling.
+
+- **`xhash`** - Extended hashing utilities for creating consistent hash values across different data types.
+
+- **`xhttp`** - HTTP utilities including basic authentication, gzip handling, metadata management, file retrieval, and server helpers.
+
+- **`ximage`** - Image processing utilities with support for various image formats.
+
+- **`xio`** - Extended I/O utilities including BOM stripping, safe file closing, and specialized readers/writers.
+
+- **`xjson`** - Enhanced JSON handling utilities for parsing and marshaling with additional features.
+
+- **`xnet`** - Network utilities for address manipulation and network-related operations.
+
+- **`xos`** - Operating system utilities including application information, browser launching, filesystem operations, panic recovery, safe file handling, task queues, and user information.
+
+- **`xrand`** - Extended random number generation utilities for cryptographically secure randomness.
+
+- **`xreflect`** - Reflection utilities for working with Go's reflection API more effectively.
+
+- **`xruntime`** - Runtime utilities including detailed stack trace generation with source location information.
+
+- **`xslices`** - Enhanced slice manipulation utilities including column-based sorting and other advanced slice operations.
+
+- **`xslog`** - Enhanced structured logging with a "pretty" formatter that provides colorful output, stack trace formatting, and improved readability.
+
+- **`xstrings`** - String manipulation utilities including case conversion, text wrapping, natural sorting, emoji handling, capitalization, space collapsing, and various string processing functions.
+
+- **`xsync`** - Synchronization utilities extending Go's sync package with additional concurrent programming tools.
+
+- **`xterm`** - Terminal utilities for ANSI color codes, terminal detection, and formatted output with cross-platform compatibility.
+
+- **`xtime`** - Time manipulation utilities extending Go's time package with additional date/time functionality.
+
+- **`xunicode`** - Unicode utilities for advanced text processing and character manipulation.
+
+- **`xyaml`** - YAML processing utilities for parsing and marshaling YAML data with enhanced features.
+
+### Specialized Utilities
+
+- **`rate`** - Rate limiting with hierarchical limiters, where each limiter can be capped by its parent, useful for implementing tiered rate limiting.
+
+- **`softref`** - Soft reference implementation for memory management, allowing resources to be garbage collected when memory pressure occurs.
+
+### Command Line Tools
+
+- **`cmd/i18n`** - Command-line tool for extracting and managing internationalization strings from Go source code.
+
+All packages follow consistent patterns with use of Go generics for type safety where appropriate, comprehensive error handling with the `errs` package, and thorough testing with the `check` package. The "x" prefix convention allows seamless use alongside standard library packages without import conflicts.

appdir.go

@@ -65,4 +65,4 @@ fi
 
 # Install executables
 echo -e "\033[33mInstalling executables...\033[0m"
-go install -v ./i18n/i18n
+go install -v ./cmd/i18n