logg 0.1.4

data/Guardfile

@@ -0,0 +1,21 @@
+# A sample Guardfile
+# More info at http://github.com/guard/guard#readme
+
+guard 'cucumber' do
+  watch('^features/(.*).feature')
+  watch('^features/support')                       { 'features' }
+  watch('^features/step_definitions')              { 'features' }
+end
+
+guard 'rspec', :version => 2 do
+  watch('^spec/(.*)_spec.rb')
+  watch('^lib/(.*)\.rb')                              { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('^spec/spec_helper.rb')                       { "spec" }
+  
+  # Rails example
+  watch('^app/(.*)\.rb')                              { |m| "spec/#{m[1]}_spec.rb" }
+  # watch('^lib/(.*)\.rb')                              { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('^config/routes.rb')                          { "spec/routing" }
+  watch('^app/controllers/application_controller.rb') { "spec/controllers" }
+  watch('^spec/factories.rb')                         { "spec/models" }
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2010 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,96 @@
+# Logg
+
+A simple message dispatcher (aka. logger) for your Ruby applications.
+
+## Install
+
+``` bash
+$ gem install logg
+```
+
+## Synopsis
+
+Logg is a library providing generic logging features. At the core of Logg is a module, `Logg::Machine`, which you may include (mixin) in a class, or extend within another module. This will inject the Logg helpers, so one can write something like this:
+
+``` ruby
+class Foo
+  include Logg::Machine
+end
+
+Foo.log.debug "test!"      # => Fri Dec 31 16:00:09 +0100 2010 | [debug] test!
+Foo.new.log.debug "test…"  # => Fri Dec 31 16:00:09 +0100 2010 | [debug] test…
+Foo.new.log.error "failed" # => Fri Dec 31 16:00:09 +0100 2010 | [error] failed
+```
+
+This illustrates the basic use case, with the default message format being: `time | [namespace] message` where namespace is the method called on the logger.
+
+Many other use cases are available under the `examples/` directory, based on the Cucumber `features/`. This README explains some of them.
+
+## Custom loggers
+
+Usually, logging engines provide you with a bunch of "log levels", such as FATAL, ERROR, WARNING, NOTICE. Logg does not enforce such a convention and rather let you define your own, if required, but does not enforce you to do so. More generally, one may create custom loggers using `Logg::Dispatcher#as`:
+
+``` ruby
+class Foo
+  include Logg::Machine
+
+  # let's define a custom logger
+  log.as(:failure) do |data|
+    # play with data and render/do something, somewhere: output a String,
+    # send an email, anything you want.
+  end
+
+  # then use it!
+  log.failure my_data
+end
+```
+
+`as` expects a mandatory block, which may take any number of arguments, of any kind. Within the block, it is expected you will "log" somehow, but actually you are free to perform anything. You may output a simple string on $stdout, call an external API through HTTP, send an email, or even render a template (see below): that's just legacy ruby code in here! All in all, Logg is just a mega-method-definition-machine, aimed at logging—but feel free to use it the way you like (dispatching events, for instance).
+
+Soon to come: the possibility to change `#log` for any other valid method name.
+
+Note: if you would like to define a custom logger under the name `#as`, the helper method is also available under the `#_as` alias.
+
+## Message formatting, templates
+
+Logging is all about building meaningful messages. You may also want to log to the tty, a file and send an email on top of that, and each one of those output channels would benefit from using a different data representation. One should thus be provided with efficient tools to define how a message is rendered in particular context. Logg makes use of Tilt to help you format your data. Tilt is a wrapper around several template engines (you may know about ERB or haml, but there are many others). Just tell Logg which format you want to use and go ahead! The dispatching logic is of your responsability.
+
+For more details, see `examples/` and read/run the Cucumber `features/` (command: `cucumber features`).
+
+``` ruby
+class Foo
+  include Logg::Machine
+
+  # let's use vanilla ruby code for the first example: output the
+  # message to $stdout using #puts
+  log.as(:foo) do
+    puts "something really important happened"
+  end
+
+  # you may also define a template within the block, render it and
+  # use the result.
+  # (Keep in mind that this kind of template with heavy code is considered bad practice ;))
+  log.as(:foo) do |data|
+    tpl = "Data: <%= self.map { |k,v| puts k.to_s + v.to_s } %>"
+    puts render_inline(tpl, :as => :erb, :data => data)
+  end
+  log.foo({:foo => :bar}) # => "Data: foobar"
+
+  # now we want to render an external HAML template, providing its path with
+  # or withouth the .haml extension (if not provided, the :as option is mandatory)
+  log.as(:http_response) do |resp|
+    output = render('tpl/foo', :as => :haml, :data => resp)
+    # do something with output
+  end
+end
+```
+
+If you want to render to several logging endpoints, and send a mail on top of that, just do it within the block!
+
+## Dispatching helpers
+
+TODO: provide helpers for message dispatching/logging, levels managment and the like.
+
+## About the logger implementation
+
+When a class mixins the `Logg::Machine` module, a `Logg::Dispatcher` instance is created and associated (if possible, see below) to the receiving class, through method injection. The custom loggers blocks are runned in the context of a `Logg::Dispatcher::Render` class, so be aware you must inject in the closure any data you would require. This is by design so as to keep the logger's logic separated from the application burden, enforcing explicit control over the data payloads. If this is just too much a burden for you, you may avoid mixin `Logg::Machine` and just make use of the `Render` core implementation.

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Logg'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/logg.rb

@@ -0,0 +1,4 @@
+require 'tilt'
+require 'pathname'
+require 'better/tempfile'
+require 'logg/core'

data/lib/logg/core.rb

@@ -0,0 +1,220 @@
+module Logg
+  # Set to true to puts output when using logger#debug default's method.
+  ALWAYS_PUTS = true
+
+  # A Dispatcher is a logger core implementation, providing logger's definition
+  # and output methods. It's not intented to be used directly but through the
+  # Er mixin, within a class.
+  #
+  class Dispatcher
+    class Render
+      # Render a template. Just a mere proxy for Tilt::Template#render method,
+      # the first argument being the filepath or file, and the latter,
+      # the usual arguments for Tilt's #render.
+      #
+      # @param [String, #path, #realpath] path filepath or an object behaving
+      #   like a legacy File
+      # @param [Object] obj context object the template will be rendered within
+      # @param [Hash] args rendering context
+      # @option [Symbol] :as syntax engine
+      # @option [Object] :data template's rendering contextual object
+      # @option [Hash]   :locals template's locals
+      # @return [String] the interpolated template
+      #
+      def render(path, *args)
+        args = args.first
+        path = detect_path(path)
+        tpl  = fetch_template(args, path)
+        tpl.render(args[:data], args[:locals])
+      end
+
+      def render_inline(content, *args)
+        args   = args.first
+        syntax = detect_syntax(args)
+        res    = Object
+
+        Better::Tempfile.open(['dummylogg', ".#{syntax}"]) do |f|
+          f.write(content)
+          f.rewind
+          res = Tilt.new(f.path).render(args[:data], args[:locals])
+        end
+        res
+      end
+
+      def detect_path(path)
+        if path.respond_to?(:path)
+          path.path
+        elsif path.respond_to?(:realpath)
+          path.to_s
+        elsif path.respond_to?(:to_s)
+          path.to_s
+        else
+          raise ArgumentError, 'Missing file or a filepath.'
+        end
+      end
+
+      def fetch_template(args, path)
+        if args[:as]
+          begin
+            test_path = Pathname.new(path)
+            raise ArgumentError, "Invalid filepath #{path}" unless test_path.file?
+          rescue
+            test_path = Pathname.new(path + ".#{args[:as].to_s.downcase}")
+            raise ArgumentError, "Invalid filepath #{path}" unless test_path.file?
+            path = test_path.to_s
+          end
+          Tilt.const_get("#{args[:as].to_s.downcase.capitalize}Template").new(path)
+        else
+          Tilt.new(path)
+        end
+      end
+
+      def detect_syntax(options)
+        unless options.has_key?(:as)
+          raise ArgumentError, 'Missing template syntax specified as the :as option.'
+        end
+        options[:as].to_s
+      end
+    end
+
+    attr_reader :message, :namespace
+
+    # The Dispatcher default behavior relies on #method_missing. It sets both the
+    # message and a namespace, then auto-sends the order to output.
+    #
+    def method_missing(meth, *args, &block)
+      @namespace = meth.to_s
+      @message   = (args.first.to_s == 'debug') ? nil : args.first.to_s
+      self.send :output!
+    end
+
+    def eigenclass
+      class << self; self; end
+    end
+
+    # Define a custom logger, using a template. The template may be defined
+    # within the block as a (multi-line) string, or one may reference a
+    # file.
+    #     # do whatever you want with data or anything else, for instance,
+    #     send mails, tweet, then…
+    #
+    # Inline templates (defined within the block) make use of #render_inline
+    # (indentation broken for the sake of example readibility):
+    #
+    #   logger.as(:custom) do |response|
+    #     tpl = <<-TPL
+    #       %h2 Query log report
+    #       %span
+    #         Statu:
+    #         = data.status
+    #       %span
+    #         Response:
+    #         = data.body
+    #       %br/
+    #     TPL
+    #     puts render_inline(tpl, :as => :haml, :data => response)
+    #   end
+    #
+    # With an external template, one should use the #render helper to, well,
+    # render the template file. The extension will be used to infer the proper
+    # rendering engine. If not provided or when a custom extension is used, one
+    # may declare the template syntax.
+    #
+    #   logger.as(:custom) do |data|
+    #     # do whatever you want with data or anything else, then…
+    #     out = render('my/template.erb', :data => data)
+    #     # one may then use out to send mails, log to file, tweet…
+    #   end
+    #
+    #   logger.as(:custom) do |data|
+    #     render('my/template', :as => :erb, :data => data)
+    #   end
+    #
+    # See #render and #render_inline for more details.
+    #
+    # TODO: memoize the Render instance somehow? Or find another trick to
+    # execute the block.
+    #
+    def as(method, &block)
+      raise ArgumentError, 'Missing mandatory block' unless block_given?
+
+      method  = method.to_sym
+
+      # Define the guard at class-level, if not already defined.
+      if !eigenclass.respond_to?(method)
+        eigenclass.send(:define_method, method) do |*args|
+          Render.new.instance_exec(*args, &block)
+        end
+      end
+
+      # Define the guard at instance-level by overriding #initialize, if not
+      # already defined.
+      eigenclass.send(:define_method, :new) do
+        o = super
+        if !o.respond_to?(method)
+          o.send(:define_method, method) do |*args|
+            Render.new.instance_exec(*args, &block)
+          end
+        end
+        o
+      end
+    end
+
+    private
+
+    # Default logging behavior. Outputs to $stdout using #puts and return
+    # the message.
+    #
+    def output!
+      output  = "#{Time.now} | "
+      output += "[#{@namespace.gsub('_', ' ')}] " unless @namespace.nil?
+      output += @message
+      puts output if defined?(Logg::ALWAYS_PUTS) && Logg::ALWAYS_PUTS
+      return output
+    end
+  end
+
+  # The Er module, when mixed-in a class, instantiates a Dispatcher and performs some
+  # simple meta-programming on this receiver to add support for the logger. It thus
+  # enable the receiver to use the logger's default implementation and/or define
+  # custom loggers.
+  #
+  module Machine
+    LOGGER = Logg::Dispatcher.new
+    #NAME = (defined?(::Logg::LOG_METHOD) && ::Logg::LOG_METHOD) || :log
+    NAME = :log
+
+    def self.included(base)
+      if !base.respond_to?(NAME)
+        base.instance_eval do
+          # Memoized logger for the receiver's class.
+          #
+          # TODO: add support for defining the logger under a different name than #log,
+          # this means either defining a constant before mixin, or delaying the metaprog.
+          class << self; self; end.instance_eval do
+            define_method(NAME) do
+              @@_logg_er ||= LOGGER
+            end
+          end
+        end
+      else
+        raise RuntimeError, "Cannot mixin Logg::Er as #{base}#logger, method's already defined."
+      end
+
+      # Memoized logger for the receiver.
+      base.extend RedefInit
+    end
+
+    module RedefInit
+      def new *args, &block
+        o = super
+        if !o.respond_to?(NAME)
+          class << o; self; end.send(:define_method, NAME) do
+            @_logg_er ||= LOGGER
+          end
+        end
+        o
+      end
+    end
+  end
+end

data/lib/logg/render.rb

@@ -0,0 +1,2 @@
+module Logg
+end

data/lib/logg/version.rb

@@ -0,0 +1,6 @@
+module Logg
+  MAJOR = 0
+  MINOR = 1
+  PATCH = 4
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: logg
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.4
+platform: ruby
+authors: 
+- Jean-Denis Vauguet <jdvauguet@af83.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-02 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: A simple logger for your ruby applications.
+email: jdvauguet@af83.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/logg/render.rb
+- lib/logg/version.rb
+- lib/logg/core.rb
+- lib/logg.rb
+- MIT-LICENSE
+- Rakefile
+- Guardfile
+- README.md
+has_rdoc: true
+homepage: http://www.github.com/af83/logg
+licenses: []
+
+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.6.1
+signing_key: 
+specification_version: 3
+summary: A simple logger.
+test_files: []
+