apachelogregex 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,5 @@
+= Changelog
+
+== Release 0.1.0
+
+* Initial public release based on Apache::LogRegex 1.4.

data/LICENSE.rdoc

@@ -0,0 +1,25 @@
+= License
+
+(The MIT License)
+
+Copyright (c) 2008-2009 Simone Carletti <weppos@weppos.net>
+
+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/Manifest

@@ -0,0 +1,12 @@
+CHANGELOG.rdoc
+lib/apache_log_regex/version.rb
+lib/apache_log_regex.rb
+lib/apachelogregex.rb
+LICENSE.rdoc
+Manifest
+Rakefile
+README.rdoc
+setup.rb
+test/apache_log_regex_test.rb
+test/test_all.rb
+test/test_helper.rb

data/README.rdoc

@@ -0,0 +1,97 @@
+= Apache Log Regex
+
+Apache Log Regex is a Ruby port of Peter Hickman's Apache::LogRegex 1.4 Perl module, 
+available at http://cpan.uwinnipeg.ca/~peterhi/Apache-LogRegex.
+It provides functionalities to parse a line from an Apache log file into a hash.
+
+
+== Dependencies
+
+* Ruby >= 1.8.6 (not tested with previous versions)
+
+ApacheLogRegex is compatible with Ruby 1.9.1.
+
+
+== Overview
+
+Apache Log Regex is designed to be a simple class to parse Apache log files. 
+
+It takes an Apache logging format and generates a regular expression which is used to parse a line from a log file and returns a Hash with keys corresponding to the fields defined in the log format.
+The log format should match the one defined in your Apache configuration file with the LogFormat directive.
+
+
+== Example Usage
+
+The following one is the most simple example usage. 
+It tries to parse the `access.log` file and echoes each parsed line.
+
+  format = '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
+  parser = ApacheLogRegex.new(format)
+  
+  File.foreach('/var/apache/access.log') do |line|
+    begin
+      parser.parse(line)
+      # {"%r"=>"GET /blog/index.xml HTTP/1.1", "%h"=>"87.18.183.252", ... }
+    rescue ApacheLogRegex::ParseError => e
+      puts "Error parsing log file: " + e.message
+    end
+  end
+
+More often, you might want to collect parsed lines and use them later in your program.
+The following example iterates all log lines, parses them and returns an array of Hash with the results.
+
+  format = '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
+  parser = ApacheLogRegex.new(format)
+
+  File.readlines('/var/apache/access.log').collect do |line|
+    begin
+      parser.parse(line)
+      # {"%r"=>"GET /blog/index.xml HTTP/1.1", "%h"=>"87.18.183.252", ... }
+    rescue ApacheLogRegex::ParseError => e
+      nil
+    end
+  end
+
+
+== Acknowledgments
+
+This library is essentially a Ruby port of Apache::LogRegex Perl library.
+A big thanks goes to Peter Hickman, the author of the original package. This Ruby GEM would probably not exists without your contribution!
+
+I also want to thank you Harry Fuecks and Hamish Morgan, 
+the authors of the Python[http://code.google.com/p/apachelog/] and PHP[http://kitty0.org/] ports.
+First of all they gave me the inspiration to translate the original Perl code to Ruby, 
+as soon as I discovered nobody did it before me.
+Last but not least, their library have been extremely useful to help me understand some obscure Perl statements
+from the original package.
+
+
+== Author
+
+{Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+
+
+== Resources
+
+* {Homepage}[http://code.simonecarletti.com/apachelogregex]
+* {API}[http://apachelogregex.rubyforge.org/]
+* {GitHub}[http://github.com/weppos/apachelogregex/]
+* {RubyForge}[http://rubyforge.org/projects/apachelogregex/]
+
+
+== FeedBack and Bug reports
+
+Feel free to email {Simone Carletti}[mailto:weppos@weppos.net] with any questions or feedback.
+
+Please use the {Ticket System}[http://code.simonecarletti.com/projects/show/apachelogregex] to submit bug reports or feature request.
+
+
+== Changelog
+
+See the CHANGELOG.rdoc file for details.
+
+
+== License
+
+Copyright (c) 2008-2009 Simone Carletti, ApacheLogRegex is released under the MIT license. 
+

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+gem     'echoe', '>= 3.1'
+require 'echoe'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
+require 'apache_log_regex'
+
+
+# Common package properties
+PKG_NAME    = ENV['PKG_NAME']    || ApacheLogRegex::GEM
+PKG_VERSION = ENV['PKG_VERSION'] || ApacheLogRegex::VERSION
+PKG_SUMMARY = "Ruby parser for Apache log files based on regular expressions."
+PKG_FILES   = FileList.new("{lib,test}/**/*.rb") do |files|
+  files.include %w(README.rdoc CHANGELOG.rdoc LICENSE.rdoc)
+  files.include %w(Rakefile setup.rb)
+end
+RUBYFORGE_PROJECT = 'apachelogregex'
+ 
+if ENV['SNAPSHOT'].to_i == 1
+  PKG_VERSION << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+ 
+ 
+Echoe.new(PKG_NAME, PKG_VERSION) do |p|
+  p.author        = "Simone Carletti"
+  p.email         = "weppos@weppos.net"
+  p.summary       = PKG_SUMMARY
+  p.description   = <<-EOF
+    Apache Log Regex is a Ruby port \ 
+    of Peter Hickman's Apache::LogRegex 1.4 Perl module. \
+    It provides functionalities to parse a line from an Apache log file into a hash.
+  EOF
+  p.url           = "http://code.simonecarletti.com/apachelogregex"
+  p.project       = RUBYFORGE_PROJECT
+
+  p.need_zip      = true
+  p.rcov_options  = ["--main << README.rdoc -x Rakefile -x rcov"]
+  p.rdoc_pattern  = /^(lib|CHANGELOG.rdoc|README.rdoc)/
+
+  p.development_dependencies += ["rake  >=0.8",
+                                 "echoe >=3.1"]
+end
+
+
+begin
+  require 'code_statistics'
+  desc "Show library's code statistics"
+  task :stats do
+    CodeStatistics.new(["ApacheLogRegex", "lib"],
+                       ["Tests", "test"]).to_s
+  end
+rescue LoadError
+  puts "CodeStatistics (Rails) is not available"
+end

data/apachelogregex.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{apachelogregex}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Simone Carletti"]
+  s.date = %q{2009-02-13}
+  s.description = %q{Apache Log Regex is a Ruby port   of Peter Hickman's Apache::LogRegex 1.4 Perl module.     It provides functionalities to parse a line from an Apache log file into a hash.}
+  s.email = %q{weppos@weppos.net}
+  s.extra_rdoc_files = ["CHANGELOG.rdoc", "lib/apache_log_regex/version.rb", "lib/apache_log_regex.rb", "lib/apachelogregex.rb", "README.rdoc"]
+  s.files = ["CHANGELOG.rdoc", "lib/apache_log_regex/version.rb", "lib/apache_log_regex.rb", "lib/apachelogregex.rb", "LICENSE.rdoc", "Manifest", "Rakefile", "README.rdoc", "setup.rb", "test/apache_log_regex_test.rb", "test/test_all.rb", "test/test_helper.rb", "apachelogregex.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://code.simonecarletti.com/apachelogregex}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Apachelogregex", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{apachelogregex}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Ruby parser for Apache log files based on regular expressions.}
+  s.test_files = ["test/test_all.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, [">= 0.8"])
+      s.add_development_dependency(%q<echoe>, [">= 3.1"])
+    else
+      s.add_dependency(%q<rake>, [">= 0.8"])
+      s.add_dependency(%q<echoe>, [">= 3.1"])
+    end
+  else
+    s.add_dependency(%q<rake>, [">= 0.8"])
+    s.add_dependency(%q<echoe>, [">= 3.1"])
+  end
+end

data/lib/apache_log_regex.rb

@@ -0,0 +1,174 @@
+#
+# = Apache Log Regex
+#
+# Ruby parser for Apache log files based on regular expressions.
+#
+# Category::    
+# Package::     ApacheLogRegex
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+# SVN: $Id$
+#++
+
+
+require 'apache_log_regex/version'
+
+
+#
+# = Apache Log Regex
+#
+# Parse a line from an Apache log file into a hash.
+#
+# This is a Ruby port of Peter Hickman's Apache::LogRegex 1.4 Perl module,
+# available at http://cpan.uwinnipeg.ca/~peterhi/Apache-LogRegex.
+# 
+# == Example Usage
+# 
+# The following one is the most simple example usage. 
+# It tries to parse the `access.log` file and echoes each parsed line.
+# 
+#   format = '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
+#   parser = ApacheLogRegex.new(format)
+#   
+#   File.foreach('/var/apache/access.log') do |line|
+#     begin
+#       parser.parse(line)
+#       # {"%r"=>"GET /blog/index.xml HTTP/1.1", "%h"=>"87.18.183.252", ... }
+#     rescue ApacheLogRegex::ParseError => e
+#       puts "Error parsing log file: " + e.message
+#     end
+#   end
+# 
+# More often, you might want to collect parsed lines and use them later in your program.
+# The following example iterates all log lines, parses them and returns an array of Hash with the results.
+# 
+#   format = '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
+#   parser = ApacheLogRegex.new(format)
+# 
+#   File.readlines('/var/apache/access.log').collect do |line|
+#     begin
+#       parser.parse(line)
+#       # {"%r"=>"GET /blog/index.xml HTTP/1.1", "%h"=>"87.18.183.252", ... }
+#     rescue ApacheLogRegex::ParseError => e
+#       nil
+#     end
+#   end
+# 
+class ApacheLogRegex
+  
+  NAME            = 'ApacheLogRegex'
+  GEM             = 'apachelogregex'
+  AUTHOR          = 'Simone Carletti <weppos@weppos.net>'
+  
+  
+  #
+  # = ParseError
+  #
+  # Raised in case the parser can't parse a log line with current +format+.
+  #
+  class ParseError < RuntimeError; end
+  
+  
+  # The normalized log file format.
+  # Some common formats:
+  # 
+  #   Common Log Format (CLF)
+  #   '%h %l %u %t \"%r\" %>s %b'
+  # 
+  #   Common Log Format with Virtual Host
+  #   '%v %h %l %u %t \"%r\" %>s %b'
+  # 
+  #   NCSA extended/combined log format
+  #   '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"'
+  # 
+  attr_reader :format
+
+  # Regexp instance used for parsing a log line.
+  attr_reader :regexp
+
+  # The list of field names that extracted from log format.
+  attr_reader :names
+
+
+  # Initializes a new parser instance with given log <tt>format</tt>.
+  def initialize(format)
+    @regexp = nil
+    @names  = []
+    @format = parse_format(format)
+  end
+
+  # Parses <tt>line</tt> according to current log <tt>format</tt>
+  # and returns an hash of log field => value on success.
+  # Returns <tt>nil</tt> if <tt>line</tt> doesn't match current log <tt>format</tt>.
+  def parse(line)
+    row = line.to_s
+    row.chomp!
+    row.strip!
+    return unless match = regexp.match(row)
+
+    data = {}
+    names.each_with_index { |field, index| data[field] = match[index + 1] } # [0] == line
+    data
+  end
+
+  # Same as <tt>ApacheLogRegex#parse</tt> but raises a <tt>ParseError</tt>
+  # if <tt>line</tt> doesn't match current <tt>format</tt>.
+  # 
+  # ==== Raises
+  # 
+  # ParseError:: if <tt>line</tt> doesn't match current <tt>format</tt>
+  # 
+  def parse!(line)
+    parse(line) || raise(ParseError, "Invalid format `%s` for line `%s`" % [format, line])
+  end
+  
+  
+  protected
+    
+    # Overwrite this method if you want to use some human-readable name for log fields.
+    # This method is called only once at <tt>parse_format</tt> time.
+    def rename_this_name(name)
+      name
+    end
+
+    # Parse log <tt>format</tt> into a suitable Regexp instance.
+    def parse_format(format)
+      format = format.to_s
+      format.chomp!                # remove carriage return
+      format.strip!                # remove leading and trailing space
+      format.gsub!(/[ \t]+/, ' ')  # replace tabulations or spaces with a space
+
+      strip_quotes = proc { |string| string.gsub(/^\\"/, '').gsub(/\\"$/, '') }
+      find_quotes  = proc { |string| string =~ /^\\"/ } 
+      find_percent = proc { |string| string =~ /^%.*t$/ }
+      find_referrer_or_useragent = proc { |string| string =~ /Referer|User-Agent/ }
+      
+      pattern = format.split(' ').map do |element|
+        has_quotes = !!find_quotes.call(element)
+        element = strip_quotes.call(element) if has_quotes
+        
+        self.names << rename_this_name(element)
+
+        case
+          when has_quotes
+            if element == '%r' or find_referrer_or_useragent.call(element)
+              /"([^"\\]*(?:\\.[^"\\]*)*)"/
+            else
+              '\"([^\"]*)\"'
+            end
+          when find_percent.call(element)
+              '(\[[^\]]+\])'
+          when element == '%U'
+              '(.+?)'
+          else
+              '(\S*)'
+        end
+      end.join(' ')
+
+      @regexp = Regexp.new("^#{pattern}$")
+      format
+    end
+
+end

data/lib/apache_log_regex/version.rb

@@ -0,0 +1,30 @@
+#
+# = Apache Log Regex
+#
+# Ruby parser for Apache log files based on regular expressions.
+#
+# Category::    
+# Package::     ApacheLogRegex
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+# SVN: $Id$
+#++
+
+
+class ApacheLogRegex
+  
+  module Version #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+  
+  VERSION         = Version::STRING
+  STATUS          = 'alpha'
+  BUILD           = ''.match(/(\d+)/).to_a.first
+  
+end

data/lib/apachelogregex.rb

@@ -0,0 +1,16 @@
+#
+# = Apache Log Regex
+#
+# Ruby parser for Apache log files based on regular expressions.
+#
+# Category::    
+# Package::     ApacheLogRegex
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+# SVN: $Id$
+#++
+
+
+require 'apache_log_regex'