speck 1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTcxNDI0MDBkZDlkYWQ4OGJjOGI2N2RhYzQwM2Y5NDEyNmQzN2QyNw==
+  data.tar.gz: !binary |-
+    OTM5MTY0MDJjZDZiNDhlNmI3OWZlMmQ0M2FkNTBmMTgwODFkYThjYw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NzVhMWIzMjk3NDU4ZTg5MGRlOWRkMzI1ODhiZDVlMzI1YzA0Y2ZmZmU1MTkz
+    MjVmMjBmMWRjNjBlOTkxZDMwNzI0MWFmOGQ4MDIwNzVhYTlhYTMyOTI4OTQ0
+    OTNiNjhlZDI0ZGYzOTU2NGE1YmUwYzRjMGJmMGMxNjI3NjU3Y2E=
+  data.tar.gz: !binary |-
+    MzIyODQ4MGZlYzRlNTNkMWU4MmRiYWJhZDkzYmE5NGZmN2U3ODVjNjI0Y2U0
+    N2Q1ZjJhNmZhMDU5OWYxMzZkMmVkYmYzZGUzMThjMDFkYzc4NmY5YTIxZGMw
+    ZTdhMjc5YmQ4YTU4NGJlZWQ2NjBmM2IzZjNlNWE2OWY2MjA0NGE=

data/LICENSE.text

@@ -0,0 +1,16 @@
+Copyright (C) 2013 elliottcable
+
+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.markdown

@@ -0,0 +1,82 @@
+Speck
+=====
+This is a super-light library that attempts to enable a “literate” form of code-testing. This
+library is a part of a suite of tools intended to be used together; alongside its
+[brethren](#suite), it allows for “literate” specifications that look something like this:
+
+    Speck.new Dog do
+      some_breed = Dog::Shetland
+      
+      Dog.new.check          { it.breed == Dog::Labrador }
+      Dog.new(a_breed).check { it.breed == a_breed }
+      
+      Speck.new Dog.class_method :bark do
+        a_dog = Dog.new
+        a_dog.bark.check { |rv| rv == 'arf' }
+      end
+    end
+
+Ideas, feature requests, and bugs can be reported on the [GitHub][] issue tracker:
+
+<http://github.com/elliottcable/Speck/issues>
+
+  [GitHub]: http://github.com/
+
+Philosophy
+----------
+If you'll pay attention to the above example, you'll notice we do things a little differently around
+here. The conventions that Speck is designed to enable include:
+
+- first and foremost, we want the specification to be *source-code*, that is, we want it to read
+  like any Ruby code anywhere else. Our ‘checks’ (called assertions in other environments) simply
+  boil down to a `target` and a block to execute *against* that target. This is intended to be very
+  idiomatic Ruby-style code.
+- secondary to the former, we also like it when the checks themselves read a bit like an English
+  sentence. For example, Slack ([see below](#suite)) uses the [it][] library to make the blocks look
+  a little more readable in the usual case.
+  - this is especially powerful, because Spark extracts the source-code responsible for each check,
+    and hilights it based on the execution of that check. Thus, specification code itself is self-
+    documenting output for your test suite.
+- related to that, we tend to abstract the specifics of each check into variables, named in such a
+  way as to express the generic form of that specific element. If we're testing that a dog takes a
+  breed, but not *which* breed it takes, we place a relevant breed into `some_breed`. Similarly, we
+  might put an arbitrary numeric argument into a variable named `some_number` instead of using the
+  developer standards of `42` or `1337`. If, however, we were testing specific functionality related
+  to handling of the magic number `2`, as opposed to `1` or `3`, then we'd write the `2` directly
+  into the check-line.
+- our specification sections directly include *what* they're testing, instead of a description
+  thereof in a string. Whether this is an class, an instance method, or something else entirely.
+
+Generally speaking, we try to write *code* that self-describes what it's testing, instead of writing
+lots of english sentences in a DSL to redundantly describe the code being tested. (Lookin' at you,
+RSpec 'n friends.)
+
+  [it]: <http://github.com/elliottcable/it> "A sneakly library to expose iterated elements beautifully"
+
+Suite
+-----
+I've intentionally designed Speck to be tiny and modular. Speck itself, here, is three extremely
+brief files. To do more interesting things, and make specks easier to write, I've provided several
+“sister libraries” that expand upon what Speck itself does:
+
+- **[Slack][]**: Provides convenience methods for creating specks directly from various objects and
+                 values, and various other comparators and tools to make *writing* specks easier.
+- **[Spark][]**: Provides a [Rake][] task and other tools that beautifully *runs* your specks.
+- **[Smock][]**: Provides a “mocking and spying” toolkit, for testing intricate code that you can't
+                 easily decouple enough to test in minutae.
+
+In no way are any of these *required* to use Speck, nor do any of them inter-depend upon eachother.
+Mix-and-match as you desire. Or, y'know, write your own.
+
+  [Slack]: <http://github.com/elliottcable/slack>
+  [Spark]: <http://github.com/elliottcable/spark>
+  [Smock]: <http://github.com/elliottcable/smock>
+  
+  [Rake]: <http://rake.rubyforge.org> "A Ruby DSL for `make`-like project tasks"
+
+License
+-------
+This project is licensed very openly for your use, under a variation of the ‘MIT license.’
+Details are available in [LICENSE][].
+  
+  [LICENSE]: <./blob/master/LICENSE.text>

data/lib/speck.rb

@@ -0,0 +1,143 @@
+# All library files are required at the bottom, because in this unique case we
+# need `Speck` defined before we can use it to `Speck` anything.
+
+class Speck
+  VERSION = 1
+  
+  class <<self
+    
+    ##
+    # All specks not bound to an environment
+    attr_accessor :unbound
+    def unbound; @unbound ||= Array.new; end
+    
+    # The current `Speck` execution stack
+    # 
+    # @see #current
+    attr_accessor :stack
+    def stack; @stack ||= Array.new; end
+    
+    ##
+    # Returns the top `Speck` on the execution stack (the one currently in the
+    # process of executing)
+    # 
+    # When your `Speck`s are being run, there is a `stack` of `Speck` objects,
+    # consisting of the current nesting list of `Speck`s being run.
+    def current
+      stack.last
+    end
+    
+    ##
+    # Retreives the `Speck`s defiend for a given object, or, if none are
+    # defined, creates a new (empty) `Speck` for it.
+    # 
+    # It’s worth noting that `Module#instance_method` returns a new
+    # `UnboundMethod` object every time you call it, even for the same method…
+    # so you can’t retreive Specks assigned to `UnboundMethods` via
+    # `Module#instance_method` with this method.
+    def for object
+      specks = Speck::on object
+      specks << Speck.new(object) if specks.empty?
+      return specks
+    end
+    
+    ##
+    # Functions like `Speck::for`, without creating a new `Speck` if none are
+    # defined.
+    # 
+    # @see `Speck::for`
+    def on object
+      object.instance_variable_get(NinjaVar) ||
+        object.instance_variable_set(NinjaVar, Array.new)
+    end
+    
+  end
+  
+  ##
+  # This instance variable will be set on target objects to point to the
+  # specks for that object
+  NinjaVar = :@_specks_
+  
+  ##
+  # The block to be executed
+  attr_accessor :block
+  
+  ##
+  # `Speck`s which consider this `Speck` to be their environment
+  attr_accessor :children
+  def children; @children ||= Array.new; end
+  
+  ##
+  # The `environment` of a `Speck` is another `Speck`, describing some sort of
+  # parent. The environment of a `Speck` describing an `UnboundMethod`, for
+  # instance, would most likely be a `Speck` describing a `Module` or `Class`
+  # on which that method is defined
+  attr_accessor :environment
+  def environment= object
+    (@environment ? @environment.children : Speck.unbound).delete self
+    
+    speck = object.is_a?(Speck) || object.nil? ?
+      object : Speck::for(object).first
+    @environment = speck
+    
+    (@environment ? @environment.children : Speck.unbound) << self
+  end
+  
+  ##
+  # The checks involved in the current `Speck`
+  attr_accessor :checks
+  def checks; @checks ||= Array.new; end
+  
+  ##
+  # The `target` of a speck is usually the object which it is intended to
+  # describe (and test) the functionality of (Usually, this will be an
+  # instance of `Class`, `Module`, `Method` for “class” methods, or
+  # `UnboundMethod` for instance methods)
+  attr_accessor :target
+  def target= object
+    Speck::on(@target).delete self if @target and Speck::on(@target).include? self
+    
+    @target = object
+    
+    Speck::on(@target) << self if @target
+  end
+  
+  ##
+  # Creates a new `Speck`.
+  def initialize *environment, &block
+    self.target = environment.pop
+    
+    environment = environment.inject do |prev, curr|
+      raise Exception::EnvironmentConflict if Speck::for(curr).first.environment and Speck::for(curr).first.environment != Speck::for(prev).first
+      Speck::for(curr).first.environment = Speck::for(prev).first
+      curr
+    end
+    
+    self.environment = environment ? Speck::for(environment).first : Speck.current
+    @block = block || lambda {}
+  end
+  
+  ##
+  # Executes the `Speck`.
+  def execute
+    Speck.stack << self
+    @block.call
+    Speck.stack.pop
+  end
+  
+  
+  ##
+  # A root class, and container class, for `Speck` exceptions.
+  class Exception < StandardError
+    # Raised when a `Check` fails
+    CheckFailed = Class.new self
+    
+    # Raised when you attempt to stack an environment contrary to the existing
+    # environment
+    EnvironmentConflict = Class.new self
+  end
+  
+end
+
+require 'speck/battery'
+require 'speck/check'

data/lib/speck/battery.rb

@@ -0,0 +1,28 @@
+class Speck
+  ##
+  # A `Battery` of `Speck`s is a set of specks which should be executed
+  # together, and which interdepend upon other `Speck`s in the battery.
+  # `Batteries` are recursive structures; that is, a `Battery` may have sub–
+  # `Batteries` for relevant objects.
+  class Battery
+    
+    attr_reader :specks
+    attr_reader :targets
+    
+    def initialize
+      @specks = Array.new
+      @targets = Hash.new
+    end
+    
+    def << speck
+      @specks << speck
+      @targets[speck.target] ||= Battery.new
+      return self
+    end
+    
+    def [] object
+      return @targets[object]
+    end
+    
+  end
+end

data/lib/speck/check.rb

@@ -0,0 +1,43 @@
+class Speck
+  ##
+  # Represents a queued thing to be checked of some sort, within a `Speck`.
+  class Check
+    ##
+    # The block to be executed, determining the success or failure of this
+    # particular `Check`. If it accepts an argument, the result of the target
+    # block will be passed as that argument.
+    attr_accessor :expectation
+    
+    ##
+    # The `target` of a `Check` is a block that returns an object to be passed
+    # to the `expectation`. It represents the object that the `Check` is
+    # intended to, well, check.
+    attr_accessor :target
+    
+    ##
+    # The status of the `Check`. `nil` indicates the `Check` hasn’t been
+    # executed, and `true` or `false` indicate the success of the latest
+    # execution
+    attr_accessor :status
+    def passed?
+      status == :passed
+    end
+    
+    def initialize(target = nil, &expectation)
+      @target = target.respond_to?(:call) ? target : ->{target}
+      @expectation = expectation
+      Speck.current.checks << self if Speck.current
+    end
+    
+    ##
+    # Executes this `Check`, raising an error if the expectation returns nil
+    # or false.
+    def execute
+      call = @expectation.arity == 0 ? ->{@target.call; @expectation.call} : ->{@expectation[@target.call]}
+      @status = call.call ? :passed : :failed
+      raise Exception::CheckFailed unless passed?
+      return self
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: speck
+version: !ruby/object:Gem::Version
+  version: '1'
+platform: ruby
+authors:
+- elliottcable [http://ell.io/tt]
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-27 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/speck/battery.rb
+- lib/speck/check.rb
+- lib/speck.rb
+- README.markdown
+- LICENSE.text
+homepage: http://github.com/elliottcable/speck
+licenses:
+- MIT
+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.0.0
+signing_key: 
+specification_version: 4
+summary: ! 'An (extremely light) source-code literate code-specification and -testing
+  system. (see: spark, slack)'
+test_files: []
+has_rdoc: