base.rb in tracksperanto-2.2.0

- old
+ new

@@ -1,37 +1,36 @@
-# The base class for all the import modules. By default, when you inherit from this class the inherited class will be included
-# in the list of supported Tracksperanto importers. The API that an importer should present is very basic, and consists only of a few methods.
-# The main method is parse(io) which should return an array of Tracker objects.
+# The base class for all the import modules. By default, when you inherit from
+# this class the inherited class will be included in the list of supported
+# Tracksperanto importers. The API that an importer should present is very
+# basic, and consists only of a few methods. The main method is
+# stream_parse(io)
 class Tracksperanto::Import::Base
+  include Enumerable
   include Tracksperanto::Safety
   include Tracksperanto::Casts
   include Tracksperanto::BlockInit
   include Tracksperanto::ZipTuples
   include Tracksperanto::ConstName
   
-  # Every time the importer accumulates a tracker this object's #push method will be called.
-  # Can be an array or a more full-featured buffer
-  attr_accessor :receiver
+  # Handle to the IO with data being parsed
+  attr_accessor :io
   
   # Tracksperanto will assign a proc that reports the status of the import to the caller.
   # This block is automatically used by report_progress IF the proc is assigned. Should
   # the proc be nil, the report_progress method will just pass (so you don't need to check for nil
   # yourself)
   attr_accessor :progress_block
   
-  # The original width of the tracked image.
+  # The original width and height of the tracked image.
   # If you need to know the width for your specific format and cannot autodetect it,
   # Trakcksperanto will assign the passed width and height to the importer object before running
   # the import. If not, you can replace the assigned values with your own. At the end of the import
   # procedure, Tracksperanto will read the values from you again and will use the read values
   # for determining the original comp size. +width+ and +height+ MUST return integer values after
   # the import completes
-  attr_accessor :width
+  attr_accessor :width, :height
   
-  # The original height of the comp, same conventions as for width apply
-  attr_accessor :height
-  
   # These reader methods will raise when the values are nil
   cast_to_int :width, :height
   safe_reader :width, :height
   
   # Used to register your importer in the list of supported formats.
@@ -39,10 +38,13 @@
   def self.inherited(by)
     Tracksperanto.importers << by
     super
   end
   
+  # OBSOLETE, do not use
+  attr_accessor :receiver
+  
   # Return an extension WITH DOT if this format has a typical extension that
   # you can detect (like ".nk" for Nuke) 
   def self.distinct_file_ext
     nil
   end
@@ -62,30 +64,17 @@
   # This gets propagated to the caller automatically, or gets ignored if the caller did not request any progress reports
   def report_progress(message)
     @progress_block.call(message) if @progress_block
   end
   
-  # OBSOLETE: do not implement this method in your importer. This is used to accumulate trackers in an array
-  # and then send it to the caller. Used in tests.
-  def parse(track_file_io)
-    @receiver = []
-    stream_parse(track_file_io)
-    @receiver
+  # The main method of the parser. Should
+  # yield each tracker that has been fully parsed. After calling this method the caller can ask for
+  # width and height as well.
+  def each
   end
   
-  # The main method of the parser. Will receive an IO handle to the file being imported, and should
-  # send each consecutive tracker via the send_tracker method.
-  # Note that in general it's a good idea to stream-parse a document
-  # instead of bulk-reading it into memory (since Tracksperanto tries to be mem-efficient when dealing
-  # with large files)
-  def stream_parse(track_file_io)
-  end
-  
-  # When a tracker has been detected completely (all keyframes) call this method with the tracker object as argument
+  # OBSOLETE: do not use
   def send_tracker(tracker_obj)
-    if @receiver
-      @receiver.push(tracker_obj)
-    else
-      raise "Tracker received but no @receiver has been set for #{self.inspect}"
-    end
+    STDERR.puts "Import::Base#send_tracker has been deprecated, please rewrite your importer to use yield(t) inside each instead"
+    @receiver.push(tracker_obj)
   end
 end
\ No newline at end of file