operation 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4f94e9016bc8af451f55389d78d58f6123311d99
+  data.tar.gz: 18ff89827a6e314e669982c0b20e1420bbf8ef01
+SHA512:
+  metadata.gz: 4f4363d6801908c589fb62eefa8864620981026e175e52155a7abdc3b1c54e4932d36b6bf6050ea48c56368df12065c0be41926d63271b623512ae21978bc43c
+  data.tar.gz: dc133b43f1452a22d36d8e645f87837a69b33224bf5901a66370fdb5f72a559b03a60d7f2a5ecd42c113b88329819bee542bfe64f1d90030669409d3d3ba8b2f

data/README.md

@@ -0,0 +1,83 @@
+## Operation
+
+Imagine you have a class like this:
+
+```ruby
+class User
+  def delete(id)
+    @users.delete id
+  end
+end
+```
+
+What does it return? True? The User? an ID? What if an error occured? How does anyone calling `User.delete 42` know what happened?
+
+This is where `Operation` comes in. You would just **always** return an Operation. That Object holds information about what happened, like so:
+
+```ruby
+class User
+  def delete(id)
+    return Operation.new(code: :id_missing) unless id
+    return Operation.new(code: :invalid_id, id: id) unless id.match /[a-f]{8}/
+
+    user = @users[id]
+    if @users.delete id
+      Operation.new success:true, code: :user_deleted, user: user
+    else
+      Operation.new code: :deletion_failed
+    end
+  rescue ConnectionError
+      Operation.new code: :deletion_failed_badly
+  end
+end
+```
+
+This will give you this joyful, consistent, conventional, implementation-unaware programming feeling:
+
+```ruby
+  operation = User.delete 42
+  if operation.success?
+    puts "It worked! You deleted the user #{operation.meta.user.first_name}"
+  else
+    puts "Oh, could not delete User with ID #{operation.object} because #{operation.code}"
+  end
+```
+
+For your convenience you can use `Operations#failure` and `Operations.success`:
+
+```ruby
+class User
+  def delete(id)
+    return Operations.failure(:id_missing) unless id
+    return Operations.failure(:invalid_id, id: id) unless id.match /[a-f]{8}/
+
+    user = @users[id]
+    if @users.delete id
+      Operations.success :user_deleted, object: user
+    else
+      Operations.failure :deletion_failed
+    end
+  rescue ConnectionError
+      Operation.failure :deletion_failed_badly
+  end
+end
+```
+
+`#object` is just a shortcut to `#meta.object`:
+
+```ruby
+  operation = User.delete 42
+  operation.success? # => true
+  operation.object # => <#User id=42>
+  operation.meta # => <#Hashie::Mash object: <#User id=42>>
+  operation.metadata # => { object: <#User id=42> }
+  operation.failure? # => false
+```
+
+### Requirements
+
+* Ruby >= 1.9
+
+### Copyright
+
+MIT 2014 halo. See [MIT-LICENSE](http://github.com/halo/operation/blob/master/MIT-LICENSE).

data/lib/operation.rb

@@ -0,0 +1,36 @@
+require 'hashie/mash'
+require 'operations' # <- Not that we need them here, but the developer using this gem might want them.
+
+class Operation
+
+  attr_reader :metadata, :code
+
+  def initialize(options = {})
+    @success = [true, 'true', 1, '1'].include? options[:success]
+    @code = options[:code].to_s.to_sym unless options[:code].to_s == ''
+    @metadata = options[:metadata]
+  end
+
+  def success?
+    !!@success
+  end
+
+  def failure?
+    !success?
+  end
+
+  # Convenience Wrapper
+  def object
+    meta.object
+  end
+
+  def meta
+    if metadata.respond_to? :each_pair
+      Hashie::Mash.new metadata
+    elsif metadata
+      metadata
+    else
+      Hashie::Mash.new
+    end
+  end
+end

data/lib/operation/version.rb

@@ -0,0 +1,9 @@
+class Operation
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    STRING = [MAJOR, MINOR, TINY].compact.join('.')
+  end
+end

data/lib/operations.rb

@@ -0,0 +1,11 @@
+module Operations
+
+  def self.success(code = :success, metadata = {})
+    Operation.new success: true, code: code, metadata: metadata
+  end
+
+  def self.failure(code, metadata = {})
+    Operation.new success: false, code: code, metadata: metadata
+  end
+
+end

data/spec/lib/operation_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+require 'operation'
+
+describe Operation do
+
+  describe '#success' do
+    it 'handles different types of success' do
+      expect( Operation.new(success: true) ).to be_success
+      expect( Operation.new(success: 'true') ).to be_success
+      expect( Operation.new(success: 1) ).to be_success
+      expect( Operation.new(success: '1') ).to be_success
+    end
+  end
+
+  describe '#failure' do
+    it 'handles different types of failure' do
+      expect( Operation.new(success: false) ).to be_failure
+      expect( Operation.new(success: 'false') ).to be_failure
+      expect( Operation.new(success: 0) ).to be_failure
+      expect( Operation.new(success: '0') ).to be_failure
+    end
+  end
+
+  describe '#code' do
+    it 'is a Symbol if possible' do
+      expect( Operation.new(code: :normal).code ).to eq :normal
+      expect( Operation.new(code: 'normal').code ).to eq :normal
+      expect( Operation.new(code: 'it worked').code ).to eq :'it worked'
+      expect( Operation.new(code: 0).code ).to eq :'0'
+      expect( Operation.new(code: "\n").code ).to eq :"\n"
+    end
+
+    it 'may be nil' do
+      expect( Operation.new.code ).to be_nil
+      expect( Operation.new(code: nil).code ).to be_nil
+      expect( Operation.new(code: '').code ).to be_nil
+    end
+  end
+
+  describe '#metadata' do
+    it 'is whatever was passed in' do
+      expect( Operation.new(metadata: nil).metadata ).to be_nil
+      expect( Operation.new(metadata: []).metadata ).to eq []
+      expect( Operation.new(metadata: { one: :two }).metadata ).to eq one: :two
+    end
+  end
+
+  describe '#meta' do
+    it 'is a Mash for nil' do
+      expect( Operation.new.meta ).to be_instance_of Hashie::Mash
+      expect( Operation.new(metadata: nil).meta ).to be_instance_of Hashie::Mash
+    end
+
+    it 'is the Mash of what was passed in' do
+      expect( Operation.new(metadata: {}).meta ).to be_instance_of Hashie::Mash
+      expect( Operation.new(metadata: { one: { two: :three } }).meta.one.two ).to eq :three
+    end
+
+    it 'is the metadata if no Mash possible' do
+      expect( Operation.new(metadata: []).meta ).to eq []
+      expect( Operation.new(metadata: 'wow').meta ).to eq 'wow'
+    end
+  end
+
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: operation
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- halo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-27 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: :runtime
+  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'
+description: See https://github.com/halo/operation
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/operation.rb
+- lib/operation/version.rb
+- lib/operations.rb
+- spec/lib/operation_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/halo/operation
+licenses:
+- MIT-LICENSE
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Implementation-agnostic method return status objects
+test_files: []