marc 0.7.0 → 0.7.1

data/lib/marc/record.rb

@@ -39,6 +39,14 @@ module MARC
         yield tag
       end
     end
+
+    # Freeze for immutability, first reindexing if needed. 
+    # A frozen FieldMap is safe for concurrent access, and also
+    # can more easily avoid accidental reindexing on even read-only use. 
+    def freeze
+      self.reindex unless @clean
+      super
+    end
   end
 
   # A class that represents an individual MARC record. Every record
@@ -50,12 +58,39 @@ module MARC
   #   record.find_all {|field| field.tag =~ /^6../}  
   # 
   # The accessor 'fields' is also an Array of MARC::DataField objects which
-  # the client can access or modifyi if neccesary.
+  # the client can access or modify if neccesary.
   #
   #   record.fields.delete(field)
   # 
   # Other accessor attribute: 'leader' for record leader as String
- 
+  #
+  # == High-performance lookup by tag
+  #
+  # A frequent use case is looking up fields in a MARC record by tag, such
+  # as 'all the 500 fields'.  Certain methods can use a hash keyed by
+  # tag name for higher performance lookup by tag.  The hash is lazily
+  # created on first access -- there is some cost of creating the hash,
+  # testing shows you get a performance advantage to using the hash-based
+  # methods if you are doing at least a dozen lookups.
+  #
+  #     record.fields("500")  # returns an array
+  #     record.each_by_tag("500") {|field| ... }
+  #     record.fields(['100', '700'])   # can also use an array in both methods
+  #     record.each_by_tag( 600..699 )  # or a range
+  #
+  # == Freezing for thread-safety and high performance
+  #
+  # MARC::Record is not generally safe for sharing between threads.
+  # Even if you think you are just acccessing it read-only,
+  # you may accidentally trigger a reindex of the by-tag cache (see above). 
+  #
+  # However, after you are done constructing a Record, you can mark
+  # the `fields` array as immutable. This makes a Record safe for sharing
+  # between threads for read-only use, and also helps you avoid accidentally
+  # triggering a reindex, as accidental reindexes can harm by-tag
+  # lookup performance. 
+  #
+  #     record.fields.freeze
   class Record
     include Enumerable
 
@@ -126,7 +161,10 @@ module MARC
     # in the order they appear in the record.
     def fields(filter=nil)
       unless filter
-        @fields.clean = false
+        # Since we're returning the FieldMap object, which the caller
+        # may mutate, we precautionarily mark dirty -- unless it's frozen
+        # immutable. 
+        @fields.clean = false unless @fields.frozen?
         return @fields 
       end
       @fields.reindex unless @fields.clean

data/lib/marc/version.rb

@@ -1,3 +1,3 @@
 module MARC
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

data/lib/marc/writer.rb

@@ -131,7 +131,7 @@ module MARC
         if allow_oversized
           formatted = sprintf("%0#{num_digits}i", 0)
         else
-          raise MARC::Exception.new("Can't write MARC record, as length/offset value of #{number} is too long for the #{num_digits} slot in binary format.")
+          raise MARC::Exception.new("Can't write MARC record in binary format, as a length/offset value of #{number} is too long for a #{num_digits}-byte slot.")
         end
       end
       return formatted

data/test/tc_record.rb

@@ -119,4 +119,39 @@ class TestRecord < Test::Unit::TestCase
       assert_equal(five_hundreds.last['a'], 'Composer and program notes in container.')
     end
 
+
+    # Some tests for the internal FieldMap hash, normally
+    # an implementation detail, but things get tricky and we need
+    # tests to make sure we're good. Some of these you might
+    # change if you change FieldMap caching implementation or contract/API. 
+    def test_direct_change_dirties_fieldmap
+      # if we ask for #fields directly, and mutate it
+      # with it's own methods, does any cache update?
+      r = MARC::Record.new
+      assert r.fields('500').empty? 
+      r.fields.push MARC::DataField.new('500', ' ', ' ', ['a', 'notes'])
+      assert ! r.fields('500').empty?, "New 505 directly added to #fields is picked up"
+
+      # Do it again, make sure #[] works too
+      r = MARC::Record.new
+      assert r['500'].nil?
+      r.fields.push MARC::DataField.new('500', ' ', ' ', ['a', 'notes'])
+      assert r['500'], "New 505 directly added to #fields is picked up"
+    end
+
+    def test_frozen_fieldmap
+      r = MARC::Record.new
+      r.fields.push MARC::DataField.new('500', ' ', ' ', ['a', 'notes'])
+
+      r.fields.freeze
+
+      r.fields.inspect
+      r.fields
+      assert ! r.fields('500').empty?
+
+      assert r.fields.instance_variable_get("@clean"), "FieldMap still marked clean"
+
+    end
+
+
 end

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: marc
 version: !ruby/object:Gem::Version
-  version: 0.7.0
-  prerelease: 
+  prerelease:
+  version: 0.7.1
 platform: ruby
 authors:
 - Kevin Clarke
@@ -13,14 +13,15 @@ authors:
 autorequire: marc
 bindir: bin
 cert_chain: []
-date: 2013-09-03 00:00:00.000000000 Z
+date: 2013-09-09 00:00:00.000000000 Z
 dependencies: []
-description: 
+description:
 email: ehs@pobox.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/marc.rb
 - lib/marc/constants.rb
 - lib/marc/controlfield.rb
 - lib/marc/datafield.rb
@@ -35,7 +36,6 @@ files:
 - lib/marc/xml_parsers.rb
 - lib/marc/xmlreader.rb
 - lib/marc/xmlwriter.rb
-- lib/marc.rb
 - test/batch.dat
 - test/batch.xml
 - test/cp866_multirecord.marc
@@ -71,27 +71,28 @@ files:
 - Changes
 - LICENSE
 homepage: https://github.com/ruby-marc/ruby-marc/
-licenses: []
-post_install_message: 
+licenses:
+- MIT
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: 1.8.6
-required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
+  none: false
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
-signing_key: 
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
 specification_version: 3
 summary: A ruby library for working with Machine Readable Cataloging
 test_files: