library_stdnums 1.0.0 → 1.0.1

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Bill Dueber
+Copyright (c) 2010-2011 Bill Dueber
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -9,40 +9,41 @@ See the actual functions for more information than what's below.
 ## ISBN
 
 ````ruby
-  isbn = StdNum::ISBN.normalize(goodISBN)
-    # => a 13-digit ISBN with no dashes/spaces
+
+      isbn = StdNum::ISBN.normalize(goodISBN)
+        # => a 13-digit ISBN with no dashes/spaces
     
-  isbn = StdNum::ISBN.normalize(badISBN)
-    # => nil (if it's not an ISBN or the checkdigit is bad)
+      isbn = StdNum::ISBN.normalize(badISBN)
+        # => nil (if it's not an ISBN or the checkdigit is bad)
   
-  tenDigit = StdNum::ISBN.convert_to_10(isbn13)
-  thirteenDigit = StdNum::ISBN.convert_to_13(isbn10)
+      tenDigit = StdNum::ISBN.convert_to_10(isbn13)
+      thirteenDigit = StdNum::ISBN.convert_to_13(isbn10)
   
-  thirteenDigit,tenDigit = StdNum::ISBN.allNormalizedValues(issn)
-    # => array of the ten and thirteen digit isbns if valid; 
-    #    an empty array if not
+      thirteenDigit,tenDigit = StdNum::ISBN.allNormalizedValues(issn)
+        # => array of the ten and thirteen digit isbns if valid; 
+        #    an empty array if not
   
-  digit = StdNum::ISBN.checkdigit(isbn)
-    # => 0..9 (for isbn13) or 0..9,X (for isbn10)
+      digit = StdNum::ISBN.checkdigit(isbn)
+        # => 0..9 (for isbn13) or 0..9,X (for isbn10)
   
-  if StdNum::ISBN.valid?(isbn)
-    puts "#{isbn} has a valid checkdigit"
-  end
+      if StdNum::ISBN.valid?(isbn)
+        puts "#{isbn} has a valid checkdigit"
+      end
   
 ````
 
 # ISSN
 
 ````ruby
-  issn = StdNum::ISSN.normalize(issn)
-  #  => the cleaned-up issn if valid; nil if not
+      issn = StdNum::ISSN.normalize(issn)
+      #  => the cleaned-up issn if valid; nil if not
   
-  digit = StdNum::ISSN.checkdigit(issn)
-  #  => 0..9 or X
+      digit = StdNum::ISSN.checkdigit(issn)
+      #  => 0..9 or X
 
-  if StdNum::ISSN.valid?(issn)
-    puts "#{issn} has a valid checkdigit"
-  end
+      if StdNum::ISSN.valid?(issn)
+        puts "#{issn} has a valid checkdigit"
+      end
 ````
   
 # LCCN
@@ -51,15 +52,16 @@ LCCNs are normalized according to the algorithm at http://www.loc.gov/marc/lccn-
 
 ````ruby
 
-  lccn = StdNum::LCCN.normalize(rawlccn)
-  #  => either the normalized lccn, or nil if it has bad syntax
-  
-  if StdNum::LCCN.valid?(rawlccn) {
-    puts "#{rawlccn} is valid"
-  }
+      lccn = StdNum::LCCN.normalize(rawlccn)
+      #  => either the normalized lccn, or nil if it has bad syntax
+
+      if StdNum::LCCN.valid?(rawlccn) {
+        puts "#{rawlccn} is valid"
+      }
+
 ````
 
-== CHANGES
+## CHANGES
 
 * 1.0.0
   * Added normalization all around. 
@@ -77,7 +79,7 @@ LCCNs are normalized according to the algorithm at http://www.loc.gov/marc/lccn-
 * 0.1.0 
   * Initial release
 
-== Note on Patches/Pull Requests
+## Note on Patches/Pull Requests
  
 * Fork the project.
 * Make your feature addition or bug fix.
@@ -87,6 +89,6 @@ LCCNs are normalized according to the algorithm at http://www.loc.gov/marc/lccn-
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-== Copyright
+## Copyright
 
-Copyright (c) 2010 Bill Dueber. See LICENSE for details.
+Copyright (c) 2010, 2011 Bill Dueber. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/lib/library_stdnums.rb

@@ -1,17 +1,29 @@
+# Static Module functions to work with library "standard numbers" ISSN, ISBN, and LCCN
 module StdNum
-    
+  
+  # Helper methods common to ISBN/ISSN
   module Helpers
     
+    # The pattern we use to try and find an ISBN/ISSN. Ditch everthing before the first
+    # digit, then take all the digits/hyphens, optionally followed by an 'X'
     STDNUMPAT = /^.*?(\d[\d\-]+[xX]?)/
 
     # Extract the most likely looking number from the string. This will be the first
     # string of digits-and-hyphens-and-maybe-a-trailing-X, with the hypens removed
+    # @param [String] str The string from which to extract an ISBN/ISSN
+    # @return [String] The extracted identifier
     def extractNumber str
       match = STDNUMPAT.match str
       return nil unless match
       return match[1].gsub(/\-/, '').upcase
     end
     
+    # Given any string, extract what looks like the most likely ISBN/ISSN
+    # of the given size(s), or nil if nothing matches at the correct size.
+    # @param [String] rawnum The raw string containing (hopefully) an ISSN/ISBN
+    # @param [Integer, Array<Integer>, nil] An integer or array of integers of valid sizes
+    # for this type (e.g., 10 or 13 for ISBN, 8 for ISSN)
+    # @return [String,nil] the reduced and verified number, or nil if there's no match at the right size
     def reduce_to_basics rawnum, valid_sizes = nil
       return nil if rawnum.nil?
       
@@ -33,7 +45,7 @@ module StdNum
     end
   end
     
-
+  # Validate, convert, and normalize ISBNs (10-digit or 13-digit)
   module ISBN
     extend Helpers
   
@@ -84,7 +96,6 @@ module StdNum
     # For an ISBN normalizing it is the same as converting to ISBN 13
     # and making sure it's valid
     # @param [String] isbn The ISBN to normalize
-    # @param [Boolean] passthrough On failure, return the original passed-in value instead of nil
     # @return [String, nil] the normalized (to 13 digit) ISBN, or nil on failure
     def self.normalize rawisbn
       isbn = convert_to_13 rawisbn
@@ -137,8 +148,6 @@ module StdNum
     # @example Get the normalized values and index them (if valid) or original value (if not)
     #   norms = StdNum::ISBN.allNormalizedValues(rawisbn)
     #   doc['isbn'] = norms ? norms : [rawisbn]
-    
-    
     def self.allNormalizedValues isbn
       isbn = reduce_to_basics isbn, [10,13]
       return [] unless isbn
@@ -153,6 +162,7 @@ module StdNum
     
   end
   
+  # Validate and and normalize ISSNs
   module ISSN
     extend Helpers
     
@@ -188,6 +198,11 @@ module StdNum
       return issn[-1..-1] == self.checkdigit(issn, true)
     end
     
+    
+    
+    # Make sure it's valid, remove the dashes, uppercase the X, and return
+    # @param [String] isbn The ISBN to normalize
+    # @return [String, nil] the normalized (to 13 digit) ISBN, or nil on failure
     def self.normalize rawissn
       issn = reduce_to_basics rawissn, 8
       if issn and valid?(issn, true)
@@ -201,6 +216,7 @@ module StdNum
     
   end
   
+  # Validate and and normalize LCCNs
   module LCCN
     
     # The rules for validity according to http://www.loc.gov/marc/lccn-namespace.html#syntax:

metadata

@@ -2,7 +2,7 @@
 name: library_stdnums
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors: 
 - Bill Dueber