logjam 1.0.0 → 1.2.3

data/lib/logjam/configuration.rb

@@ -0,0 +1,13 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2015 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module LogJam
+  class Configuration < Configurative::Settings
+    sources *(Dir.glob(File.join(Dir.getwd, "logging.{yml,yaml,json}")) +
+              Dir.glob(File.join(Dir.getwd, "config", "logging.{yml,yaml,json}")) +
+              Dir.glob(File.join(Dir.getwd, "**", "application.{yml,yaml,json}")))
+    section "logging"
+  end
+end

data/lib/logjam/exceptions.rb

@@ -7,34 +7,17 @@ require 'stringio'
 
 module LogJam
    # This class provides the exception class used by the LogJam library.
-   class LogJamError < StandardError
-      # Attribute accessor/mutator declarations.
-      attr_accessor :verbose
-
-      # Constructor for the LogJamError class.
+   class Error < StandardError
+      # Constructor for the LogJam::Error class.
       #
       # ==== Parameters
       # message::  The message to be associated with the error.
       # cause::    Any underlying exception to be associated with the error.
       #            Defaults to nil.
-      def initialize(message, cause=nil, verbose=true)
+      def initialize(message, cause=nil)
          super(message)
-         @cause   = cause
-         @verbose = verbose
-      end
-
-      # This method fetches a stringified interpretation of an exception.
-      def to_s()
-         text = StringIO.new
-         text << super
-         if @verbose
-            text << "\n" + self.backtrace.join("\n")
-            if !@cause.nil?
-               text << "\n\nCause: #{@cause}"
-               text << "\n" + @cause.backtrace.join("\n")
-            end
-         end
-         text.string
+         @cause = cause
       end
+      attr_reader :cause
    end
-end
+end

data/lib/logjam/logger.rb

@@ -0,0 +1,62 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module LogJam
+  # This class represents a specialization of the Ruby Logger class. The class
+  # retains a Ruby Logger instance within itself and delegates all standard
+  # logger calls to this instance. This allows for changes to the underlying
+  # logger without changing the containing one, thus bypassing people caching
+  # an instance.
+  class Logger < ::Logger
+    extend Forwardable
+    def_delegators :@log, :add, :close, :datetime_format, :datetime_format=,
+                          :debug, :debug?, :error, :error?, :fatal, :fatal?,
+                          :formatter, :formatter=, :info, :info?, :level,
+                          :level=, :progname, :progname=, :sev_threshold,
+                          :sev_threshold=, :unknown, :warn, :warn?
+
+    # Constructor for the Logger class. All parameters are passed
+    # straight through to create a standard Ruby Logger instance except
+    # when the first parameter is a Logger instance. In this case the
+    # Logger passed in is used rather than creating a new one.
+    #
+    # ==== Parameters
+    # logdev::      The log device to be used by the logger. This should be
+    #               be a String containing a file path/name, an IO object that
+    #               the logging details will be written to or another logger
+    #               that you want to wrap.
+    # shift_age::   The maximum number of old log files to retain or a String
+    #               containing the rotation frequency for the log.
+    # shift_size::  The maximum size that the logging output will be allowed
+    #               to grow to before rotation occurs.
+    def initialize(logdev, shift_age=0, shift_size=1048576)
+      @log = (logdev.kind_of?(::Logger) ? logdev : ::Logger.new(logdev, shift_age, shift_size))
+      @name = nil
+    end
+
+    # Attribute accessor/mutator declaration.
+    attr_accessor :name
+
+    # This method fetches the standard Ruby Logger instance contained within
+    # a Logger object.
+    def logger
+      @log
+    end
+
+    # This method updates the logger instance contained within a Logger
+    # object.
+    #
+    # ==== Parameters
+    # logger::  The object to set as the contained logger. This should be an
+    #           instance of the standard Ruby Logger class or something
+    #           compatible with this.
+    def logger=(logger)
+      @log = logger
+    end
+
+    # Aliases
+    alias :log :add
+  end
+end

data/lib/logjam/object.rb

@@ -0,0 +1,33 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2013 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+class Object
+  # This method provides an instance level accessor to obtain a logger. Unless
+  # a name is specified the logger returned is the default one.
+  def log
+    LogJam.get_logger
+  end
+
+  # This method provides a class level accessor to obtain a logger. Unless a
+  # name is specified the logger returned is the default one.
+  def self.log
+    LogJam.get_logger
+  end
+
+  def self.log=(logger)
+    LogJam.get_logger.logger = logger
+  end
+
+  # This method allows a class to specify the name of the logger that it uses
+  # once, generally within the class definition.
+  #
+  # ==== Parameters
+  # name::     The name of the logger used by the class.
+  # context::  A Hash of additional parameters that are specific to the class
+  #            to which LogJam is being applied.
+  def self.set_logger_name(name, context={})
+    LogJam.apply(self, name, context)
+  end
+end

data/lib/logjam/version.rb

@@ -1,3 +1,3 @@
 module LogJam
-   VERSION="1.0.0"
-end
+   VERSION="1.2.3"
+end

metadata

@@ -1,32 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: logjam
 version: !ruby/object:Gem::Version
-  version: 1.0.0
-  prerelease: 
+  version: 1.2.3
 platform: ruby
 authors:
 - Black North
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-01-26 00:00:00.000000000 Z
+date: 2020-07-28 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: configurative
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: LogJam is a library to simplify the use of logging across libraries and
   applications.
 email: ruby@blacknorth.com
@@ -34,35 +59,35 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/logjam/version.rb
-- lib/logjam/logjam_logger.rb
-- lib/logjam/logjam.rb
-- lib/logjam/exceptions.rb
+- README.md
 - lib/logjam.rb
+- lib/logjam/configuration.rb
+- lib/logjam/exceptions.rb
+- lib/logjam/logger.rb
+- lib/logjam/object.rb
+- lib/logjam/version.rb
 - license.txt
-- README
 homepage: https://github.com/free-beer/LogJam
-licenses: []
-post_install_message: 
+licenses:
+- MIT
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
-specification_version: 3
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
 summary: A library to aggregate logging.
 test_files: []

data/README

@@ -1,321 +0,0 @@
-LogJam
-======
-LogJam is a library that attempts to allow for the aggregation the distributing
-logger facilities across a range of classes. Goals in creating this library
-were...
-
-   * Easy of use. Fall back on defaults as much as possible and allow the
-     functionality to be integrated and used with the least amount of work.
-     
-   * Flexibility. After easy of use is taken into consideration it should be
-     possible to use the library in a more advanced fashion if that is called
-     for.
-     
-   * Minimize the code to use it. It shouldn't require a great deal of code to
-     deploy or use the facilities and there should be no code required to pass
-     entities such as loggers around.
-     
-   * Usable in libraries. I found myself writing a lot of common logging code
-     when writing libraries and application and wanted to abstract that out. I
-     wanted to minimize the burden this placed on library users at the same
-     time.
-
-Configuration & Setup
----------------------
-The LogJam library is configured through a call to the configure() method on the
-LogJam module. This method accepts a single parameter that may be either a
-String, a Hash, an IO object or nil.
-
-If you pass a String in this is expected to contain the path and name of a file
-that contains the logging configuration. Logging configuration files can be
-provided in either YAML or JSON format. If you pass an IO object this is
-expected to be the source of the configuration and, again, this configuration
-should be in either YAML or JSON format. In either case, where a String or IO
-is specified, the data read must be translatable into a Hash, which brings us
-to the other type that the configure() method accepts as a parameter.
-
-A Hash passed to the configure() method is expected to contain a set of values
-that can be converted into a logging set up. Passing an empty Hash will result
-in set up containing a single, universal logger attached to the standard output
-stream being created and used by all classes that have LogJam functionality.
-
-The Hash passed to the configure() method can contain two keys that the library
-will recognise and use. The first of these is 'loggers', in either Symbol or
-String form. The value under the loggers key is expected to be an Array
-containing zero or more logger definitions. A logger definition is a Hash in
-which the following keys are recognised (either as Strings or Symbols)...
-
-   Key                       Description
-   -----------------------   --------------------------------------------------
-   default                   A boolean indicating whether this logger is the
-                             default (i.e. the one to be used when no other
-                             fits the bill). Only one logger should be declared
-                             as a default.
-   datetime_format           The date/time format to be used by the logger. See
-                             the documentation for the standard Ruby Logger
-                             class for more details.
-   file                      The path and name of the file that logging details
-                             will be written to. Two special values are
-                             recognised in this value. STDOUT and STDERR are
-                             translated to mean the standard output or error
-                             streams respectively.
-   level                     The logging level to set on the logger. If not
-                             explicitly specified this defaults to DEBUG.
-   max_size                  When rotation is set to an integer value this value
-                             can be set to indicate the maximum permitted file
-                             size for a log file.
-   name                      The name to associate with the logger. This allows
-                             loggers to be tied to classes or for the creation
-                             of aliases that tie multiple names to a single
-                             logger. Note that you should always use Strings
-                             (and not Symbols) when specifying aliases.
-   rotation                  The frequency with which the log file is rotated.
-                             This may be an integer to indicate how many old log
-                             files are retained or may be a String such as
-                             "daily", "weekly" or "monthly".
-
-A note on logger names. Logger names (including alias names) aren't hierarchical
-and should be unique.
-
-The second key recognised in the configuration Hash is 'aliases', again as
-either a String or Symbol. The value under the aliases key is expected to be a
-Hash that maps String keys to String values. The key values are expected to be
-alias names and the mapped values are expected to be the name of a logger
-declared in the logger section. An entry in the aliases Hash creates an alias
-for an existing logger under a different name.
-
-If you pass nil to the configure method it behaves in a slightly different
-fashion. In this case the method searches for a configuration file that it can
-use given a default set of files names (basically logging.yaml, logging.yml and
-logging.json in the current working directory and in a subdirectory of the
-current working directory called config). The first of these files that it finds
-it attempts to use as configuration for the logging set up. If it doesn't find
-a configuration file then this type of call becomes equivalent to passing an
-empty Hash to the configure() method.
-
-See the end of this document for some example configurations.
-
-Logging With The Library
-------------------------
-The stated goals of the LogJam library are to avoid the need to pass Logger
-instances around while still allowing potentially complex configuration with a
-minimum of code. The first step in this process has been covered in the
-Configuration & Setup section in which it's explained how to configure logging
-from a single Hash or file. This section will provide details on how to deploy
-loggers to various classes.
-
-The LogJam library works by providing an extension to any class that uses it
-that provides access to the logger to be used by the class. To make use of this
-functionality a class must call the apply() method of the LogJam module. A
-typical call to this method might look like...
-
-   LogJam.apply(self, "my_logger")
-   
-This line would appear somewhere inside the definition for the class that will
-use logging. The first parameter to the call is the class that is to be extended
-with the LogJam functionality. The second parameter is the name of the logger
-that the class will use. Note that this parameter is optional and, if not
-specified or if a matching logger does not exist, the class will fall back in
-using the default logger.
-
-Once this line has been added to the class definition it will cause the class to
-be extended with three methods - two class level methods (one called log() and
-one called log=()) and an instance level method called log(). The log() methods
-retrieve the Logger instance to be used by the class instances. The log=()
-method allows the Logger instance associated with a class to be altered. Note
-the instance level log() method will only be added if an existing method with
-that name does not already exist on the class.
-
-The following complete (although contrived) example gives an overview of how
-this would work...
-
-   require 'rubygems'
-   require 'logjam'
-   
-   class Writer
-      LogJam.apply(self, "echo")
-      
-      def initialize(stream=STDOUT)
-         @stream = stream
-      end
-      
-      def echo(message)
-         Writer.log.debug("Echoed: #{message}")
-         @stream.puts message
-      end
-   end
-   
-   begin
-      LogJam.configure({:loggers => [{:name => "echo",
-                                      :file => "echo.log"}]})
-                                      
-      writer = Writer.new
-      writer.echo "This is a string containing my message."
-   rescue => error
-      puts "ERROR: #{error}\n" + error.backtrace.join("\n")
-   end
-
-In this example we create a Writer class that can echo a String on a stream. In
-doing this it also logs the message echoed at the debug level. We use the
-LogJam.apply() method to extend this class with logging capabilities so that, in
-the echo() method, we can simply call Writer.log() to get the class logger.
-
-In the later section of the code we configure the LogJam system to have a single
-Logger that writes to the echo.log file. We then create a Writer instance and
-use it to write a simple message. This message should appear on the standard
-output stream and be logged to the echo.log file.
-
-Advanced Usage
---------------
-The hope would be that this library can be used in the creation of other
-libraries and allow for control of the logging generated by those libraries
-without having to dig into the workings of the library or to pass around Logger
-instances are constructor parameters or static data. In this case I recommend
-explicitly declaring logger names when using the apply() method and making the
-name that the library uses available with the library documentation so that the
-libraries logging can be switched off or on as needed.
-
-It's intended that, in general, the configure() method on the LogJam module
-should only be called once. Calling it a second time will clear all existing
-logging configuration and set up. This may or may not be an issue depending on
-whether you decide to cache logger inside class instances instead of always
-accessing them through the class level accessor.
-
-The Logger instance returned from a LogJam are intended to be fully compatible
-with the class defined within the standard Ruby Logger library. If you need to
-change elements, such as the formatter, you should just do so on the logger in
-the normal fashion. If you define multiple Logger instances then you will have
-to change each individually.
-
-Using the log=() method that is added to each class by the LogJam facilities it
-is possible to change the Logger being used. If you want to use this method
-please note that changing a Logger that is created via an alias will change the
-original Logger and thereby affect all classes that make use of that Logger (and
-not necessarily just the one making the change). If you want to do this give the
-class it's own logger instance.
-
-Finally, any logger can be fetched from the library using it's name and making
-a call to the LogJam.get_logger() method. Note if you omit the name or pass in
-nil you will retrieve the libraries default logger.
-
-Example Configurations
-----------------------
-This section contains some example configurations. A short explanation is given
-for each configuration and then the configuration itself in Hash, YAML and JSON
-formats is provided.
-
-This represents the most basic configuration possible. In passing an empty Hash
-to the configure method the system creates a single, default logger that writes
-everything on the standard output stream...
-
-Hash
-   {}
-   
-YAML
-   ---
-   {}
-
-JSON
-   {}
-
-The following simple configuration writes all logging output to a file called
-application.log in the current working directory. If a logging level is not
-explicitly specified then DEBUG is the default...
-
-Hash
-   {:loggers => [{:default => true, :file => "application.log"}]}
-
-YAML
-   --- 
-   :loggers: 
-   - :default: true
-     :file: application.log
-
-JSON
-   {"loggers": {"default": true, "file": "application.log"}}
-   
-This configuration declares two loggers. The first is called 'silent' and will
-log nothing. The silent logger is the default and so will be used for any class
-that doesn't have an explicitly named logger. The second is called 'verbose' and
-logs everything from the debug level up on the standard output stream. The
-configuration also declares an alias pointing the name 'database' to refer to
-the verbose logger. An class that declares it uses the 'database' logger will
-generate output while all others will be silenced.
-
-Hash
-   {:loggers => [{:default => true,
-                  :file    => "STDOUT",
-                  :level   => "UNKNOWN",
-                  :name    => "silent"},
-                 {:file    => "STDOUT",
-                  :name    => "verbose"}],
-    :aliases => {"database" => "verbose"}}
-
-YAML
-   --- 
-   :loggers: 
-   - :default: true
-     :file: STDOUT
-     :level: UNKNOWN
-     :name: silent
-   - :file: STDOUT
-     :name: verbose
-   :aliases: 
-     database: verbose
-
-JSON
-   {"loggers": [{"default":true,
-                 "file": "STDOUT",
-                 "level": "UNKNOWN",
-                 "name": "silent"},
-                {"file": "STDOUT",
-                 "name": "verbose"}],
-    "aliases": {"database":"verbose"}}
-
-The following configuration can be used as an example of how to drive logging
-from different parts of the code to different destinations. The configuration
-declares two loggers which deliver their output to two different log files and
-then declares aliases for those loggers that can be used to divide up the
-logging coming from different areas of the code.
-
-Hash
-   {:loggers => [{:default => true,
-                  :file    => "./log/main.log",
-                  :name    => "main"},
-                 {:file    => "./log/secondary.log",
-                  :name    => "secondary"}],
-    :aliases => {"database"   => "secondary",
-                 "model"      => "secondary",
-                 "controller" => "main"}}
-
-YAML
-   --- 
-   :loggers: 
-   - :default: true
-     :file: ./log/main.log
-     :name: main
-   - :file: ./log/secondary.log
-     :name: secondary
-   :aliases: 
-     database: secondary
-     model: secondary
-     controller: main
-
-JSON
-   {"loggers": [{"default":true,
-                 "file": "./log/main.log",
-                 "name": "main"},
-                {"file": "./log/secondary.log",
-                 "name": "secondary"}],
-    "aliases": {"database":"secondary",
-                "model": "secondary",
-                "controller": "main"}}
-
-Testing
--------
-LogJam uses the test-unit Ruby library for testing. The best approach to running
-the tests are to create a new gemset (assuming you're using RVM), do a bundle
-install on this gemset from within the LogJam root directory and then use a
-command such as the following to run the tests...
-
-    $> ruby -I./lib -I./test ./test/unit/test_logjam.rb