emory 0.1.0

data/.gitignore

@@ -0,0 +1,26 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea/
+.project
+emory.log
+
+## MAC OS
+.DS_Store
+.Trashes
+.com.apple.timemachine.supported
+.fseventsd

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emory.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tacit Knowledge
+
+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,193 @@
+Emory
+=====
+
+The Emory gem listens to file modifications and runs an action against it (for example, upload to a remote location).
+
+Contents
+--------
+
+* [Installation](#installation)
+* [Usage](#usage)
+* [Emory configuration DSL](#emory-dsl)
+  * [handler](#emory-dsl-handler)
+  * [teleport](#emory-dsl-teleport)
+* [Contributing](#contributing)
+* [Authors](#authors)
+
+<a name="installation" />
+Installation
+------------
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'emory'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install emory
+```
+
+<a name="usage" />
+Usage
+-----
+
+Emory is run from the command line. Please open your terminal and go to your project's work directory.
+
+There you would need to create Emory config file `.emory` which in fact is nothing more than regular
+Ruby code wrapped in gem's configuration DSL.
+
+Example configuration:
+
+```ruby
+require 'emory/handlers/stdout_handler'
+
+handler do
+  name :listener
+  implementation Emory::Handlers::StdoutHandler
+  events :all
+end
+
+teleport do
+  path '~/_emory-test/'
+  handler :listener
+  ignore %r{ignored/}
+  filter /\.txt$/
+end
+```
+
+The gem supplies an executable file which scans for the configuration file in current directory
+(and up the path if not found), configures itself and launches the process. If you need to terminate
+execution then proceed like your operating system allows you to (Ctrl-C, for example).
+
+```bash
+$ emory
+[2012-05-31 12:08:23] INFO  Emory::ConfigurationFile: Found config file: /Users/xxx/.emory
+[2012-05-31 12:08:23] INFO  Emory::Runner: Watching directory: /Users/xxx/_emory-test
+```
+
+Emory outputs some information into the console where it was launched from. However if you would
+like to consult more detailed information on what it's doing then feel free to supply `-d` or
+`--debug` when launching it like in this example:
+
+```bash
+$ emory --debug
+[2012-05-31 12:08:29] DEBUG Emory::Runner: Looking for the configuration file
+[2012-05-31 12:08:29] DEBUG Emory::ConfigurationFile: Examining directory: /Users/xxx/Projects
+[2012-05-31 12:08:29] DEBUG Emory::ConfigurationFile: Examining directory: /Users/xxx
+[2012-05-31 12:08:29] INFO  Emory::ConfigurationFile: Found config file: /Users/xxx/.emory
+[2012-05-31 12:08:29] DEBUG Emory::Runner: Reading configuration file contents
+[2012-05-31 12:08:29] DEBUG Emory::Runner: Evaluating configuration file contents:
+<<< the rest of the output is ommitted >>>
+```
+
+<a name="emory-dsl" />
+Emory configuration DSL
+-----------------------
+
+The Emory configuration DSL is evaluated as plain Ruby, so you can use normal Ruby code in your
+`.emory` file. Emory itself provides the following DSL methods that can be used for configuration:
+
+<a name="emory-dsl-handler" />
+### handler
+
+A handler in Emory is an entity which knows how to react on file system modification events.
+By default only two are provided:
+
+- `Emory::Handlers::AbstractHandler` - defines common interface for other handlers to implement
+- `Emory::Handlers::StdoutHandler` - spits out some information on what/how changed to the standard output
+
+A handler can be configured with 3 mandatory and 1 optional parameter:
+
+- mandatory
+    - name - defines a name for the handler so that it could be used in other parts of the configuration
+    - implementation - name of the specific class that conforms to `Emory::Handlers::AbstractHandler`'s interface
+    - events - a comma separated list of events the handler should react to (**:added**,
+    **:modified**, **:removed**) while ignoring the ones not mentioned. There's also an **:all**
+    shortcut to indicate all events without explicitly writing them.
+- optional
+    - options - a hash of optional data that will be passed on during handler's construction. Please
+    note that the handler's class needs to know how to treat these otherwise it's a no-op. For
+    example, `Emory::Handlers::StdoutHandler` does not know how to deal with the options so it would
+    just ignore them.
+
+Some examples of defining handlers
+
+```ruby
+require 'emory/handlers/stdout_handler'
+require 'some_company/integration/system_x_handler'
+
+handler do
+  name :stdout_handler
+  implementation Emory::Handlers::StdoutHandler
+  events :added, :removed
+end
+
+handler do
+  name :integration_handler
+  implementation SomeCompany::Integration::SystemXHandler
+  events :modified
+  options host: 'host1.othercompany.com', port: 12345, username: 'bozo', password: 'p@ssw0rd'
+  # or the arrows syntax in Ruby 1.8
+  # options :host => 'host1.othercompany.com', :port => 12345, :username => 'bozo', :password => 'p@ssw0rd'
+end
+```
+
+<a name="emory-dsl-teleport" />
+### teleport
+
+A teleport in Emory is an entity that knows that it needs to monitor some path (including sub-directories)
+and notify the linked handler if something interesting happens. A teleport can be configured with
+2 mandatory and 2 optional parameters:
+
+- mandatory
+    - path - the path to monitor (including its sub-directories). Can be either absolute or relative
+    to the location of the configuration file (`.emory`).
+    - handler - the handler to invoke/notify when the filesystem events occur in the path supplied above
+- optional
+    - ignore - the regex patterns that need to be ignored by the teleport
+    - filter - the regex patterns that filter out unwanted monitoring events
+
+An example teleport definition:
+
+```ruby
+# Will monitor file system events starting under <config_location>/ftp/incoming/x/ directory,
+# but will ignore paths containing reconciled/ and pending/ directories, and additionaly will
+# apply only to .txt files. Once events are identified will notify the handler named :integration_handler.
+teleport do
+  path 'ftp/incoming/x'
+  handler :integration_handler
+  ignore %r{reconciled/ pending/}
+  filter /\.txt$/
+end
+```
+
+<a name="contributing" />
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+<a name="authors" />
+Authors
+-------
+
+* [Vladislav Gangan](https://github.com/vgangan)
+
+Contributors
+------------
+
+* [Scott Askew](https://github.com/scottfromsf)
+* [Ion Lenta](https://github.com/noi)

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/test*.rb']
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+desc "Run rspec tests"
+task :default => :spec

data/bin/emory

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'logging'
+require 'emory/runner'
+require 'emory/version'
+
+options = {}
+OptionParser.new do |opts|
+  options[:log_level] = :info
+  opts.on('-d', '--debug', "Display debug output") do
+    options[:log_level] = :debug
+  end
+  opts.on('-v', '--version', 'Display version information') do
+    puts "Emory version #{Emory::VERSION}"
+    exit
+  end
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+end.parse!
+
+logging_lines_colors = {debug: :green, info: :light_green, warn: :yellow, error: :red, fatal: [:white, :on_red]}
+Logging.color_scheme('bright', lines: logging_lines_colors)
+
+logging_layouts_pattern = Logging.layouts.pattern(color_scheme: 'bright', pattern: '[%d] %-5l %c: %m\n')
+Logging.appenders.stdout('stdout', layout: logging_layouts_pattern, level: options[:log_level])
+
+Logging.logger.root.add_appenders('stdout')
+
+Emory::Runner.start

data/emory.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'emory/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'emory'
+  s.version       = Emory::VERSION
+  s.platform      = Gem::Platform::RUBY
+  s.authors       = ['Scott Askew', 'Vladislav Gangan', 'Ion Lenta']
+  s.email         = ['scott@tacitknowledge.com', 'vgangan@tacitknowledge.com', 'ilenta@tacitknowledge.com']
+  s.homepage      = 'https://github.com/tacitknowledge/emory'
+  s.summary       = 'Invokes a configured action when something interesting happens to a monitored file'
+  s.description   = 'The Emory gem listens to file modifications and runs an action against it (for example, upload to a remote location)'
+
+  s.files         = `git ls-files`.split($\)
+  s.executables   = %w(emory)
+  s.test_files    = Dir.glob("{spec,test}/**/*.rb")
+  s.require_paths = ["lib"]
+  
+  s.add_development_dependency 'rspec', '~> 2.10'
+  s.add_development_dependency 'simplecov', '~> 0.6.2'
+  s.add_development_dependency 'rake'
+
+  s.add_runtime_dependency 'logging'
+  s.add_runtime_dependency 'listen'
+end

data/examples/simple-stdout/.emory

@@ -0,0 +1,15 @@
+require 'emory/handlers/stdout_handler'
+
+# Define a handler emits any file add/modify/delete in ./src to STDOUT.
+handler do
+  name :stdout
+  implementation Emory::Handlers::StdoutHandler
+  events :all
+end
+
+# Map ./src to the handler defined above. Note that the 'path' is relative
+# to the location .emory (i.e. this file)
+teleport do
+  path 'src'
+  handler :stdout
+end

data/examples/simple-stdout/.gitignore

@@ -0,0 +1 @@
+src/*

data/lib/emory/configuration_file.rb

@@ -0,0 +1,29 @@
+require 'pathname'
+
+module Emory
+
+  class EmoryConfigurationFileNotFoundException < Exception; end
+
+  class ConfigurationFile
+
+    LOGGER = Logging.logger[self]
+    CONFIG_FILE_NAME = ".emory"
+
+    class << self
+
+      def locate
+        Pathname.new(Dir.pwd).ascend do |dir|
+          LOGGER.debug "Examining directory: #{dir}"
+          config_file = File.join(dir, CONFIG_FILE_NAME)
+          next unless File.exists?(config_file)
+          LOGGER.info "Found config file: #{config_file}"
+          return config_file
+        end
+
+        raise EmoryConfigurationFileNotFoundException, 'Configuration file (.emory) was not found'
+      end
+    end
+
+  end
+
+end

data/lib/emory/dsl/dsl.rb

@@ -0,0 +1,54 @@
+require 'emory/teleport_config'
+require 'emory/dsl/handler_builder'
+require 'emory/dsl/teleport_config_builder'
+
+module Emory
+  module DSL
+
+    class EmoryMisconfigurationException < Exception; end
+    class DuplicateHandlerNameException < Exception; end
+
+    class Dsl
+
+      LOGGER = Logging.logger[self]
+
+      class << self
+        def instance_eval_emoryfile(contents, config_path)
+          config = new
+          config.instance_eval(contents, config_path, 1)
+          config.handlers.freeze
+          config.teleports.freeze
+          config
+        rescue
+          LOGGER.error("Incorrect contents of .emory file, original error is:\n#{ $! }")
+          raise EmoryMisconfigurationException, 'Incorrect contents of .emory file'
+        end
+      end
+
+      def teleport(&block)
+        teleport_builder = TeleportConfigBuilder.new(handlers, &block)
+        teleport = teleport_builder.build
+        teleports << teleport
+        LOGGER.debug("Processed and added #{teleport} to the list: #{teleports}")
+      end
+
+      def handler(&block)
+        handler_builder = HandlerBuilder.new(&block)
+        handler = handler_builder.build
+        raise DuplicateHandlerNameException, "The handler name ':#{handler.name}' is defined more than once" if handlers.include?(handler.name)
+        handlers[handler.name] = handler
+        LOGGER.debug("Processed and added ':#{handler.name}' to the list: #{handlers}")
+      end
+
+      def handlers
+        @handlers ||= {}
+      end
+
+      def teleports
+        @teleports ||= []
+      end
+
+    end
+
+  end
+end

data/lib/emory/dsl/handler_builder.rb

@@ -0,0 +1,78 @@
+module Emory
+  module DSL
+
+    class HandlerConfigurationBlockMustBeSuppliedException < Exception; end
+    class HandlerNameMustBeSuppliedException < Exception; end
+    class HandlerImplementationMustBeSuppliedException < Exception; end
+    class HandlerActionAllMustBeSingletonException < Exception; end
+    class HandlerActionMustBeSuppliedException < Exception; end
+    class HandlerActionUnsupportedException < Exception; end
+
+    class HandlerBuilder
+
+      LOGGER = Logging.logger[self]
+      HANDLER_ACTION_ALL = :all
+      ALLOWED_HANDLER_ACTIONS = [HANDLER_ACTION_ALL, :added, :modified, :removed]
+
+      def initialize(&block)
+        LOGGER.debug('Initializing a new handler builder')
+        raise HandlerConfigurationBlockMustBeSuppliedException, "The configuration block with handler settings must be supplied" unless block_given?
+        @block = block
+        @options = {}
+      end
+
+      def build
+        LOGGER.debug('Evaluating handler configuration')
+        instance_eval &@block
+
+        raise HandlerNameMustBeSuppliedException, "The handler name must be supplied in its configuration" if @name.nil?
+        raise HandlerImplementationMustBeSuppliedException, "The handler implementation must be supplied in its configuration" if @implementation.nil?
+
+        LOGGER.debug('Creating a new handler instance')
+        handler = @implementation.new(@name, @options)
+
+        raise HandlerActionMustBeSuppliedException, "At least one handler action needs to be supplied" if @events.nil?
+        if @events.first != HANDLER_ACTION_ALL
+          handler.instance_eval { undef :added } unless @events.include?(:added)
+          handler.instance_eval { undef :modified } unless @events.include?(:modified)
+          handler.instance_eval { undef :removed } unless @events.include?(:removed)
+        end
+
+        handler
+      end
+
+      private
+
+      def name(name)
+        LOGGER.debug('Setting handler\'s name')
+        @name = name
+      end
+
+      def implementation(impl)
+        LOGGER.debug('Setting handler\'s implementation')
+        @implementation = impl
+      end
+
+      def options(opts)
+        LOGGER.debug('Setting handler\'s options')
+        @options = opts
+      end
+
+      def events(*actions)
+        LOGGER.debug('Setting handler\'s events')
+        uniq_actions = actions.uniq
+
+        raise HandlerActionMustBeSuppliedException, "At least one handler action needs to be supplied" if actions.empty?
+        raise HandlerActionAllMustBeSingletonException, "The handler action ':#{HANDLER_ACTION_ALL}' cannot be mixed with other types" if uniq_actions.include?(HANDLER_ACTION_ALL) and uniq_actions.size > 1
+        uniq_actions.each do |action|
+          raise HandlerActionUnsupportedException,
+                "The action ':#{action}' is unsupported. Supported actions are #{ALLOWED_HANDLER_ACTIONS}." unless ALLOWED_HANDLER_ACTIONS.include?(action)
+        end
+
+        @events = uniq_actions
+      end
+
+    end
+
+  end
+end

data/lib/emory/dsl/teleport_config_builder.rb

@@ -0,0 +1,62 @@
+require 'emory/teleport_config'
+
+module Emory
+  module DSL
+
+    class TeleportConfigurationBlockMustBeSuppliedException < Exception; end
+    class UndefinedTeleportHandlerException < Exception; end
+    class HandlerReferenceMustBeSuppliedException < Exception; end
+    class WatchedPathMustBeSuppliedException < Exception; end
+
+    class TeleportConfigBuilder
+
+      LOGGER = Logging.logger[self]
+
+      def initialize(handlers, &block)
+        LOGGER.debug('Initializing a new teleport builder')
+        raise TeleportConfigurationBlockMustBeSuppliedException, "The configuration block with teleport settings must be supplied" unless block_given?
+
+        @block = block
+        @available_handlers = handlers
+
+        LOGGER.debug('Creating a new teleport config instance')
+        @teleport_config = TeleportConfig.new
+      end
+
+      def build
+        LOGGER.debug('Evaluating teleport configuration')
+        instance_eval &@block
+
+        raise HandlerReferenceMustBeSuppliedException, "A reference to an existing handler must be supplied in teleport configuration" if @teleport_config.handler.nil?
+        raise WatchedPathMustBeSuppliedException, "A watched path must be supplied in teleport configuration" if @teleport_config.watched_path.nil?
+
+        @teleport_config
+      end
+
+      private
+
+      def path(path)
+        LOGGER.debug('Setting teleport\'s watched path')
+        @teleport_config.watched_path = path
+      end
+
+      def handler(handler_name)
+        LOGGER.debug('Setting teleport\'s handler')
+        raise UndefinedTeleportHandlerException, "The handler ':#{handler_name}' wired to teleport could not be found" unless @available_handlers.include?(handler_name)
+        @teleport_config.handler = @available_handlers[handler_name]
+      end
+
+      def ignore(ignore)
+        LOGGER.debug('Setting teleport\'s ignore expression')
+        @teleport_config.ignore = ignore
+      end
+
+      def filter(filter)
+        LOGGER.debug('Setting teleport\'s filter expression')
+        @teleport_config.filter = filter
+      end
+
+    end
+
+  end
+end

data/lib/emory/handlers/abstract_handler.rb

@@ -0,0 +1,35 @@
+module Emory
+  module Handlers
+
+    class AbstractHandler
+
+      attr_reader :name
+
+      def initialize(name, options = {})
+        self.name = name
+      end
+
+      def added(file_path = nil)
+        raise_not_implemented_error(self.class, __method__)
+      end
+
+      def modified(file_path = nil)
+        raise_not_implemented_error(self.class, __method__)
+      end
+
+      def removed(file_path = nil)
+        raise_not_implemented_error(self.class, __method__)
+      end
+
+      private
+
+      attr_writer :name
+
+      def raise_not_implemented_error(class_name, method_name)
+        raise NotImplementedError, "This method is not implemented: #{class_name}##{method_name}"
+      end
+
+    end
+
+  end
+end

data/lib/emory/handlers/stdout_handler.rb

@@ -0,0 +1,33 @@
+require 'emory/handlers/abstract_handler'
+
+module Emory
+  module Handlers
+
+    class StdoutHandler < AbstractHandler
+
+      def initialize(name, options = {})
+        super
+      end
+
+      def added(file_path)
+        report_file_path_action(file_path, __method__)
+      end
+
+      def modified(file_path)
+        report_file_path_action(file_path, __method__)
+      end
+
+      def removed(file_path)
+        report_file_path_action(file_path, __method__)
+      end
+
+      private
+
+      def report_file_path_action(file_path, action)
+        puts ":#{name} ~> The file '#{file_path}' was '#{action}'"
+      end
+
+    end
+
+  end
+end