tron 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0ecb0f09d903e55c0725c96d38b913ba42ce1a5
+  data.tar.gz: 86b2a7e89a06393f26a69208ae775b5e4a0bdc34
+SHA512:
+  metadata.gz: 4861aa9046fc9dfc70e003d48ac729f7f25406538e034a4601e45252731682a281a475c71d5257244d355830abe3a0401a90a6b09cdd9278182a5d63ff1309f8
+  data.tar.gz: a308d078748e1d704b7fc54657f58f7011ca079ec977c7996517578ff867504997fa9a3cc3dc27c178bb301c7ecc110c3f3ba2499ee039e773882e2f0b7f2188

data/README.md

@@ -0,0 +1,146 @@
+[![Gem Version](https://img.shields.io/gem/v/tron.svg)](https://rubygems.org/gems/tron)
+[![Build Status](https://travis-ci.org/halo/tron.svg?branch=master)](https://travis-ci.org/halo/tron)
+[![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/tron/blob/master/LICENSE.md)
+
+# Tron
+
+Imagine you have a class like this:
+
+```ruby
+class User
+  def self.delete(id)
+    @users.delete id
+  end
+end
+```
+
+It's not clear from the code what this method returns (`true`?, a `User`?, a user ID?). What if an error occured - how does anyone calling `User.delete 42` know what happened?
+
+Indeed, it is not even clear what "successful" means in the context of this message - if there is no user and you try to delete one, is that considered a "failure"?
+
+Let's rewrite the method using Tron:
+
+```ruby
+class User
+  include Tron
+
+  def self.delete(id)
+    return Failure.call(:id_missing) unless id
+    return Failure.call(:invalid_id, id: id) unless id.match /[a-f]{8}/
+
+    user = @users[id]
+    if @users.delete id
+      Success.call :user_deleted, user: user
+    else
+      Success.call :deletion_failed, id: id
+    end
+
+  rescue ConnectionError
+      Failure.call :deletion_failed_badly, id: id
+  end
+end
+```
+
+One could even take it a step further and write it like this:
+
+```ruby
+class User
+  include Tron
+
+  def self.delete(id)
+    # If any one of these fail, the following blocks won't be executed
+    check_id_syntax(id)
+      .on_success { delete_user(id) }
+      .on_success { send_sms }
+      .on_success { redirect }
+  end
+
+  def self.check_id_syntax(id)
+    return Failure.call(:id_missing) unless id
+    return Failure.call(:invalid_id, id: id) unless id.match /[a-f]{8}/
+    Success.call(:id_looks_good)
+  end
+
+  def self.delete_user(id)
+    user = @users[id]
+    if @users.delete id
+      Success.call :user_deleted, user: user
+    else
+      Success.call :deletion_failed, id: id
+    end
+
+  rescue ConnectionError
+    Failure.call :deletion_failed_badly, id: id
+  end
+end
+```
+
+### So what are the benefits?
+
+#### 1. It will give you robust and predictable code
+
+Tron will give you this consistent, implementation-unaware, programming convention:
+
+```ruby
+result = User.delete 42
+
+if result.success?
+  puts "It worked! You deleted the user #{result.meta.user.first_name}"
+else
+  puts "Aw, could not delete User with ID #{result.meta.id} because #{result.code}"
+end
+```
+
+```ruby
+result = User.delete 42
+
+result.success? # => true
+result.failure? # => false
+result.metadata # => { object: <#User id=42> }
+result.meta     # => { object: <#User id=42> }
+result.object   # => <#User id=42>   <- shortcut for meta[:object]
+
+# In case you use Hashie, you will get that via #meta
+require 'hashie/mash'
+result.meta     # => <#Hashie::Mash object: <#User id=42>>
+result.object   # => <#User id=42>   <- shortcut for meta.object
+```
+
+#### 2. If will give you better tests
+
+How would you test this code?
+
+```ruby
+class Product
+  def self.delete(id)
+    return false if id.blank?
+    return false unless product = Products.find(id)
+    return false unless permission?
+    api.update(id, attributes)
+  end
+
+  def self.permission?
+    Date.today.sunday?
+  end
+end
+```
+
+You cannot simply test for the `false` as expected return value because it could mean anything. Tron helps you to check the response objects for every case.
+
+#### 3. It gives you documentation
+
+While the code you're writing becomes slightly more verbose, that verbosity translates directly into documenation. You see immediately what each line is doing.
+
+### Background
+
+Tron is a complete rewrite of its predecessor [operation](https://github.com/halo/operation). I got inspired by the [deterministic](https://github.com/pzol/deterministic) gem, which is the follow-up of the [monadic](https://github.com/pzol/monadic) gem.
+
+`operation` is very useful, but the API was always a bit cumbersome. Additionally, there was no paradigm of chaining trons, i.e. run multiple trons but bail out if one of them fails.
+
+### Requirements
+
+* Ruby >= 2.2.3
+
+### Copyright
+
+MIT 2015 halo. See [MIT-LICENSE](http://github.com/halo/tron/blob/master/LICENSE.md).

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/tron.rb

@@ -0,0 +1,8 @@
+require 'tron/version'
+
+require 'tron/resultable'
+require 'tron/success'
+require 'tron/failure'
+
+module Tron
+end

data/lib/tron/failure.rb

@@ -0,0 +1,16 @@
+module Tron
+  class Failure
+    include Resultable
+
+    def on_success(_ = nil)
+      self
+    end
+    alias_method :>>, :on_success
+
+    def on_failure(proc = nil, &block)
+      (proc || block).call
+    end
+    alias_method :>>, :on_failure
+
+  end
+end

data/lib/tron/resultable.rb

@@ -0,0 +1,62 @@
+module Tron
+  module Resultable
+    attr_reader :metadata
+
+    def self.included(receiver)
+      receiver.extend ::Tron::Resultable::ClassMethods
+    end
+
+    module ClassMethods
+      # Convenience wrapper
+      def call(code, metadata = nil)
+        new code: code, metadata: metadata
+      end
+    end
+
+    def initialize(code: nil, metadata: nil)
+      @code     = code
+      @metadata = metadata
+    end
+
+    def success?
+      is_a? ::Tron::Success
+    end
+
+    def failure?
+      is_a? ::Tron::Failure
+    end
+
+    def code
+      return if @code.to_s == ''
+      @code.to_s.to_sym
+    end
+
+    # Convenience Wrapper
+    def object
+      metadata[:object] || metadata['object']
+    rescue
+      nil
+    end
+
+    def meta
+      if defined? ::Hashie::Mash
+        metamash
+      else
+        metadata
+      end
+    end
+
+    private
+
+    def metamash
+      if metadata.respond_to? :each_pair
+        ::Hashie::Mash.new metadata
+      elsif metadata
+        metadata
+      else
+        ::Hashie::Mash.new
+      end
+    end
+
+  end
+end

data/lib/tron/success.rb

@@ -0,0 +1,16 @@
+module Tron
+  class Success
+    include Resultable
+
+    def on_success(proc = nil, &block)
+      (proc || block).call
+    end
+    alias_method :>>, :on_success
+
+    def on_failure(_ = nil)
+      self
+    end
+    alias_method :>>, :on_failure
+
+  end
+end

data/lib/tron/version.rb

@@ -0,0 +1,10 @@
+module Tron
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 7
+    TINY  = 0
+    PRE = nil
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join '.'
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: tron
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- halo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: General-purpose method return objects that can be chained. Heavily inspired
+  by the `deterministic` gem, but much much more light-weight.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/tron.rb
+- lib/tron/failure.rb
+- lib/tron/resultable.rb
+- lib/tron/success.rb
+- lib/tron/version.rb
+homepage: https://github.com/halo/tron
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: General-purpose method return objects that can be chained.
+test_files: []
+has_rdoc: