log_switch 0.4.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ecedbe5e49ac7e09fd71760ccec36aedf1270f72029101fffd3219d4447da256
+  data.tar.gz: c2968035a4838d42cb787439f3ba65497666105d4ba04c163e3983f2cdbb7c43
+SHA512:
+  metadata.gz: e293009d9babdd7ba1236a18679e44faf3158bcc286215ddebb3de51e3ea29c3a27c9e38e3d1e8cb832d772ad839ef6fdf1dce864060f08088e51483afaeb64a
+  data.tar.gz: 1ca8b618a1419224bd546c2c301a60e54a58727577569e8369b7b61f1686f37dfcf9b64e05a703275d1428e5a593718d2be98a7bd735dfdf29920a7b78a33dcd

data/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2026-07-15
+
+### Added
+
+- Declared the license (Unlicense) in the gemspec; the LICENSE file now ships with the gem.
+- The gemspec now declares a `changelog_uri`, so rubygems.org links to the changelog. It points at
+  the released version's tag rather than a branch, so each release's link is immutable.
+
+### Changed
+
+- The gemspec now requires Ruby >= 3.3. Older Rubies will continue to resolve to 1.0.0.
+- Replaced the tailor linter with RuboCop, and the dead Travis config with GitHub Actions, testing
+  Ruby 3.3, 3.4 and 4.0.
+
+### Fixed
+
+- Declared `logger` as a runtime dependency. `lib/log_switch.rb` has always required it, but the
+  gemspec never declared it — so under Bundler on Ruby 4.0, where `logger` is no longer a default
+  gem, requiring `log_switch` raised LoadError.
+
+## [1.0.0] - 2014-10-10
+
+### Added
+
+- LogSwitch can now be included in your own module, then that included in other modules. This allows
+  toggling logging per includer.
+
+### Removed
+
+- Removed `LogSwitch::Mixin` in favor of simpler implementation.
+
+### Fixed
+
+- [gh-5](https://github.com/turboladen/log_switch/issues/5): The improvements listed above alleviate
+  this problem.
+
+## 0.4.1 - 2013-01-04
+
+### Fixed
+
+- Initialize `@log` before calling it, thus removing warnings when running with `-w`.
+
+## [0.4.0] - 2012-11-12
+
+### Added
+
+- [gh-4](https://github.com/turboladen/log_switch/issues/4): Added ability to toggle the prepending
+  of the class name to log messages. This lets you know which class/object is logging each message —
+  useful for when you have a number of different classes logging.
+
+## [0.3.0] - 2012-02-03
+
+### Added
+
+- [gh-2](https://github.com/turboladen/log_switch/issues/2): Added ability to mix in
+  `LogSwitch::Mixin` to classes to allow calling `#log` in your class and have it delegate to your
+  singleton logger.
+
+### Fixed
+
+- [gh-3](https://github.com/turboladen/log_switch/issues/3): Fixed warning on `@before_block`.
+
+## [0.2.0] - 2011-12-05
+
+### Added
+
+- Added ability to pass a block to `.log` to have code executed before logging.
+- Added `before` hook to allow code to be executed every time log gets called (but before the
+  message actually gets logged).
+
+### Fixed
+
+- [gh-1](https://github.com/turboladen/log_switch/issues/1): Only log `#each_line` when that method
+  is supported on the object being logged.
+
+## [0.1.4] - 2011-10-10
+
+### Removed
+
+- Removed gemspec enforcement of >= 1.9.2
+
+## [0.1.3] - 2011-10-10
+
+### Added
+
+- Made 1.8.7 compatible.
+
+### Removed
+
+- Removed dev deps: metric_fu, code_statistics
+
+## [0.1.2] - 2011-10-09
+
+### Fixed
+
+- Just realized author is supposed to be my real name. :)
+
+## [0.1.1] - 2011-10-09
+
+### Fixed
+
+- Fixed author field in .gemspec
+
+## [0.1.0] - 2011-10-07
+
+### Added
+
+- `require` and `extend` to mix in to your class/module to get a single point of logging
+- Switch on/off logging
+- Use whatever Logger you want
+
+<!-- 0.4.1 is intentionally unlinked: it was never tagged or released to rubygems. -->
+
+[unreleased]: https://github.com/turboladen/log_switch/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/turboladen/log_switch/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/turboladen/log_switch/compare/v0.4.0...v1.0.0
+[0.4.0]: https://github.com/turboladen/log_switch/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/turboladen/log_switch/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/turboladen/log_switch/compare/v0.1.4...v0.2.0
+[0.1.4]: https://github.com/turboladen/log_switch/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/turboladen/log_switch/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/turboladen/log_switch/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/turboladen/log_switch/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/turboladen/log_switch/releases/tag/v0.1.0

data/Gemfile

@@ -1,3 +1,4 @@
-source :rubygems
-gemspec
+# frozen_string_literal: true
 
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/README.md

@@ -0,0 +1,142 @@
+# log_switch
+
+<https://github.com/turboladen/log_switch>
+
+## Description
+
+While developing other gems that needed a single class/singleton style logger, I got tired of
+repeating the code to create that logger and mix it in to my base class. I just wanted to require
+something, mix it in, and log:
+
+```ruby
+MyThing.new.log "some message"
+```
+
+...and be able to switch that logging off programmatically:
+
+```ruby
+MyThing.logging_enabled = false
+```
+
+This gem does that.
+
+## Synopsis
+
+### Basic use
+
+`include LogSwitch` to give your class a class-level logger and an instance-level `#log` method.
+**Logging is off by default** — turn it on explicitly:
+
+```ruby
+require 'log_switch'
+
+class MyThing
+  include LogSwitch
+end
+
+MyThing.logging_enabled = true
+MyThing.new.log "I like you, Ruby."
+# => D, [2026-07-15T12:46:30.206465 #66434] DEBUG -- : <MyThing> I like you, Ruby.
+```
+
+Switch it back off and calls become no-ops:
+
+```ruby
+MyThing.logging_enabled = false
+MyThing.new.log "You're my favorite."   # => nothing is written
+
+MyThing.logging_enabled = true          # ...and back on, for the examples below
+```
+
+Note the class name is prepended to each message. That is on by default.
+
+### Log levels
+
+The default level is `:debug`. Change it with `default_log_level`:
+
+```ruby
+MyThing.default_log_level = :warn
+MyThing.new.log "Crap!"
+# => W, [2026-07-15T12:46:30.206563 #66434]  WARN -- : <MyThing> Crap!
+```
+
+Or pass a level per call:
+
+```ruby
+MyThing.new.log "Stuff!", :info
+# => I, [2026-07-15T12:46:30.206499 #66434]  INFO -- : <MyThing> Stuff!
+```
+
+The level is passed straight through to your Logger, so any method it responds to will do.
+
+### Using your own Logger
+
+`LogSwitch` defaults to a `Logger` writing to `STDOUT`. Point it anywhere:
+
+```ruby
+MyThing.logger = Logger.new('log.txt')
+MyThing.new.log "hi!"
+```
+
+`LogSwitch.logger` sets the default for includers that have not set their own, and
+`LogSwitch.reset_config!` puts things back to a fresh `STDOUT` logger.
+
+### Multi-line messages
+
+Anything responding to `#each_line` is logged one line per call, so a multi-line message stays
+readable:
+
+```ruby
+MyThing.new.log "line one\nline two"
+# => D, [...] DEBUG -- : <MyThing> line one
+# => D, [...] DEBUG -- : <MyThing> line two
+```
+
+Objects that do not respond to `#each_line` (an Array, an Exception) are logged whole.
+
+### Hooks
+
+Pass a block to `#log` and it runs before the message is written — handy for one-off setup:
+
+```ruby
+require 'fileutils'
+log_directory = File.expand_path('log')
+
+MyThing.new.log("Thanks brah!") do
+  FileUtils.mkdir_p(log_directory)
+end
+```
+
+For something that should run before _every_ call, use `before_log`:
+
+```ruby
+MyThing.before_log = proc { FileUtils.mkdir_p(log_directory) }
+MyThing.new.log "Thanks brah!"    # runs the hook, then logs
+MyThing.new.log "I'm hungry..."   # runs it again
+```
+
+## Requirements
+
+- Ruby >= 3.3. Tested on 3.3, 3.4 and 4.0 (see `.github/workflows/ci.yml`).
+- Runtime dependency: `logger` (no longer a default gem as of Ruby 4.0).
+
+## Install
+
+```sh
+gem install log_switch
+```
+
+## Developers
+
+After checking out the source:
+
+```sh
+bundle install
+bundle exec rake      # specs + RuboCop
+```
+
+## Thanks
+
+I need to thank the [savon](https://github.com/savonrb/savon) project for most of the code here.
+Somehow I ran across how they do logging and started following suit. The code in `log_switch` is
+almost identical to Savon's logging.

data/Rakefile

@@ -1,29 +1,42 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'yard'
+require 'rubocop/rake_task'
 
 YARD::Rake::YardocTask.new do |t|
-  t.files = %w(lib/**/*.rb - History.rdoc)
-  t.options = %W(--title log_switch Documentation (#{LogSwitch::VERSION}))
-  t.options += %w(--main README.rdoc)
+  t.files = %w[lib/**/*.rb - CHANGELOG.md]
+  t.options = %W[--title log_switch Documentation (#{LogSwitch::VERSION})]
+  t.options += %w[--main README.md]
 end
 
 RSpec::Core::RakeTask.new do |t|
-  t.ruby_opts = %w(-w)
+  t.ruby_opts = %w[-w]
 end
 
-if defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && RUBY_VERSION > "1.9"
-  require 'tailor/rake_task'
+RuboCop::RakeTask.new
+
+# RuboCop covers Ruby; dprint covers the Markdown and YAML. It is a binary
+# rather than a gem, so `bundle install` cannot supply it -- fail loudly with
+# somewhere to go rather than skipping, which would make the gate a no-op
+# exactly when nobody notices.
+desc 'Check non-Ruby formatting with dprint'
+task :dprint do
+  abort <<~MSG unless system('command -v dprint > /dev/null 2>&1')
+    dprint is not installed, so Markdown/YAML formatting was not checked.
+    Install it (https://dprint.dev/install/) -- e.g. `brew install dprint` --
+    or run `rake spec rubocop` to skip this deliberately.
+  MSG
 
-  Tailor::RakeTask.new do |task|
-    task.file_set 'lib/**/*.rb'
-    task.file_set 'spec/**/*.rb', :specs
-  end
+  sh 'dprint check'
+end
 
-# Alias for rubygems-test
-  task :test => [:spec, :tailor]
-else
-  task :test => :spec
+desc 'Format non-Ruby files with dprint'
+task 'dprint:fmt' do
+  sh 'dprint fmt'
 end
 
-task :default => :test
+task test: %i[spec rubocop dprint]
+
+task default: :test

data/lib/log_switch/version.rb

@@ -1,3 +1,3 @@
 module LogSwitch
-  VERSION = '0.4.0'
+  VERSION = '1.1.0'
 end

data/lib/log_switch.rb

@@ -1,93 +1,156 @@
-require "logger"
-require File.expand_path(File.dirname(__FILE__) + '/log_switch/version')
-require File.expand_path(File.dirname(__FILE__) + '/log_switch/mixin')
+require 'logger'
+require_relative 'log_switch/version'
 
-# LogSwitch allows for extending a class/module with a logger and, most
-# importantly, allows for turning off logging programmatically.  See the
-# +README.rdoc+ for more info.
+# LogSwitch mixes a logger into a class/module and, most importantly, allows for
+# turning off logging programmatically.  See README.md for more info.
 module LogSwitch
+  def self.included(base)
+    @includers ||= []
+    @includers << base
+    base.extend ClassMethods
+    base.send(:include, InstanceMethods)
 
-  # Saves the name of the class that extended itself with this module.  Used
-  # by {LogSwitch::Mixin} to know which class to include itself to.
-  def self.extend_object(base)
-    @extender = base
-    super(base)
+    base.class_eval do
+      def self.included(b)
+        b.extend ClassMethods
+        b.send :include, InstanceMethods
+      end
+    end
   end
 
-  # Simply returns the name of the class that extended itself with this module.
-  # It's set by {.extend_object}.
-  #
-  # @return [Class] The class that extended itself with LogSwitch.
-  def self.extender
-    @extender
+  # Defaults to a +Logger+ writing to STDOUT.
+  def self.logger
+    @logger ||= ::Logger.new STDOUT
   end
 
-  # Use to turn logging on or off.
-  attr_writer :log
+  def self.logger=(new_logger)
+    @logger = new_logger
+  end
 
-  # Set this to the Logger you want to use.
-  attr_writer :logger
+  # Sets back to defaults.
+  def self.reset_config!
+    self.logger = ::Logger.new STDOUT
 
-  # Set the log level so you don't have to pass it in on your call.
-  attr_writer :log_level
+    @includers.each do |klass|
+      klass.logging_enabled = false
+      klass.log_class_name = true
+    end
+  end
 
-  # Toggle prepending the class name of the #log caller to the log message.
-  attr_writer :log_class_name
+  module ClassMethods
+    # TODO: broken -- the class variables below are declared in this module body,
+    #   so they live on ClassMethods itself and every includer shares one slot:
+    #   `A.logging_enabled = true` also enables B.  Intent is per-includer config.
 
-  # Tells whether logging is turned on or not.
-  def log?
-    @log != false
-  end
+    # @param value [Boolean]
+    def logging_enabled
+      @@logging_enabled ||= false
+    end
 
-  # Defaults to a +Logger+ writing to STDOUT.
-  def logger
-    @logger ||= ::Logger.new STDOUT
-  end
+    # Tells whether logging is turned on or not.
+    #
+    # @param value [Boolean]
+    def logging_enabled?
+      !!logging_enabled
+    end
 
-  # @return [Symbol] The current default log level.  Starts off as :debug.
-  def log_level
-    @log_level ||= :debug
-  end
+    # Use to turn logging on or off.
+    #
+    # @param value [Boolean]
+    def logging_enabled=(value)
+      @@logging_enabled = value
+    end
 
-  # @return [Boolean] Tells whether logging of the class name with the log
-  #   message is turned on.
-  def log_class_name?
-    @log_class_name == true
-  end
+    # @return [Symbol] The current default log level.  Starts off as :debug.
+    def default_log_level
+      @@default_log_level ||= :debug
+    end
+
+    # @param level [Symbol]
+    def default_log_level=(level)
+      @@default_log_level = level
+    end
+
+    # @return [Boolean] Tells whether logging of the class name with the log
+    #   message is turned on.
+    def log_class_name?
+      log_class_name
+    end
 
-  # {#log} calls the block given to this method before it logs every time.
-  # This, thus, acts as a hook in the case where you want to make sure some
-  # code gets executed before you log a message.  Useful for making sure a file
-  # exists before logging to it.
-  #
-  # @param [Proc] block The block of code to execute before logging a message
-  #   with {#log}.
-  def before(&block)
-    @before_block ||= block
+    # TODO: broken -- `||=` against a truthy default overwrites a stored `false`
+    #   on the next read, so `log_class_name = false` never sticks.
+    def log_class_name
+      @@log_class_name ||= true
+    end
+
+    # Toggle prepending the class name of the #log caller to the log message.
+    def log_class_name=(value)
+      @@log_class_name = value
+    end
+
+    def logger
+      @@logger ||= LogSwitch.logger
+    end
+
+    def logger=(new_logger)
+      @@logger = new_logger
+    end
+
+    # {#log} calls the block given to this method before it logs every time.
+    # This, thus, acts as a hook in the case where you want to make sure some
+    # code gets executed before you log a message.  Useful for making sure a file
+    # exists before logging to it.
+    #
+    # @param [Proc] block The block of code to execute before logging a message
+    #   with {#log}.
+    # TODO: broken -- `||=` keeps only the first assignment, and #before_log
+    #   initialises the slot on first read, so later hooks are silently ignored.
+    def before_log=(block)
+      @@before_block ||= block
+    end
+
+    def before_log
+      @@before_block ||= Proc.new do; end
+    end
   end
 
-  # Logs a message using the level provided.  If no level provided, use
-  # +@log_level+.
-  #
-  # @param [String] message The message to log.
-  # @param [Symbol] level The log level to send to your Logger.
-  def log(message, level=log_level)
-    before.call unless before.nil?
-    yield if block_given?
-
-    if log?
-      if message.respond_to? :each_line
-        message.each_line { |line| logger.send level, line.chomp }
-      else
-        logger.send(level, message)
+  module InstanceMethods
+    def logger
+      self.class.logger
+    end
+
+    # Logs a message using the level provided.  If no level provided, use
+    # +@log_level+.
+    #
+    # @param [String] message The message to log.
+    # @param [Symbol] level The log level to send to your Logger.
+    def log(message, level=nil)
+      level ||= self.class.default_log_level
+
+      self.class.before_log.call
+      yield if block_given?
+
+      if self.class.logging_enabled?
+        if message.respond_to? :each_line
+          message.each_line do |line|
+            msg = filter_class_name(line.chomp)
+            logger.send(level, msg)
+          end
+        else
+          message = filter_class_name(message)
+          logger.send(level, message)
+        end
       end
     end
-  end
 
-  # Sets back to defaults.
-  def reset_config!
-    self.log = true
-    self.logger = ::Logger.new STDOUT
-    self.log_class_name = false
+    private
+
+    def filter_class_name(message)
+      if self.class.log_class_name?
+        "<#{self.class.name}> #{message}"
+      else
+        message
+      end
+    end
   end
 end