Module: Polylog

Extended by:
Polylog
Included in:
Polylog
Defined in:
lib/polylog.rb,
lib/polylog/errors.rb,
lib/polylog/null_logger.rb,
lib/polylog/solo_provider.rb,
lib/polylog/multi_provider.rb

Defined Under Namespace

Classes: MultiProvider, NullLogger, SoloProvider

Constant Summary collapse

LIBPATH = 
::File.expand_path('../', __FILE__)
PATH = 
::File.dirname(LIBPATH)
Error =

Parent class for all Polylog errors.

Class.new StandardError
UnknownProvider =

This is error is raised when an unknown provider is requested by the user.

Class.new Error
InvalidProvider =

This is error is raised when a provider is registered and it does not respond to the ‘logger` method or the `logger` method has an arity other than 1.

Class.new Error

Instance Method Summary collapse

Instance Method Details

#libpath(*args) ⇒ Object

Internal: Returns the library path for the module. If any arguments are given, they will be joined to the end of the library path using ‘File.join`.



129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/polylog.rb', line 129

def libpath( *args )
  rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
  if block_given?
    begin
      $LOAD_PATH.unshift LIBPATH
      rv = yield
    ensure
      $LOAD_PATH.shift
    end
  end
  return rv
end

#logger(object = nil) ⇒ Object

Request a logger instance for the given object from the configured provider.

object - Any ruby object

Returns a logger instance from the provider.



11
12
13
14
 
# File 'lib/polylog.rb', line 11

def logger( object = nil )
  name = logger_name object
  provider.logger name
end

#logger_name(object) ⇒ Object

Internal: Given any ruby object, try to construct a sensible logger name to use for looking up specific logger instances from a provider. For nearly every object passed in this will be the class name of the instance.

If you pass in ‘nil` or a String then the original object is return. Symbols will be converted to Strings.

The only objects we cannot generate a logger name for are anonymous modules. For these we just return ‘nil`.

object - Any ruby object

Returns the logger name String or nil.



84
85
86
87
88
89
90
91
 
# File 'lib/polylog.rb', line 84

def logger_name( object )
  case object
  when nil, String; object
  when Symbol; object.to_s
  when Module; logger_name_for_module(object)
  when Object; logger_name_for_module(object.class)
  end
end

#logger_name_for_module(mod) ⇒ Object

Internal: Generate logger names for classes, modules, singleton classes, and anonymous modules. For all of these we use the class name or the module name. For anonymous modules we return ‘nil`.

mod - A Module or Class

Returns the logger name String or nil.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/polylog.rb', line 100

def logger_name_for_module( mod )
  return mod.name unless mod.name.nil? or mod.name.empty?

  # check if we have a metaclass (or eigenclass)
  if mod.ancestors.include? Class
    mod.inspect =~ %r/#<Class:([^#>]+)>/
    return $1
  end

  # see if we have a superclass
  if mod.respond_to? :superclass
    return logger_name_for_module(mod.superclass)
  end

  # we have an anonymous module
  return nil
end

#path(*args) ⇒ Object

Internal: Returns the path for the module. If any arguments are given, they will be joined to the end of the path using ‘File.join`.



144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/polylog.rb', line 144

def path( *args )
  rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
  if block_given?
    begin
      $LOAD_PATH.unshift PATH
      rv = yield
    ensure
      $LOAD_PATH.shift
    end
  end
  return rv
end

#provider ⇒ Object

Return the currently selected provider. If a provider has not yet been specified, then the “null” provider will be used.

Returns a logger provider.



20
21
22
23
 
# File 'lib/polylog.rb', line 20

def provider
  use_provider('null') unless defined? @provider
  @provider
end

#providers ⇒ Object

Returns the list of available providers as an Array of Strings. These names are used to select which provider to use.



27
28
29
 
# File 'lib/polylog.rb', line 27

def providers
  @providers.keys
end

#register_provider(name, provider) ⇒ Object

Register a logger provider under the given name. The provider can be any Ruby object that responds to the ‘logger` method and returns valid logger instances. An exception is raised if the provider does not respond to the `logger` method or the `logger` method does not have an arity of 1.

name - The provider name as a String. provider - The provider object that responds to the ‘logger` method.

Returns the logger provider. Raises a Polylog::InvalidProvider exception.



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/polylog.rb', line 55

def register_provider( name, provider )
  @providers ||= Hash.new
  name = name.to_s

  unless provider.respond_to?(:logger)
    raise Polylog::InvalidProvider, "`logger` method not found for provider #{name.inspect}"
  end

  arity = provider.method(:logger).arity
  unless 1 == arity
    raise Polylog::InvalidProvider, "`logger` method arity must be 1; arity is #{arity} for provider #{name.inspect}"
  end

  @providers[name] = provider
end

#use_provider(name) ⇒ Object

Configure the logger provider that will be used by Polylog. The provider must already be registered using the same ‘name`.

name - The provider name as a String.

Returns the logger provider. Raises a Polylog::UnknownProvider exception.

Raises:



38
39
40
41
42
43
 
# File 'lib/polylog.rb', line 38

def use_provider( name )
  name = name.to_s
  raise Polylog::UnknownProvider, "unknown provider: #{name.inspect}" unless @providers.key? name

  @provider = @providers[name]
end

#version ⇒ Object

Returns the version String for the library.



122
123
124
 
# File 'lib/polylog.rb', line 122

def version
  @version ||= File.read(path('version.txt')).strip
end