tickly 2.1.0 → 2.1.2

data/Gemfile

@@ -6,7 +6,6 @@ gem 'bychar', '~> 2'
 # Include everything needed to run rake, tests, features, etc.
 group :development do
   gem "rake"
-  gem "shoulda", ">= 0"
   gem "rdoc", "~> 3.12"
   gem "jeweler", "~> 1.8.3"
   gem "ruby-prof"

data/README.rdoc

@@ -1,7 +1,11 @@
 = tickly
 
-A highly simplistic TCL parser and evaluator (primarily designed for parsing Nuke scripts). It structures
-the passed Nuke scripts into a TCL AST and return it. You can use some cheap tricks to discard the nodes you are not interested in.
+A highly simplistic TCL parser and evaluator (primarily designed for parsing Nuke scripts).
+It transforms the passed Nuke scripts into a TCL AST. 
+It also supports some cheap tricks to discard the nodes you are not interested in, since Nuke
+scripts easily grow into tens of megabytes.
+
+The AST format is extremely simple (nested arrays).
 
 == Plain parsing
 
@@ -25,14 +29,18 @@ will always return an Array of expressions, even if you only fed it one expressi
     # Expressions in square brackets
     p.parse '{exec cmd [fileName]}' #=> [[:c, "exec", "cmd", [:b, "fileName"]]]
 
-The AST is represented by simple arrays. An array is a TCL expression. An array with the :c symbol at the beginning
-element is an expression in curly braces. An array with the :b symbol at the beginning represents an expression with
-string interpolations in it. If you are curious, :c stands for "curlies" and :b for "brackets". All the other array
-elements are guaranteed to be strings.
+The AST is represented by simple arrays. Each TCL expression becomes an array. An array starting 
+with the :c symbol ("c" for "curlies") is a literal expression in curly braces ({}). An array with the
+:b symbol at the beginning is an expression with string interpolations (square brackets).
+All the other array elements are guaranteed to be strings.
+
+String literals are expanded to string array elements.
+
+    p.parse( '"a string with \"quote"') #=> [['a string with "quote']]
 
-Multiple expressions separated by ; or a newline will be accumulated as multiple arrays.
+Multiple expressions separated by semicolons or newlines will be accumulated as multiple arrays.
 
-Lots and lots of TCL features are not supported - remember that most Nuke scripts are machine-generated and they do not
+Lots and lots of TCL features are probably not supported - remember that most Nuke scripts are machine-generated and they do not
 use most of the esoteric language features.
 
 == Evaulating nodes in Nuke scripts
@@ -42,6 +50,7 @@ are actially arguments for a node constructor written out in TCL. Consider this
 hypothetic SomeNode in your script:
 
     SomeNode {
+      name SomeNode4
       someknob 15
       anotherknob 3
       animation {curve x1 12 45 67}
@@ -49,14 +58,17 @@ hypothetic SomeNode in your script:
       y_pos -10
     }
 
-and so on. You can use a NodeProcessor to capture these node constructors right as they are being parsed.
+and so on. You can use a +NodeProcessor+ to capture these node constructors right as they are being parsed.
+The advantage of this workflow is that the processor will discard all the nodes you don't need, saving time
+and memory.
 
-All the nodes you are not interested in will be discarded, which matters in terms of memory use.
+To match nodes you create Ruby classes matching the node classes by name. It doesn't matter if your
+custom node handler is inside a module since the processor will only use the last part of the name.
 
-To do it you need to create Ruby classes matching the node classes by name. For example, for that SomeNode
-of ours:
-
-    class SomeNode
+For example, to capture every +SomeNode+ in your script:
+    
+    # Remember, only the last part of the class name matters
+    class MyAwesomeDirtyScript::SomeNode
       attr_reader :knobs
       def initialize(string_keyed_knobs_hash)
         @knobs = string_keyed_knobs_hash
@@ -67,8 +79,9 @@ of ours:
     e = Tickly::NodeProcessor.new
     
     # Add the class
-    e.add_node_handler_class Blur
+    e.add_node_handler_class SomeNode
     
+    # Open the ginormous Nuke script
     file = File.open("/mnt/raid/nuke/scripts/HugeShot_123.nk")
     
     e.parse(file) do | every_some_node |
@@ -78,7 +91,8 @@ of ours:
       ...
     end
 
-If you are curious, this is how Tracksperanto parses various nodes containing tracking data:
+Of course you can capture multiple node classes. This is how Tracksperanto parses various
+nodes containing tracking data:
     
     parser = Tickly::NodeProcessor.new
     parser.add_node_handler_class(Tracker3)

data/lib/tickly/evaluator.rb

@@ -32,7 +32,7 @@ module Tickly
   #    end
   class Evaluator
     def initialize
-      @node_handlers = []
+      @node_handlers = {}
     end
     
     # Add a Class object that can instantiate node handlers. The last part of the class name
@@ -40,7 +40,7 @@ module Tickly
     # For example, to capture Tracker3 nodes a name like this will do:
     #     Whatever::YourModule::Better::Tracker3
     def add_node_handler_class(handler_class)
-      @node_handlers << handler_class
+      @node_handlers[class_name_without_modules(handler_class)] = handler_class
     end
     
     # Evaluates a single Nuke TCL command, and if it is a node constructor
@@ -50,7 +50,7 @@ module Tickly
     # (it's more of a pattern matcher really)
     def evaluate(expr)
       if will_capture?(expr)
-        handler_class = @node_handlers.find{|e| unconst_name(e) == expr[0]}
+        handler_class = @node_handlers[expr[0]]
         handler_arguments = expr[1]
         hash_of_args = {}
         # Use 1..-1 to skip the curly brace symbol
@@ -81,10 +81,10 @@ module Tickly
     end
     
     def has_handler?(expr)
-      @node_handlers.map{|handler_class| unconst_name(handler_class) }.include?(expr[0])
+      @node_handlers.has_key? expr[0]
     end
     
-    def unconst_name(some_module)
+    def class_name_without_modules(some_module)
       some_module.to_s.split('::').pop
     end
     

data/lib/tickly/node_processor.rb

@@ -24,7 +24,6 @@ module Tickly
   #    e.add_node_handler_class Blur
   #    e.parse(File.open("/path/to/script.nk")) do | blur_node |
   #      # do whatever you want to the node instance
-  #      end
   #    end
   class NodeProcessor
     def initialize
@@ -78,4 +77,4 @@ module Tickly
       return nil
     end
   end
-end
+end

data/lib/tickly/parser.rb

@@ -5,6 +5,10 @@ module Tickly
   # Simplistic, incomplete and most likely incorrect TCL parser
   class Parser
     
+    # Gets raised on invalid input
+    class Error < RuntimeError
+    end
+    
     # 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.
@@ -19,10 +23,10 @@ module Tickly
     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.wrap(bare_io)
+      reader = R.new(Bychar.wrap(bare_io))
       # 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)
+      parse_expr(reader, stop_char = nil, stack_depth = 0, multiple_expressions = true)
     end
     
     # Override this to remove any unneeded subexpressions.
@@ -37,13 +41,30 @@ module Tickly
     
     private
     
-    LAST_CHAR = -1..-1 # If we were 1.9 only we could use -1
     TERMINATORS = ["\n", ";"]
     ESC = 92.chr # Backslash (\)
+    QUOTES = %w( " ' )
+    
+    # TODO: this has to go into Bychar. We should not use exprs for flow control.
+    class R #:nodoc: :all
+      def initialize(bychar)
+        @bychar = bychar
+      end
+      
+      def read_one_char
+        begin
+          c = @bychar.read_one_char!
+        rescue Bychar::EOF
+          nil
+        end
+      end
+    end
     
     # Package the expressions, stack and buffer.
-    # We use a special flag to tell us whether we need multuple expressions
-    # or not, if not we just discard them
+    # We use a special flag to tell us whether we need multuple expressions.
+    # If we do, the expressions will be returned. If not, just the stack.
+    # Also, anything that remains on the stack will be put on the expressions
+    # list if multiple_expressions is true.
     def wrap_up(expressions, stack, buf, stack_depth, multiple_expressions)
       stack << buf if (buf.length > 0)
       return stack unless multiple_expressions
@@ -53,21 +74,35 @@ module Tickly
       return expressions
     end
     
+    # If the passed buf contains any bytes, put them on the stack and
+    # empty the buffer
+    def consume_remaining_buffer(stack, buf)
+      return if buf.length == 0
+      stack << buf.dup
+      buf.replace('')
+    end
+    
     # Parse from a passed IO object either until an unescaped stop_char is reached
     # 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, multiple_expressions = false)
+    def parse_expr(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
       
-      no_eof do
-        char = io.read_one_char!
+      loop do
+        char = io.read_one_char
         
-        if char == stop_char # Bail out of a subexpr
+        # Ignore carriage returns
+        next if char == "\r"
+        
+        if stop_char && char.nil?
+          raise Error, "IO ran out when parsing a subexpression (expected to end on #{stop_char.inspect})"
+        elsif char == stop_char # Bail out of a subexpr or bail out on nil
+          # TODO: default stop_char is nil, and this is also what gets returned from a depleted
+          # IO on IO#read(). We should do that in Bychar.
           # Handle any remaining subexpressions
           return wrap_up(expressions, stack, buf, stack_depth, multiple_expressions)
         elsif char == " " || char == "\n" # Space
@@ -75,68 +110,62 @@ module Tickly
             stack << buf
             buf = ''
           end
-          if TERMINATORS.include?(char) && stack.any? && !last_char_was_linebreak # Introduce a stack separator! This is a new line
-            stack << buf if buf.length > 0
-            # Immediately run this expression through the filter
+          if TERMINATORS.include?(char) && stack.any? # Introduce a stack separator! This is a new line
+            
+            # First get rid of the remaining buffer data
+            consume_remaining_buffer(stack, buf)
+            
+            # Since we now finished an expression and it is on the stack,
+            # we can run this expression through the filter
             filtered_expr = compact_subexpr(stack, stack_depth + 1)
-            stack = []
             
             # Only preserve the parsed expression if it's not nil
             expressions << filtered_expr unless filtered_expr.nil?
             
-            last_char_was_linebreak = true
+            # Reset the stack for the next expression
+            stack = []
+            
+            # Note that we will return multiple expressions instead of one
             multiple_expressions = true
-            #puts "Next expression! #{expressions.inspect} #{stack.inspect} #{buf.inspect}"
-          else
-            last_char_was_linebreak = false
           end
         elsif char == '[' # Opens a new string expression
-          stack << buf if (buf.length > 0)
-          stack << [:b] + sub_parse(io, ']', stack_depth + 1)
+          consume_remaining_buffer(stack, buf)
+          stack << [:b] + parse_expr(io, ']', stack_depth + 1)
         elsif char == '{' # Opens a new literal expression  
-          stack << buf if (buf.length > 0)
-          stack << [:c] + sub_parse(io, '}', stack_depth + 1)
-        elsif char == '"'
-          stack << buf if (buf.length > 0)
-          stack << parse_str(io, '"')
-        elsif char == "'"
-          stack << buf if (buf.length > 0)
-          stack << parse_str(io, "'")
+          consume_remaining_buffer(stack, buf)
+          stack << [:c] + parse_expr(io, '}', stack_depth + 1)
+        elsif QUOTES.include?(char) # String
+          consume_remaining_buffer(stack, buf)
+          stack << parse_str(io, char)
         else
           buf << char
         end
       end
       
-      return wrap_up(expressions, stack, buf, stack_depth, multiple_expressions)
-    end
-    
-    def chomp!(stack)
-      stack.delete_at(-1) if stack.any? && stack[-1].nil?
-    end
-    
-    def no_eof(&blk)
-      begin
-        loop(&blk)
-      rescue Bychar::EOF
-      end
+      raise Error, "Should never happen"
     end
     
-    def parse_str(io, stop_char)
+    # Parse a string literal, in single or double quotes.
+    def parse_str(io, stop_quote)
       buf = ''
-      no_eof do
-        c = io.read_one_char!
-        if c == stop_char && buf[LAST_CHAR] != ESC
-          return buf
-        elsif buf[LAST_CHAR] == ESC # Eat out the escape char
-          buf = buf[0..-2] # Trim the escape character at the end of the buffer
+      loop do
+        c = io.read_one_char
+        if c.nil?
+          raise Error, "The IO ran out before the end of a literal string"
+        elsif buf.length > 0 && last_char(buf) == ESC # If this char was escaped
+          # Trim the escape character at the end of the buffer
+          buf = buf[0..-2] 
           buf << c
+        elsif c == stop_quote
+          return buf
         else
           buf << c
         end
       end
-      
-      return buf
     end
     
+    def last_char(str)
+      RUBY_VERSION < '1.9' ? str[-1].chr : str[-1]
+    end
   end
 end

data/lib/tickly.rb

@@ -4,22 +4,5 @@ require File.dirname(__FILE__) + "/tickly/curve"
 require File.dirname(__FILE__) + "/tickly/node_processor"
 
 module Tickly
-  VERSION = '2.1.0'
-  
-  # Provides the methods for quickly emitting the expression arrays,
-  # is used in tests
-  module Emitter #:nodoc :all
-    def le(*elems)
-      [:c] + elems
-    end
-    
-    def e(*elems)
-      elems
-    end
-    
-    def se(*elems)
-      [:b] + elems
-    end
-  end
-  
+  VERSION = '2.1.2'
 end

data/test/helper.rb

@@ -8,11 +8,27 @@ rescue Bundler::BundlerError => e
   exit e.status_code
 end
 require 'test/unit'
-require 'shoulda'
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'tickly'
 
 class Test::Unit::TestCase
+  # Provides the methods for quickly emitting the expression arrays,
+  # is used in tests
+  module Emitter #:nodoc :all
+    def le(*elems)
+      e(*elems).unshift :c
+    end
+    
+    def e(*elems)
+      elems
+    end
+    
+    def se(*elems)
+      e(*elems).unshift :b
+    end
+  end
+  
+  include Emitter
 end