subtitle_shifter 1.0.0.0 → 1.1.0.0

data/lib/subtitle_shifter.rb

@@ -1,25 +1,72 @@
 
 # encoding: UTF-8
 
+#@example Manipulate subtitles from the command line
+#  $ subtitle_shifter --help
+#  $ subtitle_shifter --operation add --index 12 --time 2,345 source.srt dest.srt
+#@example Manipulate subtitles from within a ruby program
+#  # This will shift all subtitles from index 12 onward by 2.345 seconds
+#  # or 2345 milliseconds
+#  subs = SubtitleShifter.new('mysubs.srt')
+#  subs.parse
+#  subs.shift(:index => 12, :time => 2345)
+#@example Shift subtitles backward
+#  # This will shift subtitles backward, beware - you cannot shift
+#  # subtitles backward so that they overlap the preceding subtitles.
+#  # A RuntimeError exception will be raised if this occurs.
+#  subs.shift(:index => 12, :time => -2345) # Simply provide a negative time value
+#@example Output subtitles once they've been parsed and/or manipulated
+#  puts subs
+#  # -- or --
+#  subs.to_s
+#@see http://en.wikipedia.org/wiki/Subrip Wikipedia's article on the SubRip format
 class SubtitleShifter
   module Version
     MAJOR = 1
-    MINOR = 0
+    MINOR = 1
     PATCH = 0
     BUILD = 0
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
   end
 
-  attr_reader :subtitles, :parsed_ok
-
+  # A boolean flag highlighting whether or not subtitles have been parsed yet
+  attr_reader :parsed_ok
+  # A hash of the parsed subtitles. You normally wouldn't need to access this directly
+  # @example The format of the hash is as follows
+  #   {1 => {:start => 107,
+  #          :end   => 5762,
+  #          :subtitle => 'This is the first subtitle'
+  #         },
+  #   {2 => {:start => 5890,
+  #          :end   => 10553,
+  #          :subtitle => 'This is the second subtitle'
+  #         }
+  # @note I chose to implement internal representation of subtitle files as a hash
+  #   and not an array, which would've been more efficient, as subtitles cannot be
+  #   guaranteed to start at index 1
+  #   That being said, I can already think of a way to do this using an array and offset attribute
+  attr_reader :subtitles
+
+  # The delimiter used for separating SubRip time stamps
   TIME_SEPERATOR = '-->'
 
+  # @param [String] file      A string of the file name
+  # @param [String] linebreak A string of the linebreak pattern.
   def initialize(file, linebreak = "\r\n")
     @sub_file  = file
     @linebreak = linebreak
+    @parsed_ok = false
   end
 
+  # Parses the subtitles
+  # @note Always call only after initialising.
+  # @note If your subtitle file is UTF-8 encoded, and has a Byte Order Mark as its first few bytes,
+  #   the BOM will not be preserved when outputing the parsed and shifted subtitles. You probably don't
+  #   need it anyway
+  # @example
+  #   sub.parse if sub.parsed_ok
+  # @see http://en.wikipedia.org/wiki/UTF-8#Byte_order_mark Wikipedia's article on UTF-8 and BOM
   def parse
     raw_text  = File.open(@sub_file, 'r').read.force_encoding('UTF-8')
     raw_text.gsub!("\xEF\xBB\xBF".force_encoding("UTF-8"), '') #Remove stupid BOM that was causing me so much grief!
@@ -37,6 +84,12 @@ class SubtitleShifter
     @parsed_ok = true # Not very useful, but will help when error checking is added
   end
 
+  # Shifts subtitles forward (or backward) by a number of ms from an index
+  # @param [Integer] :index The index of the subtitle
+  # @param [Integer] :time The time (in ms) by which you wish to shift the subtitles. A negative value will shift backwards.
+  # @example
+  #   sub.shift(:index => 42, :time => 10000) # Shift subs from index 42 onwards by 10 seconds.
+  # @raise [RuntimeError] Raises this exception when shifting backwards if index and index-1 time's overlap
   def shift(args)
     first = args[:index] # used for checking first go round.
     index = first
@@ -58,6 +111,9 @@ class SubtitleShifter
     end
   end
 
+  # Outputs parsed subtitles
+  # @raise [RuntimeError] Will raise this exception if an attempt is made to output the subs before parsing has taken place
+  # @see SubtitleShifter#parsed_ok
   def to_s
     raise RuntimeError, 'File has not been parsed yet' unless @parsed_ok
 

data/subtitle_shifter.gemspec

@@ -0,0 +1,64 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{subtitle_shifter}
+  s.version = "1.1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{Gabriel Fortuna}]
+  s.date = %q{2011-12-13}
+  s.description = %q{A simple little gem for modifying SubRip subtitle files. Done as a mentoring exercise with Citizen428, and taken from the Ruby Programming Challenge For Newbies}
+  s.email = %q{gee.forr@gmail.com}
+  s.executables = [%q{shift_subtitle}]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "bin/shift_subtitle",
+    "lib/.subtitle_shifter.rb.swp",
+    "lib/subtitle_shifter.rb",
+    "subtitle_shifter.gemspec",
+    "test/The.Big.Bang.Theory.srt",
+    "test/helper.rb",
+    "test/subtitle_shifter_spec.rb"
+  ]
+  s.homepage = %q{http://github.com/gee-forr/subtitle_shifter}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.6}
+  s.summary = %q{A simple library for adjusting SubRip (.srt) subtitles}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+    else
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rdoc>, [">= 0"])
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: subtitle_shifter
 version: !ruby/object:Gem::Version
-  version: 1.0.0.0
+  version: 1.1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-12-13 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70285953842120 !ruby/object:Gem::Requirement
+  requirement: &70158991265800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70285953842120
+  version_requirements: *70158991265800
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70285953840700 !ruby/object:Gem::Requirement
+  requirement: &70158987679900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70285953840700
+  version_requirements: *70158987679900
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70285953839740 !ruby/object:Gem::Requirement
+  requirement: &70158987678000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70285953839740
+  version_requirements: *70158987678000
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &70285953838260 !ruby/object:Gem::Requirement
+  requirement: &70158987676420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70285953838260
+  version_requirements: *70158987676420
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70285953837240 !ruby/object:Gem::Requirement
+  requirement: &70158987674940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70285953837240
+  version_requirements: *70158987674940
 description: A simple little gem for modifying SubRip subtitle files. Done as a mentoring
   exercise with Citizen428, and taken from the Ruby Programming Challenge For Newbies
 email: gee.forr@gmail.com
@@ -84,6 +84,7 @@ files:
 - bin/shift_subtitle
 - lib/.subtitle_shifter.rb.swp
 - lib/subtitle_shifter.rb
+- subtitle_shifter.gemspec
 - test/The.Big.Bang.Theory.srt
 - test/helper.rb
 - test/subtitle_shifter_spec.rb