tobacco 0.0.1

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use 1.9.3@tobacco

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm:
+  - 1.9.3

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Craig Williams
+
+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,319 @@
+# Tobacco [![Build Status](https://secure.travis-ci.org/CraigWilliams/Tobacco.png)](http://travis-ci.org/CraigWilliams/Tobacco)
+
+
+Tobacco is a convenience wrapper around fetching content from a url or using the content supplied to it, verifying that content was received, creating a directory structure where the file will live and finally writing the content to that file.
+
+This procedure is mostly simple url reading and making directories and writing to a file. We deal with a system where many files are being written to a specific parent directory and urls are formed using a pre-determined host and structure. The implementation details are consistent and to avoid duplication in our code, we extract the things that don't change from the things that do.
+
+## Example
+
+At Factory Code Labs, we work on a system for which we must deploy static HTML files. [Mike Pack](http://github.com/MikePack) has written a concurrency gem named [Pipes](http://github.com/MikePack/Pipes) that masterfully handles all the stages the publishing system must perform.
+
+Tobacco is meant to complement the Writer classes that utilize Pipes. With a few configuration settings and two or three methods added to a writer class, Tobacco will handle the rest.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'tobacco'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tobacco
+
+## Usage
+
+Tobacco is very simple to use.
+
+
+##Configuration##
+
+First add a configuration file. In Rails for example, this can live in 'config/initializers/tobacco.rb'
+
+```ruby
+Tobacco.configure do |config|
+  config.published_host         = Rails.env.development? ? 'http://localhost:3000' : 'http://localhost'
+  config.base_path              = File.join(Rails.root, 'published_content', Rails.env)
+
+  config.content_method         = :content
+  config.content_url_method     = :content_url
+  config.output_filepath_method = :output_filepath
+end
+```
+
+
+**Default Values**
+
+These are the setting that come default with Tobacco.
+
+```ruby
+  base_path              = '/tmp/published_content'
+  published_host         = 'http://localhost:3000'
+  content_method         = :content
+  content_url_method     = :content_url
+  output_filepath_method = :output_filepath
+```
+
+**Configuration Options**
+
+```ruby
+published_host
+```
+
+published_host will be used to form the host part of the url before reading a web pages' content.
+
+```ruby
+base_path
+```
+
+base_path is the base folder where all other folders and files will live when publishing files.
+All file writing paths generated will be appended to the base_path.
+
+
+### Methods in Writer Classes ###
+
+**Optional**
+
+If the Writer class will be providing its own content, say from manipulating data from a database, this is the method Tobacco will be calling to get that content.
+
+It is not required otherwise.
+
+Return a String
+
+```ruby
+def content
+  # A string to be written to file
+end
+```
+
+**Required**
+
+The url that will be read for content is created based on the published_host and the string returned from this method.
+
+The following example will produce a url of "http://localhost:3000/entertainment/videos/1"
+
+Return a String
+
+```ruby
+def content_url
+  '/entertainment/videos/1'
+end
+```
+
+
+The ouput_filepath can return a string or an array of path options. All are joined with the base_path to create the full path the file location.
+
+Return a String or Array
+
+```ruby
+def output_filepath
+  [ 'public', 'videos', '1', 'index.html' ]
+
+  # or
+
+  'public/videos/1/index.html'
+end
+```
+
+
+## Hook Methods ##
+
+There are four (4) hook methods you can tie into during the reading and writing process. Three are for handling errors and one is for manipulating the content before it is written.
+
+Be default, there are no 
+
+```ruby
+def on_success(content)
+  # code to execute after content writen to file
+end
+```
+
+```ruby
+def on_read_error(error)
+  # handle
+end
+```
+
+```ruby
+def on_write_error(error)
+  # handle
+end
+```
+
+The error is a Tobacco::Error object with the following attributes:
+
+```ruby
+msg      - A short description of the error
+content  - The content or lack of content
+filepath - The output path where the content was to be written
+error    - The error that was raised. An error object that responds to message.
+```
+
+
+```ruby
+def before_write(content)
+  # manipulate content
+
+  return content #=> using "return" to emphasize that this method must return the content to Tobacco for writing
+end
+```
+
+
+## Public API ##
+
+The first thing to call is generate_file_paths so that the content_url and output_filepath is available to Tobacco for reading and writing.
+
+```ruby
+generate_file_paths
+```
+
+When the read method is called, it will do three things.
+  
+  1. Set the reader to either the calling class,
+      because it implemented the content method, or to an instance of Tobacco::Inhaler to prepare for reading.
+  2. Read the content
+  3. Verify content was read successfully.
+      If not, the callback :on_read_error will be called with an instance of Tobacco::Error as described above.
+
+```ruby
+read
+```
+
+Write can be called after these first two or you can skip the read method if the content is provided directly. In either case, if the content is written successfully the :on_success callback is called. If not, the :on_write_error callback is called.
+
+```ruby
+write!
+```
+
+Example using all three methods
+
+```ruby
+writer = Tobacco::Smoker.new(self)
+writer.generate_file_paths
+writer.read
+writer.write!
+```
+
+Example when setting the content directly. This takes the content as a string and writes it to file.
+
+```ruby
+writer = Tobacco::Smoker.new(self)
+writer.generate_file_paths
+writer.content = 'lorem ipsum'
+writer.write!
+```
+
+###Usage###
+
+There are only three methods to add to your class that Tobacco needs to do its work and
+only two of those are required. The third method allows your class to provide its own
+content to be written to file. In many cases, the content being written to file is taken from
+a database or other source and formatted by the class itself. Tobacco will simple take the 
+provided content and write it to file for you.
+
+Here is an example class using all three methods.
+
+```ruby
+module Writers
+  class HTMLWriter
+    def write!
+      writer = Tobacco::Smoker.new(self)
+      writer.generate_file_paths
+      writer.read
+      writer.write!
+    end
+
+    # If this method is present, Tobacco will use it instead of the content_url method.
+    def content
+      'Content to write to file'
+    end
+
+    def content_url
+      '/vehicles/1/index.html'
+    end
+
+    def output_filepath
+      [ 'vehicles', vehicle.model, vehicle.id, 'index.html']
+    end
+  end
+end
+```
+
+
+This example includes the callback methods
+
+```ruby
+module Writers
+  class HTMLWriter
+    def write!
+      writer = Tobacco::Smoker.new(self)
+      writer.generate_file_paths
+      writer.read
+      writer.write!
+    end
+
+    # If this method is present, Tobacco will use it instead of the content_url method.
+    def content
+      'Content to write to file'
+    end
+
+    def content_url
+      '/vehicles/1/index.html'
+    end
+
+    def output_filepath
+      [ 'vehicles', vehicle.model, vehicle.id, 'index.html']
+    end
+
+    #--------------------------------------
+    # Callbacks
+    #--------------------------------------
+    def on_success(content)
+      # Send email notfications
+    end
+
+    def on_read_error(error)
+      # code to handle missing content
+    end
+
+    def on_write_error(error)
+      # code to handle write error
+    end
+
+    def before_write(content)
+      # code to manipulate the content
+
+      return content #=> using "return" to emphasize that this method must return the content to Tobacco for writing
+    end
+  end
+end
+```
+
+## Final Thoughts ##
+
+To avoid duplication, we wrap the callbacks and write! method in a helper module that is included in all the Writer classes. This makes the individual Writers very small and easy to maintain.
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write tests
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+## Credits
+
+
+![Factory Code Labs](http://i.imgur.com/yV4u1.png)
+
+Tobacco is maintained by [Factory Code Labs](http://www.factorycodelabs.com).
+
+## License
+
+Tobacco is Copyright © 2012 Factory Code Labs. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rspec/core/rake_task'
+
+desc 'Run RSpec code examples'
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+task default: :spec
+

data/lib/tobacco/burnout.rb

@@ -0,0 +1,28 @@
+module Tobacco
+  module Burnout
+
+    class MaximumAttemptsExceeded < Exception; end
+
+    def self.try(max_attempts, &block)
+      attempts = 1
+
+      while(attempts <= max_attempts)
+        success, return_value = attempt &block
+        return return_value if success
+
+        attempts += 1
+      end
+
+      raise MaximumAttemptsExceeded.new("Execution timed out more than #{max_attempts} time(s).  I give up.")
+    end
+
+    def self.attempt(&block)
+      begin
+        [ true, yield ]
+      rescue
+        false
+      end
+    end
+
+  end
+end

data/lib/tobacco/error.rb

@@ -0,0 +1,38 @@
+# Passed to callbacks when error occurs
+#
+# msg      #=> Context where the error occurred
+# filepath #=> Filepath to where the file was to be written
+# content  #=> Content to be written after it was modified using the callback before_write
+# object   #=> The error object that raised the error
+#
+module Tobacco
+  class Error
+    attr_accessor :msg, :filepath, :content, :object
+
+    def initialize(options = {})
+      self.msg      = options[:msg]
+      self.filepath = options[:filepath]
+      self.content  = options[:content]
+      self.object   = options[:object]
+    end
+
+    # Allow destructure of the error into variable names
+    #
+    # eg.
+    #
+    #   msg, filepath, content, object = *error
+    #   [ 'Error writing file', '/path/to/file', '<h1>Title</h1>', #<Errno::EACCES: Permission denied - /users/index.txt> ]
+    #
+    # You can access the attributes normally as well
+    #
+    #   error.msg      #=> 'Error writing file'
+    #   error.filepath #=> '/path/to/file'
+    #   error.object   #=> #<Errno::EACCES: Permission denied - /users/index.txt>
+    #
+    def to_a
+      [ msg, filepath, content, object ]
+    end
+    alias_method :to_ary, :to_a
+
+  end
+end

data/lib/tobacco/exhaler.rb

@@ -0,0 +1,26 @@
+module Tobacco
+  class Exhaler
+    attr_accessor :content, :filepath
+
+    def initialize(content = '', filepath = '')
+      self.content = content
+      self.filepath = filepath
+    end
+
+    def write!
+     create_directory
+     write_content_to_file
+    end
+
+    def create_directory
+      FileUtils.mkdir_p File.dirname(filepath)
+    end
+
+    def write_content_to_file
+      File.open(filepath, 'w') do |f|
+        f.write content
+      end
+    end
+
+  end
+end

data/lib/tobacco/inhaler.rb

@@ -0,0 +1,13 @@
+module Tobacco
+  class Inhaler
+    attr_accessor :url
+
+    def initialize(url = '')
+      self.url = url
+    end
+
+    def read
+      @content ||= Tobacco::Burnout.try(3) { URI.parse(url).read }
+    end
+  end
+end

data/lib/tobacco/roller.rb

@@ -0,0 +1,38 @@
+module Tobacco
+  class Roller
+
+    def initialize(smoker)
+      @smoker = smoker
+    end
+
+    def output_filepath
+      @output_filepath ||= File.join(base_path, *filepath_options)
+    end
+
+    def content_url
+      separator = url_path =~ /^\// ? '' : '/'
+
+      @content_url ||= "#{host}#{separator}#{url_path}"
+    end
+
+
+    #---------------------------------------------------------
+    private
+
+    def url_path
+      @url_path ||= @smoker.send(Tobacco.content_url_method)
+    end
+
+    def filepath_options
+      @smoker.send(Tobacco.output_filepath_method)
+    end
+
+    def host
+      Tobacco.published_host
+    end
+
+    def base_path
+      Tobacco.base_path
+    end
+  end
+end

data/lib/tobacco/smoker.rb

@@ -0,0 +1,141 @@
+module Tobacco
+  class MissingContentError < RuntimeError
+    def message
+      "No error encountered but content is empty"
+    end
+  end
+
+  class Smoker
+
+    attr_accessor :smoker,
+      :file_path_generator,
+      :reader,
+      :writer,
+      :content
+
+    def initialize(smoker, content = '')
+      self.smoker  = smoker
+      self.content = content
+    end
+
+    def generate_file_paths
+      self.file_path_generator = Roller.new(smoker)
+    end
+
+    def read
+      choose_reader
+      read_content
+      verify_content
+    end
+
+    def write!
+      return unless content_present?
+
+      begin
+        filepath         = file_path_generator.output_filepath
+        modified_content = modify_content_before_writing
+        content_writer   = Tobacco::Exhaler.new(modified_content, filepath)
+
+        content_writer.write!
+
+        callback(:on_success, modified_content)
+
+      rescue => e
+
+        error = error_object('Error Writing', modified_content, e)
+        callback(:on_write_error, error)
+      end
+    end
+
+
+    #---------------------------------------------------------
+    # End of Public API
+    #---------------------------------------------------------
+
+
+    #---------------------------------------------------------
+    # Write helper methods
+    #---------------------------------------------------------
+    def modify_content_before_writing
+      callback(:before_write, content)
+    end
+
+    #---------------------------------------------------------
+    # Read helper methods
+    #---------------------------------------------------------
+    def read_content
+      self.content = reader.send(Tobacco.content_method)
+    end
+
+    def verify_content
+      unless content_present?
+
+        # At this point, the content might be an error object
+        # but if not, we create one
+        #
+        object = missing_content_error(content)
+        error  = error_object('Error Reading', '', object)
+
+        callback(:on_read_error, error)
+      end
+    end
+
+    def missing_content_error(content)
+      if content.respond_to? :message
+        content
+      else
+        Tobacco::MissingContentError.new
+      end
+    end
+
+    def content_present?
+      @content_present ||= content?
+    end
+
+    def content?
+      return false if content.nil? || content.empty?
+
+      Array(content).last !~ /404 Not Found|The page you were looking for doesn't exist/
+    end
+
+    def choose_reader
+      # The reader will either be the calling class (smoker)
+      # if it provides the content method or a new Inhaler
+      # object that will be used to read the content from a url
+      #
+      self.reader = \
+        if smoker.respond_to? Tobacco.content_method
+          smoker
+        else
+          Inhaler.new(file_path_generator.content_url).tap do |inhaler|
+
+            # Add an alias for the user configured content_method
+            # so that when it is called it calls :read
+            # on the Inhaler instance
+            #
+            inhaler.instance_eval %{
+              alias :"#{Tobacco.content_method}" :read
+            }
+          end
+      end
+    end
+
+    #---------------------------------------------------------
+    # private
+
+    def error_object(msg, modified_content, e)
+      Tobacco::Error.new(
+        msg: msg,
+        filepath: file_path_generator.filepath,
+        content: modified_content,
+        object: e
+      )
+    end
+
+    def callback(name, error)
+      if smoker.respond_to? name
+        smoker.send(name, error)
+      end
+    end
+  end
+end

data/lib/tobacco/version.rb

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