isbn-tools 0.1.0

data/ChangeLog

@@ -0,0 +1,6 @@
+
+= ISBN-Tools Change Log
+
+== ISBN-Tools 0.1.0: 2006-09-28
+* Initial release
+

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright 2006, Thierry Godfroid
+
+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 name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
+
+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

@@ -0,0 +1,60 @@
+== ISBN-Tools for Ruby
+
+This library provides the ability to manipulate ISBN numbers.
+It knows about ISBN-10 and ISBN-13 numbers, has the ability to
+check if they are valid and convert from one format to the other.
+It can, of course, compute the check digit of both formats.
+
+Finally, it has the ability to hyphenate ISBN numbers for the
+following group identifiers: 0, 1 and 2.  Note that only hyphenation
+methods need to know about ranges, so all others methods (validity, 
+checksum computations and number conversions) can be used with ISBN 
+numbers from any group.
+
+Other ranges could be added on request but I would need samples
+ISBN to check the result.
+
+== Usage
+
+  require 'rubygems'
+  require 'isbn/tools'
+
+  isbn_good = "2800107766"
+  isbn_bad = "2810107766"
+
+  def check_and_hyphenate(isbn)
+    if ISBN_Tools.is_valid?(isbn)
+      puts ISBN_Tools.hyphenate(isbn)
+    else
+      cksum = ISBN_Tools.compute_check_digit(isbn)
+      puts "Invalid ISBN number [#{isbn}]. Checksum should be #{cksum}"
+    end
+  end
+
+  check_and_hyphenate isbn_good # => 2-8001-0776-6
+  check_and_hyphenate isbn_bad  # => Invalid ISBN number [2810107766]. Checksum should be 9
+
+== Copyright
+
+Copyright:: 2006, Thierry Godfroid
+
+The following sources were used in order to understand ISBN numbers and
+how to manipulate them. No books were harmed in the process.
+- http://www.isbn-international.org
+- "Are You Ready for ISBN-13?" http://www.isbn.org/standards/home/isbn/transition.asp. Note that at the bottom of this page, you can find a link towards a small book "ISBN-13 for Dummies", available as PDF (http://www.bisg.org/isbn-13/ISBN13_For_Dummies.pdf)
+- Structure of an ISBN number http://www.isbn.org/standards/home/isbn/international/html/usm4.htm
+
+Ranges information was found at http://www.isbn-international.org/en/identifiers.html.
+
+== LICENCE NOTE
+
+MIT-Style license. See LICENCE file in this distribution.
+
+== Requirements
+
+ISBN-Tools requires Ruby 1.8.2 or better.
+
+== Known bugs/Limitations
+
+- This release code only allows for one-digit groups.
+- See also the TODO file in this distribution

data/TODO

@@ -0,0 +1,8 @@
+== TODO list
+- Handle groups which number of digit is > 1
+- Add all known ranges for all groups
+- Proof read comments
+- Add samples to comments
+- Make sure that library follows Ruby rules (layout, naming ...)
+- Add more tests (there are never enough, I'm told)
+

data/data/ranges.dat

@@ -0,0 +1,3 @@
+0,00..19,200..699,7000..8499,85000..89999,900000..949999,9500000..9999999
+1,00..09,100..399,4000..5499,55000..86979,869800..998999
+2,00..19,200..349,35000..39999,400..699,7000..8399,84000..89999,900000..949999,9500000..9999999

data/lib/isbn/tools.rb

@@ -0,0 +1,173 @@
+#--
+# Copyright 2006, Thierry Godfroid
+# 
+# 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 name of the author may not be used to endorse or promote products derived
+# 	from this software without specific prior written permission.
+# 
+# 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.
+#++
+
+# This module provides all the methods of the ISBN-Tools library.
+# Methods have no state but the library reads the file data/ranges.dat
+# and fills up the RNG hash when loaded.
+module ISBN_Tools
+	# Supported groups and associated ranges. Data is read from data/ranges.dat
+	# (provided in gem) at module load.
+	RNG = {}
+
+	File.open(File.join(File.dirname(__FILE__), "../../data/ranges.dat")) do |file|
+		file.each do |line|
+			line.chomp!
+			break if line.empty?
+			ar_line = line.split(/,/)
+			ndx = ar_line.delete_at(0)
+			RNG[ndx] = []
+			ar_line.each { |item| 
+				r = item.split(/\.\./)
+				RNG[ndx].push(Range.new(r[0],r[1]))
+			}
+		end
+	end
+
+	# Clear all useless characters from an ISBN number and upcase the 'X' sign when
+	# present.  Also does the basic check that 'X' must be the last sign of the number,
+	# if present.  Returns nil if provided string is nil or X is not at the last position.
+	#
+	# No length check is done: no matter what string is passed in, all characters that
+	# not in the range [0-9xX] are removed.
+	def ISBN_Tools.cleanup(isbn_)
+		isbn_.gsub(/[^0-9xX]/,'').gsub(/x/,'X') unless isbn_.nil? or isbn_.scan(/([xX])/).length > 1
+	end
+	
+	# Same as cleanup but alters the argument.
+	def ISBN_Tools.cleanup!(isbn_)
+		isbn_.replace(cleanup(isbn_))
+	end
+
+	# Check that the value is a valid ISBN-10 number. Returns true if it is, false otherwise.
+	# The method will check that the number is exactly 10 digits long and that the tenth digit is
+	# the correct checksum for the number.
+	def ISBN_Tools.is_valid_isbn10?(isbn_)
+		isbn = cleanup(isbn_)
+		return false if isbn.nil? or isbn.match(/^[0-9]{9}[0-9X]$/).nil?
+		sum = 0;
+		0.upto(9) { |ndx| sum += (isbn[ndx]!= 88 ? isbn[ndx].chr.to_i : 10) * (10-ndx) } # 88 is ascii of X
+		sum % 11 == 0
+	end
+
+	# Check that the value is a valid ISBN-13 number. Returns true if it is, false otherwise.
+	# The method will check that the number is exactly 13 digits long and that the thirteenth digit is
+	# the correct checksum for the number.
+	def ISBN_Tools.is_valid_isbn13?(isbn_)
+		isbn = cleanup(isbn_)
+		return false if isbn.nil? or isbn.length!=13 or isbn.match(/^97[8|9][0-9]{10}$/).nil?
+		sum = 0
+		0.upto(12) { |ndx| sum += isbn[ndx].chr.to_i * (ndx % 2 == 0 ? 1 : 3) }
+		sum.remainder(10) == 0
+	end
+
+	# Check that an ISBN is valid or not. Returns true if is, false otherwise.  This method will
+	# first call is_valid_isbn10() and, on failure, try is_valid_isbn13().  Returns true if it is
+	# a valid number, false otherwise.
+	# This method is handy if you don't want to be bothered by checking the length of your
+	# isbn before checking its validity. It is a bit slower since cleanup will be called twice.
+	def ISBN_Tools.is_valid?(isbn_)
+		is_valid_isbn10?(isbn_) || is_valid_isbn13?(isbn_)
+	end
+
+	# Computes the check digit of an ISBN-10 number.  It will ignore the tenth sign if present
+	# and accepts a number with only 9 digits.  Returns the checksum digit or nil.  Please note
+	# that the checksum digit of an ISBN-10 may be the character 'X'.
+	def ISBN_Tools.compute_isbn10_check_digit(isbn_)
+		isbn = cleanup(isbn_)
+		return nil if isbn.nil? or isbn.length > 10 or isbn.length < 9
+		sum = 0; 
+		0.upto(8) { |ndx| sum += isbn[ndx].chr.to_i * (10-ndx) }
+		(11-sum) % 11 == 10 ? "X" : ((11-sum) % 11).to_s
+	end
+
+	# Computes the check digit of an ISBN-13 number.  It will ignore the thirteenth sign if present
+	# and accepts a number with only 12 digits.  Returns the checksum digit or nil.  Please note
+	# that the checksum digit of an ISBN-13 is always in the range [0-9].
+	def ISBN_Tools.compute_isbn13_check_digit(isbn_)
+		isbn = cleanup(isbn_)
+		return nil if isbn.nil? or isbn.length > 13 or isbn.length < 12
+		sum = 0
+		0.upto(11) { |ndx| sum += isbn[ndx].chr.to_i * (ndx % 2 == 0 ? 1 : 3) }
+		(10-sum.remainder(10)) == 10 ? "0" : (10-sum.remainder(10)).to_s
+	end
+
+	# Compute the check digit of an ISBN number. Try as an ISBN-10 number
+	# first, and if it failed, as an ISBN-13 number. Returns the check digit or
+	# nil if a processing error occured.
+	# This method is a helper for compute_isbn10_check_digit and
+	# compute_isbn13_check_digit.
+	def ISBN_Tools.compute_check_digit(isbn_)
+			compute_isbn10_check_digit(isbn_) || compute_isbn13_check_digit(isbn_)
+	end
+
+	# Convert an ISBN-10 number to its equivalent ISBN-13 number.  Returns the converted number or nil
+	# if the provided ISBN-10 number is nil or non valid.
+	def ISBN_Tools.isbn10_to_isbn13(isbn_)
+		isbn = cleanup(isbn_)
+		"978" + isbn[0..8] + compute_isbn13_check_digit("978" + isbn[0..8]) unless isbn.nil? or ! is_valid_isbn10?(isbn)
+	end
+
+	# Convert an ISBN-13 number to its equivalent ISBN-10 number.  Returns the converted number or nil
+	# if the provided ISBN-13 number is nil or non valid. Please note that only ISBN-13 numbers starting
+	# with 978 can be converted.
+	def ISBN_Tools.isbn13_to_isbn10(isbn_)
+		isbn = cleanup(isbn_)
+		isbn[3..11] +  compute_isbn10_check_digit(isbn[3..11]) unless isbn.nil? or ! is_valid_isbn13?(isbn) or ! isbn_.match(/^978.*/)
+	end
+
+	# Hyphenate a valid ISBN-10 number.  Returns nil if the number is invalid or if the group range is 
+	# unknown.  Works only for groups 0,1 and 2.
+	def ISBN_Tools.hyphenate_isbn10(isbn_)
+		isbn = cleanup(isbn_)
+		group = isbn[0..0]
+		if RNG.has_key?(group) and is_valid_isbn10?(isbn)
+			RNG[group].each { |r| return isbn.sub(Regexp.new("(.{1})(.{#{r.last.length}})(.{#{8-r.last.length}})(.)"),'\1-\2-\3-\4') if r.member?(isbn[1..r.last.length]) }
+		end
+	end
+
+	# Hyphenate a valid ISBN-13 number.  Returns nil if the number is invalid or if the group range is 
+	# unknown.   Works only for groups 0,1 and 2.
+	def ISBN_Tools.hyphenate_isbn13(isbn_)
+		isbn = cleanup(isbn_)
+		if is_valid_isbn13?(isbn)
+			group = isbn[3..3]
+			if RNG.has_key?(group)
+				RNG[group].each { |r| return isbn.sub(Regexp.new("(.{3})(.{1})(.{#{r.last.length}})(.{#{8-r.last.length}})(.)"),'\1-\2-\3-\4-\5') if r.member?(isbn[1..r.last.length]) }
+			end
+		end
+	end
+
+	# This method takes an ISBN then tries to hyphenate it as an ISBN 10 then an ISBN 13.  A bit slower
+	# than calling the right one directly but saves you the length checking. Returns an hyphenated value
+	# or nil.
+	def ISBN_Tools.hyphenate(isbn_)
+		hyphenate_isbn10(isbn_) || hyphenate_isbn13(isbn_)
+	end
+
+	# Same as hyphenate() but alters the argument.
+	def ISBN_Tools.hyphenate!(isbn_)
+		isbn_.replace(hyphenate(isbn_))
+	end
+
+end

data/tests/tc_isbn_tools_tests.rb

@@ -0,0 +1,105 @@
+require "rubygems"
+require "test/unit"
+require "isbn/tools"
+
+class TC_ISBN_Tools_Tests < Test::Unit::TestCase
+	def setup
+	end
+	
+	def teardown
+	end
+
+	def testing
+		# ISBN 10 inputs
+		isbn_orig_ok = "0-8436-1072-7"
+		isbn_orig_bad = "0-8436-1072-x"
+		# both values taken from: http://www.isbn.org/standards/home/isbn/transition.asp
+		isbn_1_10 = "1-56619-909-3"
+		isbn_1_13 = "978-1-56619-909-4"
+		isbn_1_13b = "978-1-56619-909-x" # wrong check digit
+		isbn_2_13 = "979-1-56619-909-3" # same as isbn_1_13 but altered with 979 and valid cksum
+		isbn_3_10 = "2-930088-49-4" #unusually small (?) editor: good for hyphen testing!
+
+		isbn_4_10 = "4413008480" # japanese ISBN (I think, ... At least, it validates.)
+
+		isbn = ""
+
+		# check that cleanup works
+		assert_equal(true, "0843610727".eql?(ISBN_Tools.cleanup(isbn_orig_ok)))
+		# and does not alter provided argument
+		assert_equal("0-8436-1072-7",isbn_orig_ok)
+		# test that cleanup! does alter the original string
+		isbn.replace(isbn_orig_ok)
+		ISBN_Tools.cleanup!(isbn)
+		assert_equal("0843610727", isbn)
+		# grrr .. Nte to self: make sure that isbn was not setup as a simple reference to  
+		#			isbn_orig_ok otherwise it will also be altered. Use replace as above.
+		assert_equal("0-8436-1072-7",isbn_orig_ok)
+		# test that X is upper cased (even on bad numbers)
+		assert_equal(true, "084361072X".eql?(ISBN_Tools.cleanup(isbn_orig_bad)))
+
+		# test that it is a valid isbn 10 number
+		assert_equal(true, ISBN_Tools.is_valid_isbn10?(isbn_orig_ok))
+		assert_equal(true, ISBN_Tools.is_valid_isbn10?(isbn_4_10))
+		# test that it is NOT a valid isbn 10 number
+		assert_equal(false, ISBN_Tools.is_valid_isbn10?(isbn_orig_bad))
+		assert_equal(false, ISBN_Tools.is_valid_isbn10?(isbn_1_13))
+		# same as the two tests above but via the generic is_valid? method. Must have identical result.
+		assert_equal(true, ISBN_Tools.is_valid?(isbn_orig_ok))
+		assert_equal(false, ISBN_Tools.is_valid?(isbn_orig_bad))
+		# test that it is NOT a valid isbn 13 number
+		assert_equal(false, ISBN_Tools.is_valid_isbn13?(isbn_orig_bad))
+		# test that it is a valid isbn 13 number
+		assert_equal(true, ISBN_Tools.is_valid_isbn13?(isbn_1_13))
+		# same as the two tests above but via the generic is_valid? method. Must have identical result.
+		assert_equal(true, ISBN_Tools.is_valid?(isbn_1_13))
+		assert_equal(false, ISBN_Tools.is_valid?(isbn_1_13b))
+		# test that check digit is indeed 7
+		assert_equal("7",ISBN_Tools.compute_isbn10_check_digit(isbn_orig_ok))
+		# test must also succeed on isbn_orig_bad since only the check digit changes
+		# 	and it must not be considered in the computation
+		assert_equal("7",ISBN_Tools.compute_isbn10_check_digit(isbn_orig_bad))
+		# test check digit of isbn 13 number. Must be 4
+		assert_equal("4",ISBN_Tools.compute_isbn13_check_digit(isbn_1_13))
+		# test must also succeed on isbn_orig_bad since only the check digit changes
+		# 	and it must not be considered in the computation
+		assert_equal("4",ISBN_Tools.compute_isbn13_check_digit(isbn_1_13b))
+		# test the wrapper, once for ISBN10 and once for ISBN13
+		assert_equal("7",ISBN_Tools.compute_check_digit(isbn_orig_ok))
+		assert_equal("4",ISBN_Tools.compute_check_digit(isbn_1_13))
+
+		# verify hyphenation from cleanup version
+		assert_equal(isbn_orig_ok, ISBN_Tools.hyphenate_isbn10(isbn_orig_ok))
+		assert_equal(isbn_1_10, ISBN_Tools.hyphenate_isbn10(isbn_1_10))
+		assert_equal(isbn_3_10, ISBN_Tools.hyphenate_isbn10(isbn_3_10))
+		assert_equal(isbn_3_10, ISBN_Tools.hyphenate_isbn10(isbn_3_10))
+		# fail on hyphenating a non group 0/1/2 ISBN
+		assert_equal(nil, ISBN_Tools.hyphenate_isbn10(isbn_4_10))
+		# fail on hyphenating an invalid isbn
+		assert_equal(nil, ISBN_Tools.hyphenate_isbn10(isbn_orig_bad))
+		# on isbn 13
+		assert_equal(isbn_1_13,ISBN_Tools.hyphenate_isbn13(isbn_1_13))
+		# same result with cleanup up one
+		assert_equal(isbn_1_13,ISBN_Tools.hyphenate_isbn13(ISBN_Tools.cleanup(isbn_1_13)))
+		# check the generic method
+		assert_equal(isbn_1_13,ISBN_Tools.hyphenate(isbn_1_13))
+		assert_equal(isbn_1_10, ISBN_Tools.hyphenate(isbn_1_10))
+		assert_equal(nil, ISBN_Tools.hyphenate(isbn_4_10))
+		# check that hyphenate! alters the argument
+		isbn.replace(isbn_1_10)
+		ISBN_Tools.cleanup!(isbn)
+		assert_equal(isbn_1_10,ISBN_Tools.hyphenate!(isbn))
+		assert_equal(isbn,isbn_1_10)
+
+		# test conversion from 10 to 13
+		assert_equal(ISBN_Tools.cleanup(isbn_1_13), ISBN_Tools.isbn10_to_isbn13(isbn_1_10))
+		# test conversion from 13 to 10
+		assert_equal(ISBN_Tools.cleanup(isbn_1_10), ISBN_Tools.isbn13_to_isbn10(isbn_1_13))
+		# test illegal conversion from 13 to 10 (should return nil because of the 979)
+		assert_equal(nil, ISBN_Tools.isbn13_to_isbn10(isbn_2_13))
+
+	end
+end
+
+require 'test/unit/ui/console/testrunner'
+Test::Unit::UI::Console::TestRunner.run(TC_ISBN_Tools_Tests)

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: isbn-tools
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-09-28 00:00:00 +02:00
+summary: A series of methods to manipulate ISBN numbers.
+require_paths: 
+- lib
+email: ""
+homepage: http://
+rubyforge_project: isbn-tools
+description: ""
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Thierry GODFROID
+files: 
+- README
+- LICENCE
+- TODO
+- ChangeLog
+- lib/isbn/tools.rb
+- data/ranges.dat
+test_files: 
+- tests/tc_isbn_tools_tests.rb
+rdoc_options: 
+- --title
+- ISBN-Tools
+- --main
+- README
+- --line-numbers
+extra_rdoc_files: 
+- README
+- ChangeLog
+- LICENCE
+- TODO
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+