anthonyw-dyno 0.0.3 → 0.1.0

data/README.markdown

@@ -1,14 +1,69 @@
 dyno
 ====
 
-A Ruby library for parsing sim-racing results files. Presently supports:
+> _A dynamometer or "dyno" for short, is a machine used to measure torque and
+> rotational speed (rpm) from which power produced by an engine, motor or
+> other rotating prime mover can be calculated. ([Wikipedia][dyno-wp])_
 
- * Race 07 / GTR: Evolution
+In this context, however, Dyno is a pure Ruby library for parsing sim-racing
+result files, soon to be used on the upcoming Torque sim-racing app.
 
-With support for the following in the near future:
+Dyno presently supports files spat out by a number of games:
 
- * rFactor
- * LFS
- * Arca
+* **Race07Parser** parses results from RACE 07, GTR: Evolution, and
+  STCC: The Game
+* **GTR2Parser** parses results from GTR2.
+* **RFactorParser** parses results from rFactor (and mods), and ARCA (coming
+  very soon).
 
-... once I've got my hands on some sample results files.
+Dyno requires the iniparse gem (available via `gem install iniparse` or on
+[GitHub][iniparse]) for the Race 07 and GTR2 parsers, and libxml-ruby for
+the rFactor parser.
+
+Usage
+-----
+
+    Dyno::Parsers::Race07Parser.parse_file( '/path/to/result/file' )
+    # => Dyno::Event
+
+    Dyno::Parsers::GTR2Parser.parse_file( '/path/to/result/file' )
+    # => Dyno::Event
+
+    Dyno::Parsers::RFactorParser.parse_file( '/path/to/result/file' )
+    # => Dyno::Event
+
+Each of these operations will return a Dyno::Event instance. Dyno::Event
+defines `#competitors` containing a collection of all of those who took part
+in the event. See the API docs for Dyno::Event and Dyno::Competitor for more
+details.
+
+If your results file couldn't be parsed, a Dyno::MalformedInputError exception
+will be raised.
+
+License
+-------
+
+Dyno is distributed under the MIT/X11 License.
+
+> Copyright (c) 2008-2009 Anthony Williams
+>
+> 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.
+
+[dyno-wp]:  http://en.wikipedia.org/wiki/Dynamometer "Wikipedia"
+[iniparse]: http://github.com/anthonyw/iniparse "IniParse on GitHub"

data/Rakefile

@@ -22,12 +22,13 @@ begin
               Dir.glob("{lib,spec}/**/*")
   end
 rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  puts 'Jeweler not available. Install it with: sudo gem install ' +
+       'technicalpickles-jeweler -s http://gems.github.com'
 end
 
-################################################################################
+##############################################################################
 # rSpec & rcov
-################################################################################
+##############################################################################
 
 desc "Run all examples"
 Spec::Rake::SpecTask.new('spec') do |t|

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 3
+:patch: 0
 :major: 0
-:minor: 0
+:minor: 1

data/lib/dyno.rb

@@ -1,5 +1,7 @@
 require 'rubygems'
 require 'time'
+require 'iniparse'
+require 'libxml'
 
 module Dyno
   # Base exception class.
@@ -9,10 +11,12 @@ module Dyno
   class MalformedInputError < DynoError; end
 end
 
-%w( competitor event ).each do |file|
-  require File.join( File.dirname(__FILE__), "dyno", file )
-end
+dir = File.join( File.dirname(__FILE__), "dyno" )
 
-Dir["#{ File.dirname(__FILE__) }/dyno/parsers/*_parser.rb"].sort.each do |parser|
-  require parser
-end
+require File.join( dir, "competitor" )
+require File.join( dir, "event" )
+
+# Parsers
+require File.join( dir, "parsers", "race07_parser" )
+require File.join( dir, "parsers", "gtr2_parser" )
+require File.join( dir, "parsers", "rfactor_parser" )

data/lib/dyno/competitor.rb

@@ -10,10 +10,46 @@ module Dyno
     def initialize(name, properties = {})
       @name = name
       @lap_times = properties.fetch(:laps, [])
+      @dnf = false
 
       [:uid, :position, :vehicle, :laps, :race_time, :best_lap].each do |prop|
         instance_variable_set "@#{prop}", properties[prop]
       end
     end
+
+    ##
+    # Returns true fi the competitor finished the event.
+    #
+    def finished?
+      not dnf? and not dsq?
+    end
+
+    ##
+    # Flags this competitor as having not completed the event.
+    #
+    def dnf!
+      @dnf = :dnf
+    end
+
+    ##
+    # Returns true if the competitor failed to finish.
+    #
+    def dnf?
+      @dnf == :dnf
+    end
+
+    ##
+    # Flags this competitor has having been disqualified from the event.
+    #
+    def dsq!
+      @dnf = :dsq
+    end
+
+    ##
+    # Returns true if the competitor was disqualified.
+    #
+    def dsq?
+      @dnf == :dsq
+    end
   end
 end

data/lib/dyno/parsers/gtr2_parser.rb

@@ -0,0 +1,13 @@
+module Dyno::Parsers
+  ##
+  # Parses a Race 07 results file which are almost identical to Race 07 files.
+  #
+  class GTR2Parser < Race07Parser
+    def self.parse_file( filename )
+      # GTR2 files start with a line which isn't valid INI; remove it.
+      parse( IniParse.parse(
+        File.read( filename ).sub!(/^.*\n/, '')
+      ) )
+    end
+  end
+end

data/lib/dyno/parsers/race07_parser.rb

@@ -1,14 +1,8 @@
-require 'iniparse'
-
 module Dyno::Parsers
   ##
   # Parses a Race 07 results file (which appears to be some variation of the
   # ini format).
   #
-  # TODO: Remove dependency on inifile and write our own ini parser so that:
-  #   * we can extract individual lap information.
-  #   * we don't have to have a results file on disk.
-  #
   class Race07Parser
     ##
     # Takes a file path and parses it.
@@ -20,10 +14,10 @@ module Dyno::Parsers
     end
 
     ##
-    # Takes an IniFile instance, parses the contents, and returns a
+    # Takes an IniParse::Document instance, parses the contents, and returns a
     # Dyno::Event containing your results.
     #
-    # @param  [IniFile] results The results.
+    # @param  [IniParse::Document] results The results.
     # @return [Dyno::Event]
     #
     def self.parse( results )
@@ -44,9 +38,9 @@ module Dyno::Parsers
     #######
 
     ##
-    # Takes an IniFile instance and parses the contents.
+    # Takes an IniParse::Document instance and parses the contents.
     #
-    # @param  [IniFile] results The results.
+    # @param [IniParse::Document] results The results.
     #
     def initialize( results )
       @raw = results
@@ -58,7 +52,7 @@ module Dyno::Parsers
     def parse_event!
       raise Dyno::MalformedInputError unless @raw.has_section?('Header')
 
-      @event = Dyno::Event.new( :game => 'Race 07' )
+      @event = Dyno::Event.new( :game => @raw['Header']['Game'] )
       @event.time = Time.parse( @raw['Header']['TimeString'] )
       @event.game_version = @raw['Header']['Version']
 
@@ -97,8 +91,9 @@ module Dyno::Parsers
           lap_time_to_float(lap.split(',').last.strip)
         end
 
-        if section['RaceTime'] == 'DNF'
-          competitor.race_time = 'DNF'
+        if section['RaceTime'] =~ /D(NF|S?Q)/
+          $1 == 'NF' ? competitor.dnf! : competitor.dsq!
+          competitor.race_time = 0
           dnf_competitors << competitor
         else
           time = section['RaceTime'].split( /:|\./ )
@@ -111,7 +106,9 @@ module Dyno::Parsers
       end
 
       # Sort finished competitors by their race time, lowest (P1) first.
-      finished_competitors = finished_competitors.sort_by { |c| c.race_time }
+      finished_competitors = finished_competitors.sort_by do |c|
+        [ - c.laps, c.race_time ]
+      end
 
       # ... and DNF'ed competitors by how many laps they've done.
       dnf_competitors = dnf_competitors.sort_by { |c| c.laps }.reverse!

data/lib/dyno/parsers/rfactor_parser.rb

@@ -0,0 +1,138 @@
+module Dyno::Parsers
+  ##
+  # Parses a rFactor results files.
+  #
+  class RFactorParser
+    ##
+    # Takes a file path and parses it.
+    #
+    # @param [String] filename The path to the results file.
+    #
+    def self.parse_file( filename )
+      xmlparser = LibXML::XML::Parser.new
+      xmlparser.file = filename
+      parse( xmlparser.parse )
+    end
+
+    ##
+    # Takes a LibXML::XML::Document instance, parses the contents, and returns
+    # a Dyno::Event containing your results.
+    #
+    # @param  [LibXML::XML::Document] results The results.
+    # @return [Dyno::Event]
+    #
+    def self.parse( results )
+      new( results ).parse
+    end
+
+    ##
+    # Returns your parsed event and competitor information.
+    #
+    def parse
+      parse_event!
+      parse_competitors!
+      @event
+    end
+
+    #######
+    private
+    #######
+
+    ##
+    # Takes a LibXML::XML::Document instance and parses the contents.
+    #
+    # @param [LibXML::XML::Document] results The results.
+    #
+    def initialize( results )
+      @doc   = results
+      @stack = []
+    end
+
+    ##
+    # Extracts the event information from the results.
+    #
+    def parse_event!
+      unless results = @doc.find_first('//RaceResults')
+        raise Dyno::MalformedInputError, 'No //RaceResults node.'
+      end
+
+      with_node(results) do
+        @event = Dyno::Event.new(
+          :game         => clean(value('Mod').gsub(/\.rfm$/, '')),
+          :track        => clean(value('TrackCourse')),
+          :game_version => value('GameVersion')
+        )
+
+        # Sort out the event time - the rFactor results format has more than
+        # one TimeString node. The first appears to be when the server was
+        # started - we need the time of the event itself, which is held under
+        # the Race, Qualify or Warmup node.
+        if event_node = \
+              (@doc.find_first('//RaceResults/Race')    ||
+               @doc.find_first('//RaceResults/Qualify') ||
+               @doc.find_first('//RaceResults/Warmup'))
+          with_node(event_node) do
+            @event.time = Time.parse( value('TimeString') )
+          end
+        end
+      end
+    end
+
+    ##
+    # Extracts information about each of the competitors.
+    #
+    def parse_competitors!
+      @doc.find('//Driver').each do |section|
+        with_node(section) do
+          competitor = Dyno::Competitor.new(value('Name'),
+            :vehicle => clean(value('CarType')),
+            :laps    => value('Laps').to_i
+          )
+
+          competitor.position  = value('Position').to_i
+          competitor.best_lap  = lap_time_to_float( value('BestLapTime') )
+          competitor.race_time = lap_time_to_float( value('FinishTime') )
+
+          competitor.lap_times = section.find('Lap').map do |lap|
+            lap_time_to_float( lap.content )
+          end
+
+          if value('FinishStatus') =~ /D(NF|S?Q)/
+            $1 == 'NF' ? competitor.dnf! : competitor.dsq!
+          end
+
+          @event.competitors << competitor
+        end
+      end
+
+      @event.competitors = @event.competitors.sort_by { |c| c.position }
+    end
+
+    # --
+    # Utility stuff
+    # ++
+
+    def value( node ) # :nodoc:
+      if found = @stack.last.find_first( node )
+        found.content
+      else
+        nil
+      end
+    end
+
+    def clean( value ) # :nodoc:
+      value.gsub(/[-_]/, ' ').squeeze(' ') unless value.nil?
+    end
+
+    def with_node( node ) # :nodoc:
+      @stack.push( node )
+      yield
+      @stack.pop
+    end
+
+    # Converts a lap time (in the format of M:SS:SSS) to a float.
+    def lap_time_to_float(time) # :nodoc:
+      (time.nil? || time == '--.----') ? 0.0 : Float(time)
+    end
+  end
+end

data/spec/competitor_spec.rb

@@ -1,7 +1,7 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
 describe Dyno::Competitor do
-  before(:all) do
+  before(:each) do
     @competitor = Dyno::Competitor.new("Jake Lucas")
   end
 
@@ -40,10 +40,16 @@ describe Dyno::Competitor do
     @competitor.should respond_to(:best_lap=)
   end
 
+  it 'should respond_to #finished?' do
+    @competitor.should respond_to(:finished?)
+  end
+
   it 'should respond_to #dnf?' do
-    pending do
-      @competitor.should respond_to(:dnf)
-    end
+    @competitor.should respond_to(:dnf?)
+  end
+
+  it 'should respond_to #dsq?' do
+    @competitor.should respond_to(:dsq?)
   end
 
   # ----------
@@ -71,4 +77,53 @@ describe Dyno::Competitor do
     lambda { Dyno::Competitor.new }.should raise_error(ArgumentError)
   end
 
+  # ---------------------------------
+  # finished / dnf / disqualification
+
+  describe 'when the competitor finished the event' do
+    it 'should return true to #finished?' do
+      @competitor.should be_finished
+    end
+
+    it 'should return false to #dnf?' do
+      @competitor.should_not be_dnf
+    end
+
+    it 'should return false to #dsq?' do
+      @competitor.should_not be_dsq
+    end
+  end
+
+  describe 'when the competitor did not finish' do
+    before { @competitor.dnf! }
+
+    it 'should return false to #finished?' do
+      @competitor.should_not be_finished
+    end
+
+    it 'should return true to #dnf?' do
+      @competitor.should be_dnf
+    end
+
+    it 'should return false to #dsq?' do
+      @competitor.should_not be_dsq
+    end
+  end
+
+  describe 'when the competitor was disqualified' do
+    before { @competitor.dsq! }
+
+    it 'should return false to #finished?' do
+      @competitor.should_not be_finished
+    end
+
+    it 'should return false to #dnf?' do
+      @competitor.should_not be_dnf
+    end
+
+    it 'should return true to #dsq?' do
+      @competitor.should be_dsq
+    end
+  end
+
 end