NAME
    G::LOG - Pure Perl Object-Oriented Logging Module
    glog - Simple Functional Logging Interface for G::LOG

SYNOPSIS
    Using glog for simple logging:

      use glog;

      # Set log level
      LogLevel(5); # Enable debug logging

      # Log messages
      LogInfo("Application started");
      LogDebug("Debug details: x=42");
      LogWarn("Warning: low disk space");
      LogErr("Error: cannot open file");
      LogDie("Fatal error!"); # Logs and dies

      # Formatted logging
      LogF(3, "User %s logged in at %d", "alice", time);

      # Log to file
      LogFile("app.log");
      LogInfo("Logging to file");
      LogFile(undef); # Revert to STDERR

    Using G::LOG for advanced logging:

      use G::LOG;

      # Create a logger instance
      my $logger = G::LOG->new;

      # Set log level
      $logger->LogLevel(3);

      # Log messages
      $logger->LogInfo("Starting process");
      $logger->LogFormat(3, "Processing %d items", 42);

      # Log to file
      $logger->LogFile("process.log");
      $logger->LogWarn("Potential issue detected");
      $logger->LogFile(undef); # Back to STDERR

DESCRIPTION
    G::LOG is a high-performance, Pure Perl object-oriented logging module designed for
    the G collection, providing robust logging capabilities with support for multiple
    log levels (ERROR, WARN, INFO, DEBUG), timestamped output, and flexible output
    destinations (STDERR or file). The glog module serves as a lightweight, functional
    proxy, offering a simple interface that delegates all operations to a global G::LOG
    instance.

    These modules are built to be fast, reliable, and easy to integrate into both small
    scripts and large systems, maintaining the quality standards of other G collection
    modules like G::SHA, G::MD5, and G::CRC.

FEATURES
    - Pure Perl: No external dependencies beyond standard Perl modules and gerr.
    - Flexible Logging: Supports ERROR (1), WARN (2), INFO (3), and DEBUG (5) levels.
    - Timestamped Output: High-resolution timestamps using Time::HiRes.
    - Output Options: Log to STDERR or a file, with seamless switching.
    - Simple Interface: glog provides a drop-in functional API (LogInfo, LogWarn, etc.).
    - Object-Oriented Core: G::LOG encapsulates all logic, allowing multiple logger instances.
    - Standards Compliant: Consistent with the G collection's design principles.

INSTALLATION
    To install this module, run the following commands:

      perl Makefile.PL
      make
      make test
      make install

    Alternatively, install directly from CPAN:

      cpan glog

DEPENDENCIES
    - Core Perl modules: Exporter, strict, warnings, Time::HiRes, POSIX
    - Required: gerr (for error handling, available on CPAN)
    - Testing: Test::More (>= 0.88)

LOG LEVELS
    - 1: ERROR - Critical errors
    - 2: WARN - Warnings
    - 3: INFO - Informational messages
    - 5: DEBUG - Detailed debugging information

    Messages are only logged if their level is less than or equal to the current log level.

OUTPUT FORMAT
    Log messages follow this format:

      [YYYY-MM-DD HH:MM:SS.mmm] LEVEL message

    Example:

      [2025-04-25 20:15:23.456] INFO Application started

PERFORMANCE
    G::LOG and glog are optimized for minimal overhead:
    - Early level checks to skip unnecessary processing.
    - Efficient timestamp generation with Time::HiRes.
    - Lightweight proxy in glog with direct delegation to G::LOG.
    - Reusable file handles and configuration state.

    Benchmarks in the test suite demonstrate low-latency logging even for high-frequency calls.

TESTING
    The distribution includes comprehensive tests in the t/ directory, covering:
    - All log levels and message types.
    - Formatted logging with LogF.
    - File-based logging with LogFile.
    - Error handling and LogDie behavior.

    Run tests with:

      make test

DOCUMENTATION
    Detailed documentation is available in the POD sections of each module:

      perldoc glog
      perldoc G::LOG

LIMITATIONS
    - No built-in log rotation for file-based logging.
    - No native threading support.
    - Log files are opened in append mode without automatic rotation.

CONTRIBUTING
    Contributions are welcome! Please submit issues or pull requests at:

      https://github.com/onehippy/G-LOG

    See CONTRIBUTING.md (if available) for guidelines.

LICENSE
    This module is released under the MIT License. See the LICENSE file for details.

AUTHOR
    OnEhIppY <domerosoftware@gmail.com>, Domero Software

SUPPORT
    Please report issues at:

      https://github.com/onehippy/G-LOG/issues

COPYRIGHT
    Copyright (c) 2025 OnEhIppY, Domero Software