class Console::Filter

A log filter which can be used to filter log messages based on severity, subject, and other criteria.

Attributes

level [R]

@attribute [Integer] The current log level.

options [RW]

@attribute [Hash] Additional options.

output [RW]

@attribute [Console::Output] The output destination.

subjects [R]

@attribute [Hash(Module, Integer)] The log levels for specific subject (classes).

verbose [R]

@attribute [Boolean] Whether to enable verbose output.

Public Class Methods

[] (**levels)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 34
def self.[] **levels
        klass = Class.new(self)
        minimum_level, maximum_level = levels.values.minmax
        
        klass.instance_exec do
                const_set(:LEVELS, levels.freeze)
                const_set(:MINIMUM_LEVEL, minimum_level)
                const_set(:MAXIMUM_LEVEL, maximum_level)
                
                # The default log level for instances of this filter class.
                # Set to MINIMUM_LEVEL to allow all messages by default.
                const_set(:DEFAULT_LEVEL, minimum_level)
                
                levels.each do |name, level|
                        const_set(name.to_s.upcase, level)
                        
                        define_immutable_method(name) do |subject = nil, *arguments, **options, &block|
                                if self.enabled?(subject, level)
                                        @output.call(subject, *arguments, severity: name, **@options, **options, &block)
                                end
                                
                                return nil
                        end
                        
                        define_immutable_method("#{name}!") do
                                @level = level
                        end
                        
                        define_immutable_method("#{name}?") do
                                @level <= level
                        end
                end
        end
        
        return klass
end

Create a new log filter with specific log levels.

“‘ruby class MyLogger < Console::Filter[debug: 0, okay: 1, bad: 2, terrible: 3] “`

@parameter levels [Hash(Symbol, Integer)] A hash of log levels.

define_immutable_method (name, &block)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 16
def self.define_immutable_method(name, &block)
        block = Ractor.make_shareable(block)
        self.define_method(name, &block)
end

Define a method which can be shared between ractors.

new (output, verbose: true, level: nil, **options)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 77
def initialize(output, verbose: true, level: nil, **options)
        @output = output
        @verbose = verbose
        
        # Set the log level using the behaviour implemented in `level=`:
        if level
                self.level = level
        else
                @level = self.class::DEFAULT_LEVEL
        end
        
        @subjects = {}
        
        @options = options
end

Create a new log filter.

@parameter output [Console::Output] The output destination. @parameter verbose [Boolean] Enable verbose output. @parameter level [Integer] The log level. @parameter options [Hash] Additional options.

If the severity is not defined in this filter’s LEVELS (e.g., when chaining filters with different severity levels), the message is passed through to the output without filtering. This allows custom filters to be composed together.

@parameter subject [Object] The subject of the log message. @parameter arguments [Array] The arguments to log. @parameter options [Hash] Additional options to pass to the output. @parameter block [Proc] A block passed to the output. @returns [Nil] Always returns nil.

clear (subject)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 203
def clear(subject)
        unless subject.is_a?(Module)
                raise ArgumentError, "Expected a class, got #{subject.inspect}"
        end
        
        @subjects.delete(subject)
end

Clear any specific filters for the given class.

@parameter subject [Module] The class to disable.

disable (subject)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 195
def disable(subject)
        # Set the filter level of the logging for a given subject which filters all log messages:
        filter(subject, self.class::MAXIMUM_LEVEL + 1)
end

Disable logging for the given class.

@parameter name [Module] The class to disable.

enable (subject, level = self.class::MINIMUM_LEVEL)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 187
def enable(subject, level = self.class::MINIMUM_LEVEL)
        # Set the filter level of logging for a given subject which passes all log messages:
        filter(subject, level)
end

Enable specific log level for the given class.

@parameter name [Module] The class to enable.

enabled? (subject, level = self.class::MINIMUM_LEVEL)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 172
def enabled?(subject, level = self.class::MINIMUM_LEVEL)
        subject = subject.class unless subject.is_a?(Module)
        
        if specific_level = @subjects[subject]
                return level >= specific_level
        end
        
        if level >= @level
                return true
        end
end

Whether logging is enabled for the given subject and log level.

You can enable and disable logging for classes. This function checks if logging for a given subject is enabled.

@parameter subject [Module | Object] The subject to check. @parameter level [Integer] The log level. @returns [Boolean] Whether logging is enabled.

filter (subject, level)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 157
def filter(subject, level)
        unless subject.is_a?(Module)
                raise ArgumentError, "Expected a class, got #{subject.inspect}"
        end
        
        @subjects[subject] = level
end

Filter log messages based on the subject and log level.

You must provide the subject’s class, not an instance of the class.

@parameter subject [Module] The subject to filter. @parameter level [Integer] The log level.

level= (level)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 125
def level= level
        if level.is_a? Symbol
                @level = self.class::LEVELS[level]
        else
                @level = level
        end
end

Set the log level.

@parameter level [Integer | Symbol] The log level.

off! ()

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 142
def off!
        @level = self.class::MAXIMUM_LEVEL + 1
end

Disable all logging.

verbose! (value = true)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 136
def verbose!(value = true)
        @verbose = value
        @output.verbose!(value)
end

Set verbose output (enable by default with no arguments).

@parameter value [Boolean] Enable or disable verbose output.

with (level: @level, verbose: @verbose, **options)

Source

# File vendor/bundle/ruby/4.0.0/gems/console-1.34.3/lib/console/filter.rb, line 99
def with(level: @level, verbose: @verbose, **options)
        dup.tap do |logger|
                logger.level = level
                logger.verbose! if verbose
                logger.options = @options.merge(options)
        end
end

Create a new log filter with the given options, from an existing log filter.

@parameter level [Integer] The log level. @parameter verbose [Boolean] Enable verbose output. @parameter options [Hash] Additional options. @returns [Console::Filter] The new log filter.