bookland 1.0.0 → 1.0.1

data/.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 pkg
 .bundle
+Gemfile.lock
+docs

data/README.md

@@ -1,12 +1,13 @@
 Bookland
 ========
 
-[Bookland](http://en.wikipedia.org/wiki/Bookland) provides an ISBN class in Ruby.
+[Bookland](http://en.wikipedia.org/wiki/Bookland) provides an ISBN class in
+Ruby.
 
-Examples
---------
+Usage
+-----
 
-    include Bookland
+    require 'bookland'
 
     isbn10 = ISBN.new('0262011530')
     isbn10.to_isbn13
@@ -18,17 +19,15 @@ Examples
     isbn13 == ISBN.new('9780262011532')
     => true
 
-    # An invalid ISBN
-    not_an_isbn = ISBN.new('0262011531')
-    not_an_isbn.valid?
+    # Does an invalid ISBN quack like an ISBN?
+    bad_isbn = ISBN.new('0262011531')
+    bad_isbn.valid?
     => false
-    not_an_isbn.to_isbn13
+    bad_isbn.to_isbn13
     => Bookland::ISBNError: Invalid ISBN
 
 Some utility methods defined in the class level:
 
-    include Bookland
-
     ISBN.to_13('0262011530')
     => "9780262011532"
 

data/Rakefile

@@ -9,3 +9,15 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
 end
 
 task :default => :spec
+
+require 'rocco/tasks'
+Rocco::make 'docs/'
+
+desc 'Build rocco docs'
+task :docs => :rocco
+directory 'docs/'
+
+desc 'Build docs and open in browser for the reading'
+task :read => :docs do
+  sh 'open docs/lib/bookland/isbn.html'
+end

data/bookland.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
 
   s.add_development_dependency('rspec', '~> 2.5.0')
+  s.add_development_dependency('rocco', '~> 0.6.0')
 end

data/lib/bookland.rb

@@ -1 +1,5 @@
 require 'bookland/isbn'
+
+# Include Bookland in global namespace.
+#
+Object.send(:include, Bookland)

data/lib/bookland/isbn.rb

@@ -1,16 +1,37 @@
+# encoding: UTF-8
+#
+# [Bookland][bl] is a simple ISBN class in Ruby.
+#
+# [bl]: http://en.wikipedia.org/wiki/Bookland
 module Bookland
 
-  # A simple ISBN class
+  #### Public Interface
+  #
+  # `ISBN.new` takes an optional string. The string should look like an ISBN
+  # and may contain extra characters that are traditionally used to format
+  # ISBNs.
+  #
+  # The following are valid instantiations:
+  #
+  #     isbn13 = ISBN.new('9780826476951')
+  #     isbn10 = ISBN.new('0-8264-7695-3')
+  #
+  #     isbn10 == isbn13
+  #     => true
   class ISBN
     class << self
+
+      # Casts a specified string to a 10-digit ISBN.
       def to_10(isbn)
         new(isbn).to_isbn10.to_s
       end
 
+      # Casts a specified string to a 13-digit ISBN.
       def to_13(isbn)
         new(isbn).to_isbn13.to_s
       end
 
+      # Returns `true` if the specified string is a valid ISBN.
       def valid?(isbn)
         new(isbn).valid?
       end
@@ -20,19 +41,24 @@ module Bookland
       self.seed = seed
     end
 
+    # Returns `true` if the ISBN is equal to another specified ISBN.
     def ==(other)
       to_isbn13.to_s == other.to_isbn13.to_s
     end
 
+    # Inspecting an ISBN object will return its string representation.
     def inspect
       to_s
     end
 
+    # Sets the seed of the ISBN based on a specified string.
     def seed=(seed)
       @raw = seed.gsub(/[^Xx0-9]/, '').split(//) rescue @raw = []
     end
 
+    # Casts the ISBN to a ten-digit ISBN.
     def to_isbn10
+
       raise ISBNError unless valid?
 
       if isbn13?
@@ -54,13 +80,27 @@ module Bookland
       end
     end
 
+    # Casts ISBN to a string.
+    #
+    # Takes an optional list of integers, which it then uses to dashify the
+    # ISBN like so:
+    #
+    #     isbn = ISBN.new('0826476953')
+    #     isbn.to_s(1,4,4,1)
+    #     => "0-8264-7695-3"
+    #
     def to_s(*blocks)
       return false unless valid?
 
       raw = @raw.dup
-      blocks.any? ? (blocks.map { |i| raw.shift(i).join } << raw.join).delete_if(&:empty?).join('-') : raw.join
+      if blocks.any?
+        (blocks.map { |i| raw.shift(i).join } << raw.join).delete_if(&:empty?).join('-')
+      else
+        raw.join
+      end
     end
 
+    # Returns `true` if the ISBN is valid.
     def valid?
       if isbn10?
         @raw[9] == check_digit_10(@raw)
@@ -102,3 +142,5 @@ module Bookland
     end
   end
 end
+
+# C'est ça.

data/lib/bookland/version.rb

@@ -1,3 +1,3 @@
 module Bookland
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/spec/bookland/isbn_spec.rb

@@ -1,137 +1,164 @@
-require "spec_helper"
+require 'spec_helper'
 
 module Bookland
-  describe Bookland::ISBN do
-    context ".to_10" do
-      it "converts to ISBN-10" do
+  describe ISBN do
+    describe ".to_10" do
+      it "casts a specified string to a ten-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.to_10(isbn10).should eql isbn10
-          Bookland::ISBN.to_10(isbn13).should eql isbn10
+          ISBN.to_10(isbn10).should eql isbn10
+          ISBN.to_10(isbn13).should eql isbn10
         end
       end
 
-      it "raises an ISBNError if an invalid ISBN is converted" do
+      it "raises an ISBNError if the specified string is not a valid ISBN" do
         ['foo', 1, '', nil].each do |isbn|
           expect do
-            Bookland::ISBN.to_10(isbn)
-          end.to raise_error Bookland::ISBNError
+            ISBN.to_10(isbn)
+          end.to raise_error ISBNError
         end
       end
     end
 
-    context ".to_13" do
-      it "converts to ISBN-13" do
+    describe ".to_13" do
+      it "casts a specified string to a 13-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.to_13(isbn10).should eql isbn13
-          Bookland::ISBN.to_13(isbn13).should eql isbn13
+          ISBN.to_13(isbn10).should eql isbn13
+          ISBN.to_13(isbn13).should eql isbn13
         end
       end
 
-      it "raises an ISBNError if an invalid ISBN is converted" do
+      it "raises an ISBNError if the specified string is not a valid ISBN" do
         ['foo', 1, '', nil].each do |isbn|
           expect do
-            Bookland::ISBN.to_13(isbn)
-          end.to raise_error Bookland::ISBNError
+            ISBN.to_13(isbn)
+          end.to raise_error ISBNError
         end
       end
     end
 
-    context ".valid?" do
-      it "validates an ISBN" do
-        Bookland::ISBN.valid?("9780485113358").should be_true
-        Bookland::ISBN.valid?("9780485113359").should be_false
+    describe ".valid?" do
+      it "returns true if a specified string is a valid ISBN" do
+        ISBN.valid?('9780485113358').should be_true
+      end
+
+      it "returns false if a specified string is not a valid ISBN" do
+        ISBN.valid?('9780485113359').should be_false
       end
     end
 
-    context "#to_isbn13" do
-      it "converts an ISBN-10 to ISBN-13" do
+    describe "#to_isbn10" do
+      it "casts a 10-digit ISBN to a 10-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.new(isbn10).to_isbn13.should == Bookland::ISBN.new(isbn13)
+          ISBN.new(isbn10).to_isbn10.should == ISBN.new(isbn10)
         end
       end
 
-      it "raises an ISBNError if an invalid ISBN-10 is converted to ISBN-13" do
+      it "casts a 13-digit ISBN to a 10-digit ISBN" do
         isbns do |isbn10, isbn13|
-          invalid = isbn10.gsub(/(.)$/, "#{(isbn10.split(//).last.to_i - 2) % 10}")
+          ISBN.new(isbn13).to_isbn10.should == ISBN.new(isbn10)
+        end
+      end
+
+      it "raises an ISBNError if self is not a valid ISBN" do
+        isbns do |isbn10, isbn13|
+          invalid = isbn13.gsub(/(.)$/, "#{(isbn13.split(//).last.to_i - 2) % 10}")
           expect do
-            Bookland::ISBN.new(invalid).to_isbn13
-          end.to raise_error Bookland::ISBNError
+            ISBN.new(invalid).to_isbn10
+          end.to raise_error ISBNError
         end
       end
     end
 
-    context "#to_isbn10" do
-      it "converts an ISBN-13 to ISBN-10" do
+    describe "#to_isbn13" do
+      it "casts a 10-digit ISBN to a 13-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.new(isbn13).to_isbn10.should == Bookland::ISBN.new(isbn10)
+          ISBN.new(isbn10).to_isbn13.should == ISBN.new(isbn13)
         end
       end
 
-      it "raises an ISBNError if an invalid ISBN-13 is converted to ISBN-10" do
+      it "casts a 13-digit ISBN to a 13-digit ISBN" do
         isbns do |isbn10, isbn13|
-          invalid = isbn13.gsub(/(.)$/, "#{(isbn13.split(//).last.to_i - 2) % 10}")
+          ISBN.new(isbn13).to_isbn13.should == ISBN.new(isbn13)
+        end
+      end
+
+      it "raises an ISBNError if self is not a valid ISBN" do
+        isbns do |isbn10, isbn13|
+          invalid = isbn10.gsub(/(.)$/, "#{(isbn10.split(//).last.to_i - 2) % 10}")
           expect do
-            Bookland::ISBN.new(invalid).to_isbn10
-          end.to raise_error Bookland::ISBNError
+            ISBN.new(invalid).to_isbn13
+          end.to raise_error ISBNError
         end
       end
     end
 
-    context "#==" do
-      it "equates ISBN-10 and ISBN-13" do
+    describe "#==" do
+      it "equates a ten- and a thirteen-digit ISBN" do
+        isbns do |isbn10, isbn13|
+          (ISBN.new(isbn10) == ISBN.new(isbn13)).should be_true
+        end
+      end
+
+      it "equates a ten- and a ten-digit ISBN" do
+        isbns do |isbn10, isbn13|
+          (ISBN.new(isbn10) == ISBN.new(isbn10)).should be_true
+        end
+      end
+
+      it "equates a thirteen- and a thirteen-digit ISBN" do
         isbns do |isbn10, isbn13|
-          (Bookland::ISBN.new(isbn10) == Bookland::ISBN.new(isbn13)).should be_true
+          (ISBN.new(isbn13) == ISBN.new(isbn13)).should be_true
         end
       end
     end
 
-    context "#valid?" do
-      it "validates ISBN-10s" do
+    describe "#valid?" do
+      it "validates a ten-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.new(isbn10).valid?.should be_true
+          ISBN.new(isbn10).valid?.should be_true
         end
       end
 
-      it "validates ISBN-13s" do
+      it "validates a thirteen-digit ISBN" do
         isbns do |isbn10, isbn13|
-          Bookland::ISBN.new(isbn13).valid?.should be_true
+          ISBN.new(isbn13).valid?.should be_true
         end
       end
 
-      it "does not validate if seed looks like an ISBN-13 but has an invalid check digit" do
+      it "does not validate if the 13-digit seed has an invalid check digit" do
         isbns do |isbn10, isbn13|
           invalid = isbn13.gsub(/(.)$/, "#{(isbn13.split(//).last.to_i - 2) % 10}")
-          Bookland::ISBN.new(invalid).valid?.should be_false
+          ISBN.new(invalid).valid?.should be_false
         end
       end
 
-      it "does not validate if seed looks like an ISBN-10 but has an invalid check digit" do
+      it "does not validate if the 10-digit seed has an invalid check digit" do
         isbns do |isbn10, isbn13|
           invalid = isbn10.gsub(/(.)$/, "#{(isbn10.split(//).last.to_i - 2) % 10}")
-          Bookland::ISBN.new(invalid).valid?.should be_false
+          ISBN.new(invalid).valid?.should be_false
         end
       end
 
       it "does not validate if seed is not an ISBN" do
-        ['foo', 1, '', nil].each { |seed| Bookland::ISBN.new(seed).valid?.should be_false }
+        ['foo', 1, '', nil].each { |seed| ISBN.new(seed).valid?.should be_false }
       end
     end
 
-    context "#to_s" do
-      it "casts as string" do
-        Bookland::ISBN.new('0262011530').to_s.should eql '0262011530'
+    describe "#to_s" do
+      it "casts to string" do
+        ISBN.new('0262011530').to_s.should eql '0262011530'
       end
 
-      it "casts as string and hyphenate an ISBN-13" do
-        Bookland::ISBN.new("9780485113358").to_s(3, 10).should eql '978-0485113358'
+      it "casts to string and hyphenates a thirteen-digit ISBN" do
+        ISBN.new('9780485113358').to_s(3, 10).should eql '978-0485113358'
       end
 
-      it "casts as string and hyphenate an ISBN-10" do
-        Bookland::ISBN.new("048511335X").to_s(1, 3, 5, 1).should eql '0-485-11335-X'
+      it "casts to string and hyphenate a ten-digit ISBN" do
+        ISBN.new('048511335X').to_s(1, 3, 5, 1).should eql '0-485-11335-X'
       end
 
-      it "returns false if an invalid ISBN is cast as string" do
-        ['foo', 1, '', nil].each { |seed| Bookland::ISBN.new(seed).to_s.should be_false }
+      it "returns false if ISBN is not valid" do
+        ['foo', 1, '', nil].each { |seed| ISBN.new(seed).to_s.should be_false }
       end
     end
   end

data/spec/bookland_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Bookland do
+  it "includes itself in the global namespace" do
+    defined?(ISBN).should eql 'constant'
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bookland
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Paper Cavalier
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-03 00:00:00 +00:00
+date: 2011-03-17 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,6 +34,22 @@ dependencies:
         version: 2.5.0
   type: :development
   version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rocco
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 6
+        - 0
+        version: 0.6.0
+  type: :development
+  version_requirements: *id002
 description: Bookland is an ISBN class in Ruby.
 email: code@papercavalier.com
 executables: []
@@ -47,17 +63,16 @@ files:
 - .rspec
 - .rvmrc
 - Gemfile
-- Gemfile.lock
 - History.md
 - LICENSE
 - README.md
 - Rakefile
-- VERSION
 - bookland.gemspec
 - lib/bookland.rb
 - lib/bookland/isbn.rb
 - lib/bookland/version.rb
 - spec/bookland/isbn_spec.rb
+- spec/bookland_spec.rb
 - spec/fixtures/isbn
 - spec/spec_helper.rb
 has_rdoc: true
@@ -96,5 +111,6 @@ specification_version: 3
 summary: An ISBN class in Ruby
 test_files: 
 - spec/bookland/isbn_spec.rb
+- spec/bookland_spec.rb
 - spec/fixtures/isbn
 - spec/spec_helper.rb

data/Gemfile.lock

@@ -1,24 +0,0 @@
-PATH
-  remote: .
-  specs:
-    bookland (1.0.0)
-
-GEM
-  remote: http://rubygems.org/
-  specs:
-    diff-lcs (1.1.2)
-    rspec (2.5.0)
-      rspec-core (~> 2.5.0)
-      rspec-expectations (~> 2.5.0)
-      rspec-mocks (~> 2.5.0)
-    rspec-core (2.5.1)
-    rspec-expectations (2.5.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.5.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bookland!
-  rspec (~> 2.5.0)

data/VERSION

@@ -1 +0,0 @@
-0.3.1