Module: Lumberjack::IOCompatibility

Defined in:
lib/lumberjack/io_compatibility.rb

Overview

IOCompatibility provides methods that allow a logger to be used as an IO-like stream. This enables loggers to be used anywhere an IO object is expected, such as for redirecting standard output/error or integrating with libraries that expect stream objects.

When used as a stream, all written values are logged with UNKNOWN severity and include timestamps and other standard log entry metadata. This is particularly useful for:

  • Capturing output from external libraries or subprocesses

  • Redirecting STDOUT/STDERR to logs

  • Providing a logging destination that conforms to IO interface expectations

The module implements the essential IO methods like write, puts, print, printf, flush, and close to provide broad compatibility with Ruby’s IO ecosystem.

Examples:

Basic stream usage

logger = Lumberjack::Logger.new(STDOUT)
logger.puts("Hello, world!")  # Logs with UNKNOWN severity
logger.write("Direct write")  # Also logs with UNKNOWN severity

Setting the log entry severity

logger = Lumberjack::Logger.new(STDOUT)
logger.default_severity = :info
logger.puts("This is an info message") # Logs with INFO severity

Using as STDOUT replacement

logger = Lumberjack::Logger.new("/var/log/app.log")
$stdout = logger  # Redirect all puts/print calls to the logger
puts "This goes to the log file"

Instance Method Summary collapse

Instance Method Details

#close ⇒ nil

Close the stream. This method is provided for IO compatibility but is a no-op. To actually close a logger, call close on the logger object itself, which will close the underlying logging device.

Returns:

  • (nil) 


102
103
 
# File 'lib/lumberjack/io_compatibility.rb', line 102

def close
end

#closed? ⇒ Boolean

Check if the stream is closed. Always returns false since loggers using this module don’t maintain a closed state through this interface.

Returns:

  • (Boolean) —

    Always returns false.



109
110
111
 
# File 'lib/lumberjack/io_compatibility.rb', line 109

def closed?
  false
end

#flush ⇒ nil

Flush any buffered output. This method is provided for IO compatibility but is a no-op since log entries are typically written immediately to the underlying device. The actual flushing behavior depends on the logging device being used.

Returns:

  • (nil) 


94
95
 
# File 'lib/lumberjack/io_compatibility.rb', line 94

def flush
end

#print(*args) ⇒ nil

Concatentate strings into a single log entry. This mimics IO#print behavior by writing arguments without separators. If no arguments are given, writes the value of the global $_ variable.

Examples:

logger.print("Hello", " ", "World")  # Single log entry: "Hello World"

Parameters:

  • args (Array<Object>) —

    The messages to write. If empty, uses $_ (last input record).

Returns:

  • (nil) 


65
66
67
68
69
70
71
72
 
# File 'lib/lumberjack/io_compatibility.rb', line 65

def print(*args)
  if args.empty?
    write($_)
  else
    write(args.join(""))
  end
  nil
end

#printf(format, *args) ⇒ nil

Write a formatted string to the log using sprintf-style formatting. The formatted result is logged as a single entry with UNKNOWN severity.

Examples:

logger.printf("User %s logged in at %s", "alice", Time.now)
# Logs: "User alice logged in at 2025-08-21 10:30:00 UTC"

Parameters:

  • format (String) —

    The format string (printf-style format specifiers).

  • args (Array<Object>) —

    The values to substitute into the format string.

Returns:

  • (nil) 


84
85
86
87
 
# File 'lib/lumberjack/io_compatibility.rb', line 84

def printf(format, *args)
  write(format % args)
  nil
end

#puts(*args) ⇒ nil

Write multiple values to the log, each as a separate log entry with UNKNOWN severity. This method mimics the behavior of IO#puts by writing each argument on a separate line.

Parameters:

  • args (Array<Object>) —

    The messages to write. Each will be converted to a string.

Returns:

  • (nil) 


49
50
51
52
53
54
 
# File 'lib/lumberjack/io_compatibility.rb', line 49

def puts(*args)
  args.each do |arg|
    write(arg)
  end
  nil
end

#set_encoding(_encoding) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the encoding for the stream. This method is provided for IO compatibility but is a no-op since loggers handle encoding internally through their devices and formatters.

Parameters:

  • _encoding (String, Encoding) —

    The encoding to set (ignored).

Returns:

  • (nil) 


130
131
 
# File 'lib/lumberjack/io_compatibility.rb', line 130

def set_encoding(_encoding)
end

#tty? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if the stream is connected to a terminal (TTY). Always returns false since loggers are not terminal devices, even when they write to STDOUT/STDERR. This method is required for complete IO compatibility.

Returns:

  • (Boolean) —

    Always returns false.



119
120
121
 
# File 'lib/lumberjack/io_compatibility.rb', line 119

def tty?
  false
end

#write(value) ⇒ Integer

Write a value to the log as a log entry. The value will be recorded with UNKNOWN severity, ensuring it always appears in the log regardless of the current log level.

Parameters:

  • value (Object) —

    The message to write. Will be converted to a string for logging.

Returns:

  • (Integer) —

    Returns 1 if a log entry was written, or 0 if the value was nil or empty.



37
38
39
40
41
42
 
# File 'lib/lumberjack/io_compatibility.rb', line 37

def write(value)
  return 0 if value.nil? || value == ""

  self << value
  1
end