tickly 0.0.8 → 1.0.0

data/Gemfile

@@ -1,7 +1,4 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
 
 gem "bychar", "~> 1.2"
 

data/README.rdoc

@@ -5,18 +5,19 @@ the passed Nuke scripts into a TCL AST and return it. You can use some cheap tri
 
 == Parsing
 
-Create a Parser object and pass TCL expressions/scripts to it. You can pass IO obejcts or strings. For example:
+Create a Parser object and pass TCL expressions/scripts to it. You can pass IO obejcts or strings. Note that parse()
+will always return an Array of expressions, even if you only fed it one expression line. For example:
     
     p = Tickly::Parser.new
     
-    # One expression
-    p.parse '2' #=> ["2"]
+    # One expression, even if it's invalid (2 is not a valid TCL bareword)- doesn't matter
+    p.parse '2' #=> [["2"]]
     
     # TCL command
-    p.parse "tail $list" #=> ["tail", "$list"]
+    p.parse "tail $list" #=> [["tail", "$list"]]
     
     # Multiple expressions
-    p.parse "2\n2" #=> [["2", "2"]]
+    p.parse "2\n2" #=> [["2"], ["2"]]
     
     # Expressions in curly braces   
     p.parse '{2 2}' #=> [[:c, "2", "2"]]
@@ -65,6 +66,10 @@ the evaulation you need to create classes matching the node classes by name. For
       end
     end
 
+== Animation curves
+
+You can parse Nuke's animation curves using Tickly::Curve. This will give you a way to iterate over every defined keyframe.
+
 == Contributing to tickly
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

data/lib/tickly.rb

@@ -1,14 +1,15 @@
 require File.dirname(__FILE__) + "/tickly/parser"
 require File.dirname(__FILE__) + "/tickly/node_extractor"
 require File.dirname(__FILE__) + "/tickly/evaluator"
+require File.dirname(__FILE__) + "/tickly/curve"
 require 'forwardable'
 
 module Tickly
-  VERSION = '0.0.8'
+  VERSION = '1.0.0'
   
   # Provides the methods for quickly emitting the expression arrays,
   # is used in tests
-  module Emitter
+  module Emitter #:nodoc :all
     def le(*elems)
       [:c] + elems
     end
@@ -22,21 +23,4 @@ module Tickly
     end
   end
   
-  # Converts a passed Array (received from a Parser)
-  # into a TCL expression. This is only ever used in tests
-  def self.to_tcl(e)
-    if e.is_a?(Array) && e[0] == :c
-      '{%s}' % e.map{|e| to_tcl(e)}.join(' ')
-    elsif e.is_a?(Array) && e[0] == :b
-      '[%s]' % e.map{|e| to_tcl(e)}.join(' ')
-    elsif e.is_a?(Array)
-      e.map{|e| to_tcl(e)}.join(" ")
-    elsif e.is_a?(String) && (e.include?('"') || e.include?("'"))
-      e.inspect
-    else
-      e.to_s
-    end
-  end
-  
-  
 end

data/lib/tickly/curve.rb

@@ -0,0 +1,59 @@
+module Tickly
+  # A shorthand class for Nuke's animation curves.
+  # Will convert a passed Curve expression into a set of values,
+  # where all the values are baked per integer frames on the whole
+  # stretch of time where curve is defined
+  class Curve
+    
+    class InvalidCurveError < RuntimeError; end
+    
+    include Enumerable
+    
+    SECTION_START = /^x(\d+)$/
+    KEYFRAME = /^([-\d\.]+)$/
+    
+    # The constructor accepts a Curve expression as returned by the Parser
+    # Normally it looks like this
+    #     [:c, "curve", "x1", "123", "456", ...]
+    def initialize(curve_expression)
+      raise InvalidCurveError, "A curve expression should have :c as it's first symbol" unless curve_expression[0] == :c
+      raise InvalidCurveError, "A curve expression should start with a `curve' command" unless curve_expression[1] == "curve"
+      raise InvalidCurveError, "Curve expression contained no values" unless curve_expression[2]
+      
+      expand_curve(curve_expression)
+    end
+    
+    # Returns each defined keyframe as a pair of a frame number and a value
+    def each(&blk)
+      @tuples.each(&blk)
+    end
+    
+    private
+    
+    def expand_curve(curve_expression)
+      # Replace the closing curly brace with a curly brace with space so that it gets caught by split
+      atoms = curve_expression[2..-1] # remove the :c curly designator and the "curve" keyword
+      
+      @tuples = []
+      # Nuke saves curves very efficiently. x(keyframe_number) means that an uninterrupted sequence of values will start,
+      # after which values follow. When the curve is interrupted in some way a new x(keyframe_number) will signifu that we
+      # skip to that specified keyframe and the curve continues from there, in gap size defined by the last fragment.
+      # That is, x1 1 x3 2 3 4 will place 2, 3 and 4 at 2-frame increments.
+      # Thanks to Michael Lester for explaining this.
+      last_processed_keyframe = 1
+      intraframe_gap_size = 1
+      while atom = atoms.shift
+        if atom =~ SECTION_START
+          last_processed_keyframe = $1.to_i
+          if @tuples.any?
+            last_captured_frame = @tuples[-1][0]
+            intraframe_gap_size = last_processed_keyframe - last_captured_frame
+          end
+        elsif  atom =~ KEYFRAME
+          @tuples << [last_processed_keyframe, $1.to_f]
+          last_processed_keyframe += intraframe_gap_size
+        end
+      end
+    end
+  end
+end

data/lib/tickly/evaluator.rb

@@ -1,9 +1,35 @@
 module Tickly
   # Evaluates a passed TCL expression without expanding it's inner arguments.
-  # The TCL should look like Nuke's node commands (i.e. NodeClass { foo bar; baz bad; } and so on)
+  # The TCL should look like Nuke's node commands:
+  #
+  #   NodeClass { 
+  #     foo bar
+  #     baz bad
+  #   }
+  #
   # You have to add the Classes that you want to instantiate for nodes using add_node_handler_class
   # and the evaluator will instantiate the classes it finds in the passed expression and pass the
-  # node options (actually TCL commands) to the constructor, as a Ruby Hash with string keys.
+  # node options (actually TCL commands) to the constructor, as a Ruby Hash with string keys. 
+  # Every value of the knobs hash will be the AST as returned by the Parser.
+  # You have to pass every expression returned by Tickly::Parser#parse separately.
+  #
+  #    class Blur
+  #      def initialize(knobs_hash)
+  #         puts knobs_hash.inspect
+  #      end
+  #    end
+  #    
+  #    e = Tickly::Evaluator.new
+  #    e.add_node_handler_class Blur
+  #    p = Tickly::Parser.new
+  #     
+  #    expressions = p.parse(some_nuke_script)
+  #    expressions.each do | expr |
+  #      # If expr is a Nuke node constructor, a new Blur will be created and yielded
+  #      e.evaluate(expr) do | node_instance|
+  #         # do whatever you want to the node instance
+  #      end
+  #    end
   class Evaluator
     def initialize
       @node_handlers = []

data/lib/tickly/parser.rb

@@ -2,20 +2,27 @@ require 'stringio'
 require 'bychar'
 
 module Tickly
-  
-  
   # Simplistic, incomplete and most likely incorrect TCL parser
   class Parser
     
     # Parses a piece of TCL and returns it converted into internal expression
     # structures. A basic TCL expression is just an array of Strings. An expression
     # in curly braces will have the symbol :c tacked onto the beginning of the array.
-    # An expression in square braces will have :b at the beginning.
+    # An expression in square braces will have the symbol :b tacked onto the beginning.
+    # This method always returns a Array of expressions. If you only fed it one expression,
+    # this expression will be the only element of the array.
+    # The correct way to use the returned results is thusly:
+    #
+    #   p = Tickly::Parser.new
+    #   expressions = p.parse("2 + 2") #=> [["2", "+", "2"]]
+    #   expression = expressions[0] #=> ["2", "2"]
     def parse(io_or_str)
       bare_io = io_or_str.respond_to?(:read) ? io_or_str : StringIO.new(io_or_str)
       # Wrap the IO in a Bychar buffer to read faster
       reader = Bychar::Reader.new(bare_io)
-      sub_parse(reader)
+      # Use multiple_expressions = true so that the top-level parsed script is always an array
+      # of expressions
+      sub_parse(reader, stop_char = nil, stack_depth = 0, multiple_expressions = true)
     end
     
     # Override this to remove any unneeded subexpressions Modify the passed expr
@@ -46,13 +53,12 @@ module Tickly
     # or until the IO is exhausted. The last argument is the class used to
     # compose the subexpression being parsed. The subparser is reentrant and not
     # destructive for the object containing it.
-    def sub_parse(io, stop_char = nil, stack_depth = 0)
+    def sub_parse(io, stop_char = nil, stack_depth = 0, multiple_expressions = false)
       # A standard stack is an expression that does not evaluate to a string
       expressions = []
       stack = []
       buf = ''
       last_char_was_linebreak = false
-      multiple_expressions = false
       
       no_eof do
         char = io.read_one_byte!

data/test/test_curve.rb

@@ -0,0 +1,31 @@
+require "helper"
+
+class TestCurve < Test::Unit::TestCase
+  def test_parsing_nuke_curve
+    curve = [:c] + %w( curve x742 888 890.2463989 891.6602783 
+893.5056763 895.6155396 s95 897.2791748 899.1762695 
+x754 912.0731812 x755 913.7190552 916.0959473 918.1025391 920.0751953 922.1898804 )
+    
+    p = Tickly::Curve.new(curve)
+    result = p.to_a
+    
+    assert_kind_of Array, result
+    assert_equal 13, result.length
+    assert_equal 742, result[0][0]
+    assert_equal 754, result[7][0]
+  end
+  
+  def test_invalid_curves
+    assert_raise Tickly::Curve::InvalidCurveError do
+      Tickly::Curve.new([])
+    end
+    
+    assert_raise Tickly::Curve::InvalidCurveError do
+      Tickly::Curve.new([:c])
+    end
+    
+    assert_raise Tickly::Curve::InvalidCurveError do
+      Tickly::Curve.new([:c, "curve"])
+    end
+  end
+end

data/test/test_parser.rb

@@ -5,33 +5,33 @@ class TestParser < Test::Unit::TestCase
   include Tickly::Emitter
   
   should "parse a single int as a stack with a string" do
-    assert_equal e("2"), P.parse('2')
+    assert_equal e(e("2")), P.parse('2')
   end
 
   should "parse a single int and discard whitespace" do
     p = P.parse('   2 ')
-    assert_equal e("2"), p
+    assert_equal e(e("2")), p
   end
 
   should "parse multiple ints and strings as a stack of subexpressions" do
-    assert_equal e("2", "foo", "bar", "baz"), P.parse('2 foo bar baz')
+    assert_equal e(e("2", "foo", "bar", "baz")), P.parse('2 foo bar baz')
   end
   
   should "parse and expand a string in double quotes" do
     p = P.parse('"This is a string literal with spaces"')
-    assert_equal e("This is a string literal with spaces"), p
+    assert_equal e(e("This is a string literal with spaces")), p
     
     p = P.parse('"This is a string literal \"escaped\" with spaces"')
-    assert_equal e("This is a string literal \"escaped\" with spaces"), p
+    assert_equal e(e("This is a string literal \"escaped\" with spaces")), p
   end
   
   should "parse a string expression" do
-    assert_equal e(se("1", "2", "3")),  P.parse("[1 2 3]")
+    assert_equal e(e(se("1", "2", "3"))),  P.parse("[1 2 3]")
   end
   
   should "parse multiple string expressions" do
     p = P.parse("[1 2 3] [3 4 5 foo]")
-    assert_equal e(se("1", "2", "3"), se("3", "4", "5", "foo")), p
+    assert_equal e(e(se("1", "2", "3"), se("3", "4", "5", "foo"))), p
   end
   
   def test_parse_multiline_statements_as_literal_expressions
@@ -42,7 +42,7 @@ class TestParser < Test::Unit::TestCase
   def test_parse_expr
     expr = '{4 + 5}'
     p = P.parse(expr)
-    assert_equal e(le("4", "+", "5")), p
+    assert_equal e(e(le("4", "+", "5"))), p
   end
   
   def test_parsing_a_nuke_node
@@ -129,11 +129,11 @@ class TestParser < Test::Unit::TestCase
   def test_one_node_parsing
     f = File.open(File.dirname(__FILE__) + "/test-data/one_node_with_one_param.txt")
     p = P.parse(f)
-    ref = e("SomeNode",
+    ref = e(e("SomeNode",
         le(
           e("foo", "bar")
         )
-    )
+    ))
     
     assert_equal ref, p
   end

data/tickly.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "tickly"
-  s.version = "0.0.8"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Julik Tarkhanov"]
-  s.date = "2013-03-15"
+  s.date = "2013-03-17"
   s.description = "Parses the subset of the TCL grammar needed for Nuke scripts"
   s.email = "me@julik.nl"
   s.extra_rdoc_files = [
@@ -24,6 +24,7 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "lib/tickly.rb",
+    "lib/tickly/curve.rb",
     "lib/tickly/evaluator.rb",
     "lib/tickly/node_extractor.rb",
     "lib/tickly/parser.rb",
@@ -38,6 +39,7 @@ Gem::Specification.new do |s|
     "test/test-data/three_nodes_and_roto.txt",
     "test/test-data/tracker_with_differing_gaps.nk",
     "test/test-data/tracker_with_repeating_gaps.nk",
+    "test/test_curve.rb",
     "test/test_evaluator.rb",
     "test/test_node_extractor.rb",
     "test/test_parser.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tickly
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-15 00:00:00.000000000 Z
+date: 2013-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bychar
@@ -122,6 +122,7 @@ files:
 - README.rdoc
 - Rakefile
 - lib/tickly.rb
+- lib/tickly/curve.rb
 - lib/tickly/evaluator.rb
 - lib/tickly/node_extractor.rb
 - lib/tickly/parser.rb
@@ -136,6 +137,7 @@ files:
 - test/test-data/three_nodes_and_roto.txt
 - test/test-data/tracker_with_differing_gaps.nk
 - test/test-data/tracker_with_repeating_gaps.nk
+- test/test_curve.rb
 - test/test_evaluator.rb
 - test/test_node_extractor.rb
 - test/test_parser.rb
@@ -156,7 +158,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3261881245436907150
+      hash: 748629881843892716
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: