lib/import/base.rb in tracksperanto-1.1.1 vs lib/import/base.rb in tracksperanto-1.2.0

@@ -1,34 +1,67 @@
-require 'stringio'
-
+# 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.
 class Tracksperanto::Import::Base
   include Tracksperanto::Safety
   include Tracksperanto::Casts
+  include Tracksperanto::BlockInit
+  include Tracksperanto::ZipTuples
   
+  # 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
-  # Some importers need it
-  cast_to_int :width
+  # The original width 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
   
-  # The original height of the original image.
-  # Some importers need it
-  cast_to_int :height
+  # The original height of the comp, same conventions as for width apply
+  attr_accessor :height
   
-  # Safety on readers
+  # 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
   def self.inherited(by)
     Tracksperanto.importers << by
     super
   end
   
-  # Call this method to tell what you are doing. This gets propagated to the caller
+  # Return an extension WITH DOT if this format has a typical extension that
+  # you can detect 
+  def self.distinct_file_ext
+    nil
+  end
+  
+  # Should return a human-readable (read: properly capitalized and with spaces) name of the
+  # import format
+  def self.human_name
+    "Abstract import format"
+  end
+  
+  # Return true from this method if your importer can deduce the comp size from the passed file
+  def self.autodetects_size?
+    false
+  end
+  
+  # Call this method to tell what you are doing. 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
   
-  # Should return an array of Tracksperanto::Tracker objects
-  def parse(track_file_content)
+  # The main method of the parser. Will receive an IO handle to the file being imported, and should
+  # return an array of Tracksperanto::Tracker objects containing keyframes. If you have a problem
+  # doing an import, raise from here.
+  def parse(track_file_io)
     []
   end
 end
\ No newline at end of file