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