logg 0.1.5 → 0.1.6

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2010 YOURNAME
+Copyright 2010 Jean-Denis Vauguet
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -22,9 +22,34 @@ 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.
+You may also just instantiate a Logg dispatcher. This is less intrusive, no
+mixin involved, allow for changing the dispatcher's name and have several
+loggers lurking around:
 
-Many other use cases are available under the `examples/` directory, based on the Cucumber `features/`. This README explains some of them.
+``` ruby
+report = Logg::Dispatcher.new
+report.failure 'danger' # => "2011-07-02 20:27:01 +0200 | [failure] danger"
+```
+
+``` ruby
+class Foo
+  attr_reader :report
+
+  def initialize
+    @report = Logg::Dispatcher.new
+  end
+
+  def bar
+    report.something 'important'
+  end
+end
+Foo.new.bar # => "2011-07-02 20:27:01 +0200 | [something] important"
+```
+
+This illustrates the basic use cases. The default logging format is a string
+sent to `$stdout`, formatted as `time | [namespace] message` where "namespace" is the method called on the logger.
+
+But this is only the default implementation of the message dispatcher. Many other examples are available under the `examples/` directory (based on the Cucumber `features/`). The next part of this README explains some of those use-cases.
 
 ## Custom loggers
 
@@ -53,7 +78,12 @@ Note: if you would like to define a custom logger under the name `#as`, the help
 
 ## 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.
+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](https://github.com/rtomayko/tilt)
+to help you format your data. [Tilt](https://github.com/rtomayko/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`).
 
@@ -79,20 +109,58 @@ class Foo
 
   # 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 |response|
-    output = render('tpl/foo.haml', :data => response)
+  # note we expect two parameters for this logger
+  log.as(:http_response) do |response, params|
+    output = render('tpl/foo.haml', :data => response, :locals => { :params => params})
     # do something with output, for instance, send a mail notification when not a 200
   end
-  log.http_response(resp) # performs the block, really
+  log.http_response(resp, request.params) # performs the block, really
 end
 ```
 
 If you want to render to several logging endpoints, and send a mail on top of that, just do it within the block!
 
+Both `#render_inline` and `#render` follow [Tilt](https://github.com/rtomayko/tilt)'s implementation. The `:data`
+object is any Ruby object which be promoted as `self` when rendering the
+template. In the last example, if `foo.haml` where to contain calls to
+methods such as `status` or `body`, this would mean running `response.status`
+and `response.body` within the template. The `:locals` are additional
+variables one may need to interpolate the template. In the last example, we
+are passing the request parameters along the response object. You basically
+define your loggers the way you want (see `Advice` section below for some
+insight).
+
 ## Dispatching helpers
 
 TODO: provide helpers for message dispatching/logging, levels managment and the like.
 
-## About the logger implementation
+## About the 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, by instantiating a new `Logg::Dispatcher` as illustrated in the Synopsis section above.
+
+## Advice
+
+When using MRI 1.9.2 or equivalent implementations, you can now define closure with dynamic params:
+
+``` ruby
+log.as(:report) do |name = 'toto', *args|
+  puts name
+  puts args
+end
+
+log.report # => toto
+           #    []
+log.report('joe') # => joe
+                  #    []
+log.report('joe', {:foo => :bar}, 1) # => joe
+                                     #    [{:foo => :bar}, 1]
+```
+
+It also support blocks as closure parameters ([more details](http://www.igvita.com/2011/02/03/new-ruby-19-features-tips-tricks/)). All of this allows for building super-dynamic custom loggers.
+
+## License
 
-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.
+[MIT License](http://en.wikipedia.org/wiki/MIT_License). See the LICENSE file.

data/lib/logg/version.rb

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

metadata

@@ -2,7 +2,7 @@
 name: logg
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors: 
 - Jean-Denis Vauguet <jd@vauguet.fr>
@@ -10,10 +10,163 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-02 00:00:00 +02:00
+date: 2011-07-11 00:00:00 +02:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: tilt
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: better
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: aruba
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: metric_fu
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id009
+- !ruby/object:Gem::Dependency 
+  name: guard
+  prerelease: false
+  requirement: &id010 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id010
+- !ruby/object:Gem::Dependency 
+  name: guard-cucumber
+  prerelease: false
+  requirement: &id011 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id011
+- !ruby/object:Gem::Dependency 
+  name: guard-rspec
+  prerelease: false
+  requirement: &id012 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id012
+- !ruby/object:Gem::Dependency 
+  name: rb-inotify
+  prerelease: false
+  requirement: &id013 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id013
+- !ruby/object:Gem::Dependency 
+  name: libnotify
+  prerelease: false
+  requirement: &id014 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id014
 description: A simple message dispatcher (aka. logger) for your ruby applications.
 email: jd@vauguet.fr
 executables: []