contractual 0.0.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,17 @@
1
+ *.gem
2
+ *.rbc
3
+ .bundle
4
+ .config
5
+ .yardoc
6
+ Gemfile.lock
7
+ InstalledFiles
8
+ _yardoc
9
+ coverage
10
+ doc/
11
+ lib/bundler/man
12
+ pkg
13
+ rdoc
14
+ spec/reports
15
+ test/tmp
16
+ test/version_tmp
17
+ tmp
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source 'https://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in contractual.gemspec
4
+ gemspec
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ Copyright (c) 2012 TODO: Write your name
2
+
3
+ MIT License
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,78 @@
1
+ # Contractual
2
+
3
+ This gem provides limited support for the utilization of interfaces in Ruby. The approach here is
4
+ nearly idetnical to one suggested by Mark Bates at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.
5
+ It didn't seem like this had been turned into a gem yet, so I thought I might go ahead and put it together in
6
+ case others found the technique as helpful as I had.
7
+
8
+ ## What's this all about?
9
+
10
+ An **interface** is a logical description of the role of an entity within the system; basically it is a construct which specifies a contract for the behavior of a component in an application. You might be thinking: hey, I've got all these RSpec/Cucumber/etc. focused behavior descriptions -- surely you're not saying I *repeat* myself? Well, not exactly. Specifications give us programmatic descriptions of how a given entity should behave in certain situations. These can *include* contracts but potentially go significantly deeper, since they can specify just about any behavior you can imagine. An interface is somewhat simpler in comparison: it's more or less just a hint that a given method must be implemented by a subclass. So you specify 'implement this method' and 'implement that method' in order to have an 'official' whatever-kind-of-entity.
11
+
12
+ The basic idea here is to give hints to developers extending your API that aren't just in the form of shared RSpec examples, but rather embedded in the source of the superclass. Effectively, this supports the 'L' in SOLID -- making it easier to substitute subclasses in a dynamic language, ensuring that certain methods are implemented.
13
+
14
+ Please note that there are some limitations as to the utility of this approach, perhaps most importantly the one that Bates himself identified -- that the interface hints aren't going to show up, automagically anyway, in documentation. (As a note on good practice it probably makes sense to describe these as part of the documentation for the class.) Furthermore, please note that given there's no compiler for Ruby, the associated contractual warnings only 'kick in' the first time an unimplemented contractually-obligated method is invoked.
15
+
16
+ ## Installation
17
+
18
+ Add this line to your application's Gemfile:
19
+
20
+ gem 'contractual'
21
+
22
+ And then execute:
23
+
24
+ $ bundle
25
+
26
+ Or install it yourself as:
27
+
28
+ $ gem install contractual
29
+
30
+ ## Usage
31
+
32
+ Consider a canonical superclass.
33
+
34
+ class Vehicle
35
+ def drive(passengers, destination)
36
+ load passengers
37
+ follow Route.new(@current_location, destination)
38
+ unload passengers
39
+ end
40
+ end
41
+
42
+ See all the methods have to be implemented for this to work? Let's specify these as part of the interface:
43
+
44
+ class Vehicle
45
+
46
+ must_implement :load, :passengers
47
+ must_implement :follow, :route
48
+ must_implement :unload, :passengers
49
+
50
+ def move(passengers, destination)
51
+ load passengers
52
+ follow Route.new(@current_location, destination)
53
+ unload passengers
54
+ end
55
+ end
56
+
57
+ Let's suppose we've been handed this interface from another developer. How do we make a custom subclass? Our first attempt at implementing might look something like this:
58
+
59
+ class Zeppelin
60
+
61
+ def load(passengers); @passengers << passengers; end
62
+ def unload(passengers); @current_location << passengers; @passengers = []; end
63
+
64
+ end
65
+
66
+ So now when we try to invoke Zeppelin.move, we'll get an exception warning us that Zeppelin is obligated to implement a method 'follow' from the interface Vehicle. This is the 'hint' that the implementing developer has a bit more work to do before they can use this custom class smoothly with the rest of the system.
67
+
68
+ ## Contributing
69
+
70
+ 1. Fork it
71
+ 2. Create your feature branch (`git checkout -b my-new-feature`)
72
+ 3. Commit your changes (`git commit -am 'Added some feature'`)
73
+ 4. Push to the branch (`git push origin my-new-feature`)
74
+ 5. Create new Pull Request
75
+
76
+ ## Thanks!
77
+
78
+ Many thanks go to Mark Bates for the idea for this gem.
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env rake
2
+ require "bundler/gem_tasks"
@@ -0,0 +1,19 @@
1
+ # -*- encoding: utf-8 -*-
2
+ require File.expand_path('../lib/contractual/version', __FILE__)
3
+
4
+ Gem::Specification.new do |gem|
5
+ gem.authors = ["Joseph Weissman"]
6
+ gem.email = ["jweissman1986@gmail.com"]
7
+ gem.description = %q{This gem provides limited support for the utilization of interfaces in Ruby. The approach here is
8
+ nearly idetnical to one suggested by Mark Bates at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.
9
+ It didn't seem like this had been turned into a gem yet, so I thought I might go ahead and put it together in case others found the technique as helpful as I had.}
10
+ gem.summary = %q{Specify interface contracts for your Ruby classes.}
11
+ gem.homepage = ""
12
+
13
+ gem.files = `git ls-files`.split($\)
14
+ gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
15
+ gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
16
+ gem.name = "contractual"
17
+ gem.require_paths = ["lib"]
18
+ gem.version = Contractual::VERSION
19
+ end
@@ -0,0 +1,41 @@
1
+ require "contractual/version"
2
+
3
+ module Contractual
4
+ module Interface
5
+ class MethodNotImplementedError < NoMethodError; end
6
+
7
+ def self.included(klass)
8
+ klass.send(:include, Interface::Methods)
9
+ klass.send(:extend, Interface::Methods)
10
+ klass.send(:extend, Interface::ClassMethods)
11
+ end
12
+
13
+ module Methods
14
+ def does_not_implement_method(klass, method_name = nil)
15
+ if method_name.nil?
16
+ caller.first.match(/in \`(.+)\'/)
17
+ method_name = $1
18
+ end
19
+
20
+ klass_name = klass.class.name
21
+ interface_name = self.name
22
+
23
+ raise MethodNotImplementedError.new("#{klass.class.name} needs to implement '#{method_name}' for interface #{self.name}!")
24
+ end
25
+ end
26
+
27
+ module ClassMethods
28
+ def must_implement(method_name, *args)
29
+ this = self
30
+ self.class_eval do
31
+ define_method(method_name) do |*args|
32
+ this.does_not_implement_method(self, method_name)
33
+ end
34
+ end
35
+ end
36
+
37
+ # helper alias
38
+ def must(method_name, *args); must_implement(method_name, args); end
39
+ end
40
+ end
41
+ end
@@ -0,0 +1,3 @@
1
+ module Contractual
2
+ VERSION = "0.0.1"
3
+ end
metadata ADDED
@@ -0,0 +1,57 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: contractual
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.1
5
+ prerelease:
6
+ platform: ruby
7
+ authors:
8
+ - Joseph Weissman
9
+ autorequire:
10
+ bindir: bin
11
+ cert_chain: []
12
+ date: 2012-04-19 00:00:00.000000000 Z
13
+ dependencies: []
14
+ description: ! "This gem provides limited support for the utilization of interfaces
15
+ in Ruby. The approach here is \n nearly idetnical to one suggested by Mark Bates
16
+ at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.\nIt
17
+ didn't seem like this had been turned into a gem yet, so I thought I might go ahead
18
+ and put it together in case others found the technique as helpful as I had."
19
+ email:
20
+ - jweissman1986@gmail.com
21
+ executables: []
22
+ extensions: []
23
+ extra_rdoc_files: []
24
+ files:
25
+ - .gitignore
26
+ - Gemfile
27
+ - LICENSE
28
+ - README.md
29
+ - Rakefile
30
+ - contractual.gemspec
31
+ - lib/contractual.rb
32
+ - lib/contractual/version.rb
33
+ homepage: ''
34
+ licenses: []
35
+ post_install_message:
36
+ rdoc_options: []
37
+ require_paths:
38
+ - lib
39
+ required_ruby_version: !ruby/object:Gem::Requirement
40
+ none: false
41
+ requirements:
42
+ - - ! '>='
43
+ - !ruby/object:Gem::Version
44
+ version: '0'
45
+ required_rubygems_version: !ruby/object:Gem::Requirement
46
+ none: false
47
+ requirements:
48
+ - - ! '>='
49
+ - !ruby/object:Gem::Version
50
+ version: '0'
51
+ requirements: []
52
+ rubyforge_project:
53
+ rubygems_version: 1.8.22
54
+ signing_key:
55
+ specification_version: 3
56
+ summary: Specify interface contracts for your Ruby classes.
57
+ test_files: []