We wanted the procedural markup engine to be very modular. It had to be easy to add new parsers that generated the tags and we wanted to be able to throw any sort of media at the framework and for the parsers to be able to request the particular type of input they needed. So, when a piece of media is to be marked up, we need to work out which parsers are applicable. For instance, if you have a parser that attempts to detect faces in video, theres no point trying to run an MP3 audio file through that parser. Conversely, if you have a parser that expects its input as raw uncompressed audio samples, an MP3 file would need to be pre-converted for the parser to receive what it expects.

To that end, each parser needs to tell the system the media types and formats it wants and the framework must perform the transcoding.

Now, there are thousands of different formats of data, so how can we write a transcoding framework for them all? We can't. But we CAN make a subframework which will let us express a subset of transformations and make the system work out chains of these transformations that do what we need. So, instead of direct transcoding instructions from every type to every other type, we define a network or 'graph' of transformations. Each node on the graph is a mime type, and we define a small set of ways to transform from one mime type to another. Provided the graph has enough basic transformations we can get from any one mime type to any other. This sort of system is called a 'Directed Graph'

So, lets define some classes to allow us to build a directed graph.

First, lets see what we want to be able to do to define nodes and transformations.

class AudioMpeg < MimeType
  mime_type 'audio/mpeg'
  extension 'mp3'
end

class FromMp3ToWav < Transformation
  comes_from AudioMp3, AudioMpeg
  goes_to AudioWav

  def self.command_string
    "mpg123 -w #{new_file_name_with_path} #{old_file_name_with_path}"
  end
end

class MimeType
  private
  def self.from
    @from_list ||= Array.new
  end

  def self.to
    @to_list ||= Array.new
  end

  def self.mime_type type_string = nil
    @mime_type = type_string unless type_string.nil?
    @mime_type
  end

  def self.extension extension_string = nil
    @extension = extension_string unless extension_string.nil?
    @extension
  end

  # implement finder
  def self.inherited klass
    subclasses << klass
  end

  def self.subclasses
    @subclasses ||= Array.new
  end

  def self.find mime_type
    puts "Attempting to find mime type = #{mime_type}(#{mime_type})"
    subclasses.detect{|klass| klass.mime_type == mime_type}
  end

end

class Transformation

  def self.comes_from *types
    @from = types
    types.each{|t| t.from << self}
  end

  def self.goes_to type
    @to = type
    type.to << self
  end

  def self.block
    @block
  end

  def self.to
    @to
  end

  def self.from
    @from
  end

  def self.new_extension
    @to.nil? ? nil : @to.extension
  end

  def self.set_file_name file_name
    @file_name = file_name
  end

  def self.do file_name
    set_file_name file_name

    LogLine.record(:component => 'TRANSFORMATION',
                   :event => 'ATTEMPT',
                   :message => "Transform #{old_file_name} #{self.name} #{new_file_name}")

    transformation_command

    # now, check if the expectant file exists.
    LogLine.record(:component => 'TRANSFORMATION',
                   :event => 'FAILED',
                   :message => "Expected Transformation(#{self.name}) to produce #{new_file_name}, but was not") unless
                   File.exist?(new_file_name_with_path)    

    LogLine.record(:component => 'TRANSFORMATION',
                   :event => 'FAILED',
                   :message => "Expected Transformation(#{self.name}) to produce #{new_file_name}, but was empty") if
                   File.zero?(new_file_name_with_path)    

    # return the raw name
    new_file_name
  end

  def self.path_to_datafiles
    "#{File.expand_path(RAILS_ROOT)}/scratch_data"
  end

  def self.old_file_name_with_path
    "#{path_to_datafiles}/#{old_file_name}"
  end

  def self.old_file_name
    @file_name
  end

  def self.file_name_sans_extension
    @file_name.split('.')[0 .. -2].join('.')
  end

  def self.new_file_name_with_path
    "#{path_to_datafiles}/#{new_file_name}"
  end

  def self.transformation_command
    `#{command_string}`
  end

  def self.new_file_name
    candidate = "#{file_name_sans_extension}.#{new_extension}"

    candidate = "new_#{candidate}" if candidate == old_file_name

    candidate
  end  

  class BannedTransformation < RuntimeError
  end
end