tickly 0.0.4 → 0.0.5

data/Gemfile

@@ -3,6 +3,8 @@ source "http://rubygems.org"
 # Example:
 #   gem "activesupport", ">= 2.3.5"
 
+gem "bychar", "~> 1.0"
+
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do

data/README.rdoc

@@ -1,6 +1,69 @@
 = tickly
 
-A highly simplistic TCL parser and evaluator (primarily designed for parsing Nuke scripts)
+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.
+
+== Parsing
+
+Create a Parser object and pass TCL expressions/scripts to it. You can pass IO obejcts or strings. For example:
+    
+    p = Tickly::Parser.new
+    
+    # One expression
+    p.parse '2' #=> ["2"]
+    
+    # TCL command
+    p.parse "tail $list" #=> ["tail", "$list"]
+    
+    # Multiple expressions
+    p.parse "2\n2" #=> [["2", "2"]]
+    
+    # Expressions in curly braces   
+    p.parse '{2 2}' #=> [[:c, "2", "2"]]
+    
+    # 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.
+
+Multiple expressions separated by ; or a newline 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
+use most of the esoteric language features.
+
+== Evaulating
+
+Nuke uses the following syntax for it's nodes:
+
+    SomeNode {
+      someknob 15
+      anotherknob 3
+      andanother {curve x1 12 45 67}
+    }
+
+and so on. You can use a simple Evaluator object to run through the nodes returned by the parser. To set up
+the evaulation you need to create classes matching the node classes by name. For example, a Blur class:
+
+    class Blur
+      def initialize(string_keyed_knobs_hash)
+      end
+    end
+    
+    e = Tickly::Evaluator.new
+    e.add_node_handler_class Blur
+    
+    some_script_expressions = Tickly::Parser.new.parse(File.open("/mnt/raid/nuke/scripts/HugeShot_123.nk"))
+    
+    some_script_expressions.each do | expression_in_ast |
+      # Everytime a Blur node is found in the script it will be instantiated,
+      # and the knobs of the node will be passed to the constructor that you define
+      e.evaluate(expression_in_ast) do | blur_node |
+        # Now a Blur node instance is all yours
+      end
+    end
 
 == Contributing to tickly
  

data/lib/tickly.rb

@@ -4,9 +4,10 @@ require File.dirname(__FILE__) + "/tickly/evaluator"
 require 'forwardable'
 
 module Tickly
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
   
-  # Provides the methods for quickly emitting the LiteralExpr and StringExpr objects
+  # Provides the methods for quickly emitting the expression arrays,
+  # is used in tests
   module Emitter
     def le(*elems)
       [:c] + elems
@@ -21,11 +22,15 @@ 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

data/lib/tickly/evaluator.rb

@@ -9,10 +9,19 @@ module Tickly
       @node_handlers = []
     end
     
+    # Add a Class object that can instantiate node handlers. The last part of the class name
+    # has to match the name of the Nuke node that you want to capture.
+    # 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
     end
     
+    # Evaluates a single Nuke TCL command, and if it is a node constructor
+    # and a class with a corresponding name has been added using add_node_handler_class
+    # the class will be instantiated and yielded to the block. The instance will also be returned
+    # at the end of the method. This method evaluates one expression at a time
+    # (it's more of a pattern matcher really)
     def evaluate(expr)
       if multiple_atoms?(expr) && has_subcommand?(expr) && has_handler?(expr) 
         handler_class = @node_handlers.find{|e| unconst_name(e) == expr[0]}
@@ -25,10 +34,16 @@ module Tickly
         end
         
         # Instantiate the handler with the options
-        handler_class.new(hash_of_args)
+        handler_instance = handler_class.new(hash_of_args)
+        
+        # Both return and yield it
+        yield handler_instance if block_given?
+        handler_instance
       end
     end
     
+    private
+    
     def multiple_atoms?(expr)
       expr.length > 1
     end

data/lib/tickly/parser.rb

@@ -1,23 +1,32 @@
 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 (nested StringExpr or LiteralExpr objects).
+    # 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.
     def parse(io_or_str)
-      io = io_or_str.respond_to?(:read) ? io_or_str : StringIO.new(io_or_str)
-      sub_parse(io)
+      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)
     end
     
-    # Override this to remove any unneeded subexpressions
+    # Override this to remove any unneeded subexpressions Modify the passed expr
+    # array in-place.
     def expand_subexpr!(expr, at_depth)
     end
     
     private
     
     LAST_CHAR = -1..-1 # If we were 1.9 only we could use -1
+    TERMINATORS = ["\n", ";"]
+    ESC = 92.chr # Backslash (\)
     
     # 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
@@ -29,7 +38,7 @@ module Tickly
       buf = ''
       last_char_was_linebreak = false
       until io.eof?
-        char = io.read(1)
+        char = io.read_one_byte
         
         if buf[LAST_CHAR] != ESC
           if char == stop_char # Bail out of a subexpr
@@ -42,7 +51,7 @@ module Tickly
               stack << buf
               buf = ''
             end
-            if char == "\n" # Introduce a stack separator! This is a new line
+            if TERMINATORS.include?(char) # Introduce a stack separator! This is a new line
               if stack.any? && !last_char_was_linebreak
                 last_char_was_linebreak = true
                 stack = handle_expr_terminator(stack, stack_depth)
@@ -87,8 +96,6 @@ module Tickly
       return stack
     end
     
-    ESC = 92.chr # Backslash (\)
-    
     def chomp!(stack)
       stack.delete_at(-1) if stack.any? && stack[-1].nil?
     end
@@ -118,7 +125,7 @@ module Tickly
     def parse_str(io, stop_char)
       buf = ''
       until io.eof?
-        c = io.read(1)
+        c = io.read_one_byte
         if c == stop_char && buf[LAST_CHAR] != ESC
           return buf
         elsif buf[LAST_CHAR] == ESC # Eat out the escape char

data/test/test_evaluator.rb

@@ -39,5 +39,22 @@ class TestEvaluator < Test::Unit::TestCase
     ref_o = {"foo" => "bar", "baz" => "bad"}
     assert_equal ref_o, node.options
   end
+  
+  class TargetError < RuntimeError
+  end
+  
+  def test_yields_the_handler_instance
+    stack = e("SomeNode", le(e("foo", "bar"), e("baz", "bad")))
+    e = Tickly::Evaluator.new
+    e.add_node_handler_class(SomeNode)
+    ref_o = {"foo" => "bar", "baz" => "bad"}
+    
+    assert_raise(TargetError) do
+      e.evaluate(stack) do | some_node |
+        assert_kind_of SomeNode, some_node
+        raise TargetError
+      end
+    end
+  end
 
 end

data/tickly.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "tickly"
-  s.version = "0.0.4"
+  s.version = "0.0.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Julik Tarkhanov"]
-  s.date = "2013-03-12"
+  s.date = "2013-03-15"
   s.description = "Parses the subset of the TCL grammar needed for Nuke scripts"
   s.email = "me@julik.nl"
   s.extra_rdoc_files = [
@@ -52,17 +52,20 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<bychar>, ["~> 1.0"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<bundler>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
     else
+      s.add_dependency(%q<bychar>, ["~> 1.0"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<bundler>, [">= 0"])
       s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
     end
   else
+    s.add_dependency(%q<bychar>, ["~> 1.0"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<bundler>, [">= 0"])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tickly
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-12 00:00:00.000000000 Z
+date: 2013-03-15 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bychar
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: shoulda
   requirement: !ruby/object:Gem::Requirement
@@ -122,7 +138,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2196296843243875248
+      hash: -4354134908046767929
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: