torkify 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.tags
+log/

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in torkify.gemspec
+gemspec
+gem 'rb-inotify'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jon Cairns
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# Torkify
+
+Torkify integrates with [tork][1], which is a solution for automating tests as you change your source files.
+
+Torkify hooks in to tork's remote events, and allows you to write ruby code that's called when particular events fire. This makes it easy for you to write code that triggers cool stuff when your tests pass or fail.
+
+## An example
+
+You define callbacks by creating an observer that defines certain methods. Here's an example that creates a system notification:
+
+```ruby
+# my_tork_notifier.rb
+require 'torkify'
+
+class SystemNotifier
+  def notify(text)
+    # Do a system call to fire a popup notification, e.g. `notify-send`
+  end
+
+  def on_pass(event)
+    notify "Test passed: #{event.file}"
+  end
+
+  def on_fail(event)
+    notify "Test failed: #{event.file}, log file #{event.log_file}"
+  end
+end
+
+listener = Torkify.listener
+listener.add_observer SystemNotifier.new
+listener.start
+```
+
+This connects to an existing tork process that's running in the current directory.
+
+## Usage
+
+Create a ruby script, load torkify and set up a new listener:
+
+```ruby
+# my_tork_notifier.rb
+
+require 'torkify'
+
+listener = Torkify.listener
+```
+
+This listener allows you to add observer objects which you create yourself:
+
+```ruby
+# my_tork_notifier.rb
+
+listener.add_observer MyObserver.new
+listener.start  # connect to tork and pass all events to the observer(s)
+```
+
+### Observer callback methods
+
+Your observer classes can define any number of the following methods:
+
+ * `on_startup`: when torkify starts
+ * `on_shutdown`: when torkify shuts down
+ * `on_test`: when a test is started
+ * `on_pass`: when a test passes
+ * `on_fail`: when a test fails
+ * `on_pass_now_fail`: when a previously passed test fails
+ * `on_fail_now_pass`: when a previously failed test passes
+ * `on_absorb`: when tork re-absorbs the environment
+
+Each method takes an optional event object as a parameter: this contains all the contextual information about that event. See **callback event objects** below for a complete list of accessible attributes on the events.
+
+### Options for starting torkify
+
+Calling `start()` on the listener will try and attach to a running tork process in the same directory as the script is run. This starts the process `tork-remote tork-engine` in the current directory. If you want to change the command that's called (e.g. if bundler is giving you grief), then you can pass that as the first parameter to start:
+
+```ruby
+# my_tork_notifier.rb
+
+listener.start 'bundle exec tork-remote tork-engine'  # Will use this command instead
+```
+
+If tork is running in a different directory, you can pass in a path as the second parameter:
+
+```ruby
+# my_tork_notifier.rb
+
+listener.start 'tork-remote tork-engine', '/home/user/project'
+```
+
+`start()` will assume that tork is running, and will exit if no tork process is found. If you want it to keep looping until tork starts, use `start_loop()`:
+
+```ruby
+# my_tork_notifier.rb
+
+listener.start_loop   # you can pass the same parameters as with start()
+```
+
+### Starting with tork
+
+You may not want to keep tork and torkify separate - for convenience, torkify allows you to start both at the same time. It forks torkify as a child process and runs tork in the parent, allowing you to interact with tork via STDIN but giving you the callbacks of torkify. Just use `start_with_tork()`:
+
+```ruby
+# my_tork_notifier.rb
+
+listener.start_with_tork 'bundle exec tork', 'default:logdir'   # Starts both tork and torkify
+```
+
+Both parameters are optional. The first is the command to execute tork, and the second is the `$TORK_CONFIGS` environment variable.
+
+### Multiple observers
+
+You can add multiple observers to your listener:
+
+```ruby
+require 'torkify'
+
+class FirstObserver
+  #...
+end
+
+class SecondObserver
+  #...
+end
+
+listener.Torkify.listener
+listener.add_observer FirstObserver.new
+listener.add_observer SecondObserver.new
+listener.start
+```
+
+### Callback event objects
+
+Here's an example observer, and the accessible data on the events provided in the callbacks:
+
+```ruby
+
+class MyObserver
+  def on_test(event)
+    event.type      #=> "test"
+    event.file      #=> "spec/example_spec.rb"
+    event.log_file  #=> "spec/example_spec.rb.log"
+    event.lines     #=> [10, 11, 12]
+    event.worker    #=> 0
+  end
+
+  def on_pass(event)
+    event.type      #=> "pass"
+    event.file      #=> "spec/example_spec.rb"
+    event.log_file  #=> "spec/example_spec.rb.log"
+    event.lines     #=> [10, 11, 12]
+    event.worker    #=> 0
+    event.exit_code #=> 0
+    event.pid       #=> 22813
+  end
+
+  def on_fail(event)
+    event.type      #=> "fail"
+    event.file      #=> "spec/example_spec.rb"
+    event.log_file  #=> "spec/example_spec.rb.log"
+    event.lines     #=> [10, 11, 12]
+    event.worker    #=> 0
+    event.exit_code #=> 0
+    event.pid       #=> 22813
+  end
+
+  # The event has an inner event, which is the same type of event
+  # that's passed to #on_fail()
+  def on_pass_now_fail(event)
+    event.type       #=> "pass_now_fail"
+    event.file       #=> "spec/example_spec.rb"
+    event.event.type #=> "fail"
+  end
+
+  # The event has an inner event, which is the same type of event
+  # that's passed to #on_pass()
+  def on_fail_now_pass(event)
+    event.type       #=> "fail_now_pass"
+    event.file       #=> "spec/example_spec.rb"
+    event.event.type #=> "pass"
+  end
+
+  def on_absorb(event)
+    event.type      #=> "absorb"
+  end
+
+  def on_startup(event)
+    event.type      #=> "startup"
+  end
+
+  def on_shutdown(event)
+    event.type      #=> "shutdown"
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'torkify'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install torkify
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+The guidelines are:
+
+ * The tests must pass (run python vdebugtests.py in the top directory of the plugin)
+ * Your commit messages should follow the rules outlined [here][2]
+
+The steps are:
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+[1]: https://github.com/sunaku/tork
+[2]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/torkify/conductor.rb

@@ -0,0 +1,33 @@
+require_relative 'events/event'
+require_relative 'event_parser'
+
+module Torkify
+
+  # Connect the socket reader and observers, and dispatch events.
+  class Conductor
+    attr_accessor :observers
+
+    # Create with a set of observers.
+    def initialize(observers)
+      @observers = observers
+    end
+
+    # Start reading from the reader, which is an IO-like object.
+    #
+    # Parse each line and dispatch it as an event object to all observers.
+    def start(reader)
+      dispatch Event.new 'startup'
+      parser = EventParser.new
+        reader.each_line do |line|
+          event = parser.parse line
+          dispatch event
+        end
+      dispatch Event.new 'shutdown'
+    end
+
+    protected
+    def dispatch(event)
+      @observers.dispatch(event)
+    end
+  end
+end

data/lib/torkify/event_parser.rb

@@ -0,0 +1,36 @@
+require 'json'
+require_relative 'events/event'
+require_relative 'events/test_event'
+require_relative 'events/pass_or_fail_event'
+require_relative 'events/status_change_event'
+
+module Torkify
+
+  # Parse raw strings passed by tork into event objects.
+  class EventParser
+
+    # Parse a raw string and return an object based on the event type.
+    #
+    # E.g. a raw string like:
+    # > '["test","spec/reader_spec.rb",[],"spec/reader_spec.rb.log",3]'
+    def parse(line)
+      raw = JSON.load line
+      event_from_data raw
+    end
+
+    protected
+    # Create an event object from the array of data.
+    def event_from_data(data)
+      case data.first
+      when 'test'
+        TestEvent.new(*data)
+      when /^(pass|fail)$/
+        PassOrFailEvent.new(*data)
+      when /^(pass_now_fail|fail_now_pass)$/
+        StatusChangeEvent.new(data[0], data[1], event_from_data(data[2]))
+      else
+        Event.new(*data)
+      end
+    end
+  end
+end

data/lib/torkify/events/event.rb

@@ -0,0 +1,20 @@
+require_relative 'event_message'
+
+module Torkify
+
+  # Event used for all events that have no associated data.
+  #
+  # Types:
+  #
+  #  - absorb
+  #  - shutdown
+  #  - startup
+  #  - anything else...
+  class Event < Struct.new(:type)
+    include EventMessage
+
+    def to_s
+      type
+    end
+  end
+end

data/lib/torkify/events/event_message.rb

@@ -0,0 +1,7 @@
+module Torkify
+  module EventMessage
+    def message
+      "on_#{type}".to_sym
+    end
+  end
+end

data/lib/torkify/events/pass_or_fail_event.rb

@@ -0,0 +1,25 @@
+require_relative 'event_message'
+
+module Torkify
+
+  # Event used for test passes or failures.
+  #
+  # Types:
+  #
+  #  - pass
+  #  - fail
+  class PassOrFailEvent < Struct.new(:type, :file, :lines, :log_file, :worker, :exit_code, :exit_info)
+    include EventMessage
+
+    # Get the PID from the exit info.
+    def pid
+      matched = exit_info.scan(/pid ([0-9]+)/).first
+      matched.first.to_i if matched
+    end
+
+    def to_s
+      s = "#{type.upcase} #{file}"
+      s += lines.any? ? " (lines #{lines.join(', ')})" : ''
+    end
+  end
+end

data/lib/torkify/events/status_change_event.rb

@@ -0,0 +1,20 @@
+require_relative 'event_message'
+
+module Torkify
+
+  # Event used for changes in test status.
+  #
+  # Types:
+  #
+  #  - pass_now_fail
+  #  - fail_now_pass
+  #
+  # Includes the actual fail/pass event as a separate object.
+  class StatusChangeEvent < Struct.new(:type, :file, :event)
+    include EventMessage
+
+    def to_s
+      "#{type.upcase.gsub('_',' ')} #{file}"
+    end
+  end
+end

data/lib/torkify/events/test_event.rb

@@ -0,0 +1,15 @@
+require_relative 'event_message'
+
+module Torkify
+  # Event used when a test is started.
+  #
+  # This is currently only one type: 'test'
+  class TestEvent < Struct.new(:type, :file, :lines, :log_file, :worker)
+    include EventMessage
+
+    def to_s
+      s = "#{type.upcase} #{file}"
+      s += lines.any? ? " (lines #{lines.join(', ')})" : ''
+    end
+  end
+end

data/lib/torkify/exceptions.rb

@@ -0,0 +1,5 @@
+module Torkify
+  # Used when there's a failure connecting to a tork process.
+  class TorkError < StandardError
+  end
+end

data/lib/torkify/listener.rb

@@ -0,0 +1,91 @@
+require_relative 'conductor'
+require_relative 'observer_set'
+require_relative 'reader'
+require_relative 'exceptions'
+
+module Torkify
+  class Listener
+    # Create a torkify listener with optional command and directory specified.
+    #
+    # The command is what's used to start the tork remote engine. The
+    # directory is where the command will be executed.
+    def initialize(command = 'tork-remote tork-engine', dir = Dir.pwd)
+      @command = command
+      @dir = dir
+      @conductor = Conductor.new ObserverSet.new
+    end
+
+    # Add an observer object to be notified of tork events.
+    #
+    # The object will be notified of events if it contains the following
+    # methods:
+    #
+    #  - on_startup(event)       - when torkify starts
+    #  - on_shutdown(event)      - when torkify shuts down
+    #  - on_test(event)          - when a test is started
+    #  - on_pass(event)          - when a test passes
+    #  - on_fail(event)          - when a test fails
+    #  - on_fail_now_pass(event) - when a previously failed test passes
+    #  - on_pass_now_fail(event) - when a previously passed test fails
+    #  - on_absorb(event)        - when tork reabsorbs overhead
+    #
+    # It doesn't have to inherit from a particular type, just define the
+    # method. The argument is optional, and in each case it gives an event.
+    def add_observer(observer)
+      @conductor.observers << observer
+      self
+    end
+
+    # Start the torkify listener and dispatch events to observers.
+    #
+    # This runs once, and connects to an existing tork process. If tork
+    # stops running then torkify will shut down.
+    #
+    # For continuous listening use #start_loop() instead.
+    #
+    # To start tork as well, use #start_with_tork().
+    def start
+      reader = Reader.new(@command, @dir)
+      Torkify.logger.info { 'Started torkify listener' }
+      @conductor.start reader
+      Torkify.logger.info { 'Stopping torkify' }
+      self
+    rescue Torkify::TorkError
+      Torkify.logger.info { "Tork is not running" }
+      self
+    end
+
+    # Start the torkify listener and loop until it connects to a tork process.
+    #
+    # If the tork process stops, it will keep looping until another starts.
+    #
+    # Calls #start().
+    def start_loop
+      loop do
+        sleep 2
+        start
+      end
+    rescue => e
+      Torkify.logger.error { e }
+    end
+
+    # Start the torkify listener and tork itself.
+    #
+    # It forks the current process and runs torkify as the child. It then
+    # runs tork as the main process, allowing for stdin to be passed to tork.
+    #
+    # Calls #start_loop().
+    #
+    # The command to run tork can be passed as an argument, and the
+    # TORK_CONFIGS environment variable can be passed as the second argument.
+    def start_with_tork(command = 'tork', tork_env = 'default')
+      if fork
+        start_loop
+      else
+        # Run tork in main process to keep stdin
+        Torkify.logger.info { "Starting tork" }
+        exec({'TORK_CONFIGS' => tork_env}, command)
+      end
+    end
+  end
+end

data/lib/torkify/observer_set.rb

@@ -0,0 +1,62 @@
+require 'set'
+
+module Torkify
+  # Wrapper around a Set class, that adds a dispatch method.
+  #
+  # Dispatch sends an event that calls a method on all observers.
+  class ObserverSet
+    def initialize(set = Set.new)
+      @set = set
+    end
+
+    # Call a method on all observers, depending on the event type.
+    #
+    # The method is the event type prefixed with "on_". E.g. 'test' would be
+    # 'on_test'.
+    def dispatch(event)
+      Torkify.logger.debug event.to_s
+      @set.each do |observer|
+        dispatch_each observer, event.message, event
+      end
+    end
+
+    # Don't return a Set, return an ObserverSet.
+    def |(enum)
+      self.class.new(@set | enum)
+    end
+
+    def method_missing(method, *args, &blk)
+      @set.send method, *args, &blk
+    end
+
+    def respond_to?(name, include_private = false)
+      @set.respond_to? name, include_private
+    end
+
+    alias :+ :|
+    alias :union :|
+
+    private
+    # Send the messages to a given observer, with the event object.
+    def dispatch_each(observer, message, event)
+      method = observer.method(message)
+      observer.send message, *method_args(method, event)
+    rescue NameError
+      Torkify.logger.warn { "No method #{message} defined on #{observer.inspect}" }
+    rescue => e
+      Torkify.logger.error { "Caught exception from #{observer} during ##{message}: #{e}" }
+    end
+
+    # Determine whether to include the event in the arguments.
+    #
+    # The arity of the obsever's method is checked to see whether an
+    # argument is received or not.
+    def method_args(method, event)
+      dispatch_args = []
+      unless method.arity === 0
+        dispatch_args << event
+      end
+      dispatch_args
+    end
+  end
+end

data/lib/torkify/reader.rb

@@ -0,0 +1,35 @@
+require 'open3'
+require_relative 'exceptions'
+
+module Torkify
+  class Reader
+    # Open the tork command and initialize the streams.
+    #
+    # STDOUT is kept as the underlying stream, and this class can be used as
+    # an IO-like object on STDOUT.
+    #
+    # A TorkError is raised if the command fails, and its message is whatever
+    # has been written to the command's STDERR stream.
+    def initialize(command = 'tork-remote tork-engine', run_in_dir = Dir.pwd)
+      Dir.chdir(run_in_dir) do
+        _, @io, stderr, _ = Open3.popen3 command
+
+        if @io.eof?
+          raise TorkError, stderr.read.strip
+        end
+      end
+    end
+
+    # Pass all unknown methods straight to the underlying IO object.
+    #
+    # This allows this class to be used in an IO like way.
+    def method_missing(method, *args, &blk)
+      @io.send method, *args, &blk
+    end
+
+    # Allow respond_to? to work with method_missing.
+    def respond_to?(method, include_private = false)
+      @io.respond_to? method, include_private
+    end
+  end
+end

data/lib/torkify/version.rb

@@ -0,0 +1,3 @@
+module Torkify
+  VERSION = "0.0.1"
+end

data/lib/torkify.rb

@@ -0,0 +1,40 @@
+require "torkify/version"
+
+# Listen to tork events and execute ruby code when they happen.
+#
+# E.g.
+#
+#   listener = Torkify.listener
+#   class Observer
+#     def on_pass(event)
+#       puts event.to_s
+#     end
+#   end
+#   listener.add_observer Observer.new
+#   listener.start
+#   # or listener.start_loop
+#   # or listener.start_with_tork
+module Torkify
+
+  # Create a listener object and load all required files.
+  def self.listener(*args)
+    require 'torkify/listener'
+    Listener.new(*args)
+  end
+
+  # Create a logger object, or retrieve the existing logger.
+  #
+  # Uses Log4r.
+  def self.logger
+    require 'log4r'
+    include Log4r
+
+    log = Logger['torkify']
+    unless log
+      log = Logger.new 'torkify'
+      log.outputters = Outputter.stdout
+      log.level = INFO
+    end
+    log
+  end
+end