jellog 1.0.11

data/Bugs.rdoc

@@ -0,0 +1,5 @@
+== Bugs and Change Requests for Jellog
+
+[jellog-1.0.10 21-Sep-2012]
+
+  No outstanding bugs

data/Gemfile

@@ -0,0 +1,9 @@
+# @markup ruby
+# enable color output to terminals
+gem 'term-ansicolor'
+
+# a little thor for a simple command
+gem 'thor'
+
+# config file control
+gem 'jeckyl'

data/History.txt

@@ -0,0 +1,59 @@
+== History
+
+[jellog-1.0.11 21-Sep-2012]
+
+  Renamed because jelly was already in use in Gem-space.
+
+[jelly-1.0.10 21-Sep-2012]
+
+  Tidy up documentation and tests ready for pushing to RubyGems.
+
+[jelly-1.0.9 25-Jul-2012]
+
+  Set a default format string when none is provided
+
+[jelly-1.0.8 25-Jul-2012]
+
+  Fix a couple of small errors in config
+
+[jelly-1.0.7 23-Jul-2012]
+
+  Include config class for services etc that use Jelly
+
+[jelly-1.0.6 12-Jun-2012]
+
+  Added mark method to highlight a new section in the log
+
+[jelly-1.0.5 21-Jan-2012]
+
+Tidy up README and correct rspec tests
+
+jelly-1.0.4 10-Jan-2012
+
+Change get_options to make deletion an option and not delete keys by default
+
+jelly-1.0.3 09-Sep-2011
+
+Change option names to comply with existing configure files.
+
+jelly-1.0.2 09-Sep-2011
+
+Fix close, which had not been updated to the new structure.
+
+jelly-1.0.1 07-Sep-2011
+
+Add get_opts class method to help pick out log-related options
+
+jelly-1.0.0 06-Sep-2011
+
+Introduce independent formatting and colour by option.
+Tidy up logging options (making this incompatible with previous versions).
+Make jelly into a local gem.
+
+jelly-0.0.10 28-Aug-2011
+
+Return message from error level calls to assist in keeping callers DRY
+
+jelly-0.0.0 29-May-2011
+
+Application generated.

data/Intro.txt

@@ -0,0 +1,4 @@
+A wrapper class around the standard Ruby logger that adds a simply logging level control
+and the ability to log certain messages to syslog. It also adds a puts method so that the
+logger can be used instead of stdout etc. Output can be coloured depending on the logging
+level.

data/LICENCE.rdoc

@@ -0,0 +1,159 @@
+Copyright (c) 2011 Robert Sharp
+
+This software is licensed for use under the Open Software Licence v. 3.0
+The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+and below. Under the terms of this licence, all derivative works
+must themselves be licensed under the Open Software Licence v. 3.0
+
+Open Source Initiative OSI - The Open Software Licence 3.0:Licensing
+[OSI Approved Licence]
+Open Software Licence ("OSL") v. 3.0
+
+This Open Software Licence (the "Licence") applies to any original work of authorship
+(the "Original Work") whose owner (the "Licensor") has placed the following licensing
+notice adjacent to the copyright notice for the Original Work:
+
+Licensed under the Open Software Licence version 3.0
+
+1) Grant of Copyright Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, for the duration of the copyright, to do the following:
+
+a) to reproduce the Original Work in copies, either alone or as part of a collective work;
+
+b) to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby
+creating derivative works ("Derivative Works") based upon the Original Work;
+
+c) to distribute or communicate copies of the Original Work and Derivative Works to
+the public, with the proviso that copies of Original Work or Derivative Works that
+You distribute or communicate shall be licensed under this Open Software Licence;
+
+d) to perform the Original Work publicly; and
+
+e) to display the Original Work publicly.
+
+2) Grant of Patent Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, under patent claims owned or controlled by the Licensor that are
+embodied in the Original Work as furnished by the Licensor, for the duration of the
+patents, to make, use, sell, offer for sale, have made, and import the Original Work
+and Derivative Works.
+
+3) Grant of Source Code Licence. The term "Source Code" means the preferred form of
+the Original Work for making modifications to it and all available documentation
+describing how to modify the Original Work. Licensor agrees to provide a machine-readable
+copy of the Source Code of the Original Work along with each copy of the Original Work
+that Licensor distributes. Licensor reserves the right to satisfy this obligation by
+placing a machine-readable copy of the Source Code in an information repository reasonably
+calculated to permit inexpensive and convenient access by You for as long as Licensor
+continues to distribute the Original Work.
+
+4) Exclusions From Licence Grant. Neither the names of Licensor, nor the names of
+any contributors to the Original Work, nor any of their trademarks or service marks,
+may be used to endorse or promote products derived from this Original Work without
+express prior permission of the Licensor. Except as expressly stated herein, nothing
+in this Licence grants any license to Licensor's trademarks, copyrights, patents,
+trade secrets or any other intellectual property. No patent license is granted to
+make, use, sell, offer for sale, have made, or import embodiments of any patent claims
+other than the licensed claims defined in Section 2. No license is granted to the
+trademarks of Licensor even if such marks are included in the Original Work. Nothing
+in this Licence shall be interpreted to prohibit Licensor from licensing under terms
+different from this Licence any Original Work that Licensor otherwise would have a
+right to license.
+
+5) External Deployment. The term "External Deployment" means the use, distribution,
+or communication of the Original Work or Derivative Works in any way such that the
+Original Work or Derivative Works may be used by anyone other than You, whether those
+works are distributed or communicated to those persons or made available as an application
+intended for use over a network. As an express condition for the grants of license hereunder,
+You must treat any External Deployment by You of the Original Work or a Derivative Work
+as a distribution under section 1(c).
+
+6) Attribution Rights. You must retain, in the Source Code of any Derivative Works
+that You create, all copyright, patent, or trademark notices from the Source Code of
+the Original Work, as well as any notices of licensing and any descriptive text identified
+therein as an "Attribution Notice." You must cause the Source Code for any Derivative Works
+that You create to carry a prominent Attribution Notice reasonably calculated to inform
+recipients that You have modified the Original Work.
+
+7) Warranty of Provenance and Disclaimer of Warranty. Licensor warrants that the copyright
+in and to the Original Work and the patent rights granted herein by Licensor are owned by
+the Licensor or are sublicensed to You under the terms of this Licence with the permission
+of the contributor(s) of those copyrights and patent rights. Except as expressly stated in
+the immediately preceding sentence, the Original Work is provided under this Licence on an
+"AS IS" BASIS and WITHOUT WARRANTY, either express or implied, including, without limitation,
+the warranties of non-infringement, merchantability or fitness for a particular purpose.
+THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY
+constitutes an essential part of this Licence. No license to the Original Work is granted
+by this Licence except under this disclaimer.
+
+8) Limitation of Liability. Under no circumstances and under no legal theory, whether
+in tort (including negligence), contract, or otherwise, shall the Licensor be liable
+to anyone for any indirect, special, incidental, or consequential damages of any character
+arising as a result of this Licence or the use of the Original Work including, without
+limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction,
+or any and all other commercial damages or losses. This limitation of liability shall not
+apply to the extent applicable law prohibits such limitation.
+
+9) Acceptance and Termination. If, at any time, You expressly assented to this Licence,
+that assent indicates your clear and irrevocable acceptance of this Licence and all of its
+terms and conditions. If You distribute or communicate copies of the Original Work or a
+Derivative Work, You must make a reasonable effort under the circumstances to obtain the
+express assent of recipients to the terms of this Licence. This Licence conditions your
+rights to undertake the activities listed in Section 1, including your right to create
+Derivative Works based upon the Original Work, and doing so without honoring these
+terms and conditions is prohibited by copyright law and international treaty. Nothing
+in this Licence is intended to affect copyright exceptions and limitations (including
+"fair use" or "fair dealing"). This Licence shall terminate immediately and You may no
+longer exercise any of the rights granted to You by this Licence upon your failure to
+honor the conditions in Section 1(c).
+
+10) Termination for Patent Action. This Licence shall terminate automatically and
+You may no longer exercise any of the rights granted to You by this Licence as of
+the date You commence an action, including a cross-claim or counterclaim, against
+Licensor or any licensee alleging that the Original Work infringes a patent. This
+termination provision shall not apply for an action alleging patent infringement
+by combinations of the Original Work with other software or hardware.
+
+11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this Licence
+may be brought only in the courts of a jurisdiction wherein the Licensor resides or
+in which Licensor conducts its primary business, and under the laws of that jurisdiction
+excluding its conflict-of-law provisions. The application of the United Nations Convention
+on Contracts for the International Sale of Goods is expressly excluded. Any use of
+the Original Work outside the scope of this Licence or after its termination shall be
+subject to the requirements and penalties of copyright or patent law in the appropriate
+jurisdiction. This section shall survive the termination of this Licence.
+
+12) Attorneys' Fees. In any action to enforce the terms of this Licence or seeking
+damages relating thereto, the prevailing party shall be entitled to recover its costs
+and expenses, including, without limitation, reasonable attorneys' fees and costs
+incurred in connection with such action, including any appeal of such action. This
+section shall survive the termination of this Licence.
+
+13) Miscellaneous. If any provision of this Licence is held to be unenforceable,
+such provision shall be reformed only to the extent necessary to make it enforceable.
+
+14) Definition of "You" in This Licence. "You" throughout this Licence, whether in
+upper or lower case, means an individual or a legal entity exercising rights under,
+and complying with all of the terms of, this Licence. For legal entities, "You" includes
+any entity that controls, is controlled by, or is under common control with you. For
+purposes of this definition, "control" means (i) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or otherwise, or (ii)
+ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+ownership of such entity.
+
+15) Right to Use. You may use the Original Work in all ways not otherwise restricted or
+conditioned by this Licence or by law, and Licensor promises not to interfere with or be
+responsible for such uses by You.
+
+16) Modification of This Licence. This Licence is Copyright © 2005 Lawrence Rosen.
+Permission is granted to copy, distribute, or communicate this Licence without modification.
+Nothing in this Licence permits You to modify this Licence as applied to the Original Work
+or to Derivative Works. However, You may modify the text of this Licence and copy, distribute
+or communicate your modified version (the "Modified Licence") and apply it to other original
+works of authorship subject to the following conditions: (i) You may not indicate in any way
+that your Modified Licence is the "Open Software Licence" or "OSL" and you may not use those
+names in the name of your Modified Licence; (ii) You must replace the notice specified in the
+first paragraph above with the notice "Licensed under <insert your license name here>" or
+with a notice of your own that is not confusingly similar to the notice in this Licence;
+and (iii) You may not claim that your original works are open source software unless your
+Modified Licence has been approved by Open Source Initiative (OSI) and You comply with
+its license review and certification process.

data/README.md

@@ -0,0 +1,146 @@
+# JELLY
+
+### (a.k.a. Jumpin Ermin's Loquatious Logger)
+
+Based on the standard ruby logger, Jellog provides a slightly simplified interface and
+adds a few features that may be useful:
+
+* the ability to log to syslog for certain messages, which can be disabled during 
+  setup;
+* formats its own timestamp to avoid other software from interferring under the bonnet;
+* colourises logs;
+* provides a 'puts' method to enable apps to output to either console or log (e.g foreground
+  vs background);
+* returns logged messages, e.g. to cascade into exceptions
+* simple log level control.
+
+## Installation
+
+Distributed as a gem:
+
+    gem install jellog
+  
+Jellog comes with a single command: jellog, that provides access to the README file in the gem.
+
+Jellog can also be downloaded from [GitHub](https://github.com/osburn-sharp/jellog).
+
+## Getting Started
+
+A simple example:
+
+    require 'jellog'
+    @logger = Jellog::Logger.new(name, params)
+    begin
+      @logger.system("This is a system message and will be logged to syslog")
+      @logger.info("Just logged to local log")
+      @logger.warn("As above")
+      @logger.mark
+      @logger.error("As above")
+      @logger.fatal("Logged to syslog and prefixed with 'Jellog Alert:'")
+      @logger.verbose("Logged locally if log_level = :verbose or :debug")
+      @logger.debug("Logged locally if log_level = :debug")
+      # when things go wrong
+    rescue => err
+      @logger.exception(err) # logs the entire backtrace in colour
+    ensure
+      @logger.close
+    end
+
+This creates a jellog logger and logs a variety of messages before closing it. The parameters required 
+are defined in {Jellog::Config}, which is a subclass of Jeckyl::Config, (see [Jeckyl on GitHub](https://github.com/osburn-sharp/jeckyl) 
+for more details):
+
+    require 'jellog/config'
+    options = Jellog::Config.new('path/to/config.rb')
+    @logger = Jellog::Logger.new('MyLogger', options)
+
+Check out {Jellog::Config} for details about the logging parameters available for Jellog.
+
+In addition to these conventional uses, Jellog provides the following to tailor the log:
+
+    logger = Jellog::Logger.new(name, options)
+    logger.colours = colour_hash
+    logger.log_level = :debug
+
+The colour_hash is a hash of :method => :colour (e.g. :fatal=>:blue) where colours are as defined
+in term_ansicolor. There are three log levels:
+
+* :system - basic logging required for normal applications
+* :verbose - additional logging that should help trouble-shooting during roll-out etc
+* :debug - lots of logging for development and testing purposes
+
+The {Jellog::Logger#warn warning}, {Jellog::Logger#error error} and {Jellog::Logger#fatal fatal} logging methods all return the message as
+a string to make it convenient to cascade logging with exception raising:
+
+    raise MyError, @logger.error("You did something stupid")
+    
+The {Jellog::Logger#mark mark} method simply puts a mark in the log, which can be set by one of the options. 
+
+There is also a {Jellog::Logger#puts puts} method that allows you to arrange output either to a standard out/error/file or a log
+if required. This allows parts of your code to be agnostic about where messages go, e.g. in cases where you may or may not
+daemonize a task.
+
+When using the logger as part of a service (or any other application), it may be useful to extract the parameters that are specific
+to the logger only. Check out the Jeckyl class method #intersection to get these options:
+
+    log_opts = Jellog::Config.intersection(full_opts)
+    nonlog_opts = full_opts.complement(log_opts)
+    
+More details of Jeckyl can be found on [GitHub](https://github.com/osburn-sharp/jeckyl).
+    
+## Code Walkthrough
+
+The {Jellog::Logger} presents a public interface with a range of logging methods and fairly simple customising options. It does
+not do any logging itself, but creates an instance of {Jellog::Slogger} that is a simple wrapper around the standard ruby logger
+but uses its own timestamps to defeat any other part of an application from fiddling with these settings: the standard logger
+time stamp format is defined in a global variable and other users can change it with impunity.
+
+This all seems a little complicated and I suspect it may be historical, the ruby logger being wrapped in Slogger to avoid
+naming conflicts with Jellog::logger. The little bit of meta-magic used in Slogger, however, makes controlling attributes such
+as colour and timestamps relatively compact while preserving an easy-to-read, non-magical user interface.
+
+## Dependencies
+
+See {file:Gemfile} for gem dependencies.
+
+## Documentation
+
+You can read this README file with 'jellog readme', but then as you are reading it you may already know this.
+
+Use YARD to read the full documentation, which is available online at [RubyDoc.info](http://rdoc.info/github/osburn-sharp/jellog/frames)
+
+## Testing/Modifying
+
+Download Jellog from [GitHub](https://github.com/osburn-sharp/jellog) for testing. There is an rspec test that covers most of the functionality:
+
+    rspec spec/jellog_spec.rb # tests the main functions
+    rspec spec/jellog_logger_spec.rb # tests colours (manually) and support
+    rspec spec/slogger_spec.rb # manual check of underlying logger
+    
+The last two tests don't really use rspec but generate logs in ./test and ./log which can be checked manually.
+
+## Bugs and Issues
+
+Details of any unresolved bugs are in {file:Bugs.rdoc}.
+Issues and change requests can be posted through [GitHub](https://github.com/osburn-sharp/jellog/issues).
+
+## Changelog
+
+This can be found in the {file:History.txt} file. This file is used by Jevoom to manage the
+version info and create git commits.
+
+## Author and Contact
+
+I am Robert Sharp and you can contact me on [GitHub](http://github.com/osburn-sharp)
+
+## Copyright and Licence
+
+Copyright (c) 2011-2012 Robert Sharp. 
+
+See {file:LICENCE.rdoc LICENCE} for details of the licence under which Jeckyl is released.
+
+## Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.

data/bin/jellog

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby18
+#
+# Description
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2010 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+#
+# replace this to point to your config class
+# require 'my_jeckyl_configurator'
+require 'rubygems' # delves into gem spec to find readme
+require 'thor'
+require 'colored'
+
+class JellogCLI < Thor
+  
+  default_task :usage
+  
+  desc "usage", "You are looking at it"
+  def usage
+    puts "Assistance with Jellog."
+    puts ""
+    help
+    puts ""
+    puts "See Also:"
+    puts "  README.md: (see jelloga readme above)"
+    puts "  GitHub: https://github.com/osburn-sharp/jellog"
+    puts "  RubyDoc: http://rdoc.info/github/osburn-sharp/jellog/frames"
+  end
+  
+  desc "readme", "display the readme file for the gem"
+  def readme
+    gem_spec = Gem::Specification.find_by_name('jellog')
+    readme_path = File.join(gem_spec.gem_dir, 'README.md')
+    unless FileTest.exists?(readme_path)
+      puts "Cannot find a readme file to show you. Try GitHub?".red
+      invoke :usage
+      return 0
+    end
+    File.open(readme_path) do |rfile|
+      rfile.each_line do |rline|
+        puts rline
+      end
+    end
+    
+  rescue Gem::LoadError
+    
+    puts "Cannot find the gem for jellog, try GitHub for the README file.".red
+    invoke :usage
+
+  end
+  
+end
+
+JellogCLI.start