// Package hlog provides a structured logging solution built on top of zerolog.
//
// hlog supports multiple output modes (console, file, or both), configurable
// log levels, and automatic log file management. It is designed to be simple
// to configure via environment variables while remaining flexible for
// programmatic configuration.
//
// # Basic Usage
//
// Create a logger with environment-based configuration:
//
//	cfg, err := hlog.ConfigFromEnv()
//	if err != nil {
//		log.Fatal(err)
//	}
//
//	logger, err := hlog.NewLogger(cfg, os.Stdout)
//	if err != nil {
//		log.Fatal(err)
//	}
//	defer logger.CloseLogFile()
//
//	logger.Info().Msg("Application started")
//
// # Configuration
//
// hlog can be configured via environment variables using ConfigFromEnv:
//
//	LOG_LEVEL=info             # trace, debug, info, warn, error, fatal, panic (default: info)
//	LOG_OUTPUT=console         # console, file, or both (default: console)
//	LOG_DIR=/var/log/app       # Required when LOG_OUTPUT is "file" or "both"
//	LOG_FILE_NAME=server.log   # Required when LOG_OUTPUT is "file" or "both"
//	LOG_APPEND=true            # Append to existing file or overwrite (default: true)
//
// Or programmatically:
//
//	cfg := &hlog.Config{
//		LogLevel:    hlog.InfoLevel,
//		LogOutput:   "both",
//		LogDir:      "/var/log/myapp",
//		LogFileName: "server.log",
//		LogAppend:   true,
//	}
//
// # Log Levels
//
// hlog supports the following log levels (from most to least verbose):
//   - trace: Very detailed debugging information
//   - debug: Detailed debugging information
//   - info: General informational messages
//   - warn: Warning messages for potentially harmful situations
//   - error: Error messages for error events
//   - fatal: Fatal messages that will exit the application
//   - panic: Panic messages that will panic the application
//
// # Output Modes
//
//   - console: Logs to the provided io.Writer (typically os.Stdout or os.Stderr)
//   - file: Logs to a file in the configured directory
//   - both: Logs to both console and file simultaneously using zerolog.MultiLevelWriter
//
// # File Management
//
// When using file output, hlog creates a file with the specified name in the
// configured directory. The file can be opened in append mode (default) to
// preserve logs across application restarts, or in overwrite mode to start
// fresh each time. Remember to call CloseLogFile() when shutting down your
// application to ensure all logs are flushed to disk.
//
// # Error Stack Traces
//
// hlog automatically configures zerolog to include stack traces for errors
// wrapped with github.com/pkg/errors. This provides detailed error context
// when using errors.Wrap or errors.WithStack.
//
// # Integration
//
// hlog integrates with:
//   - git.haelnorr.com/h/golib/env: For environment variable configuration
//   - github.com/rs/zerolog: The underlying logging implementation
//   - github.com/pkg/errors: For error stack trace support
package hlog