marcspec 1.5.0 → 1.6.1

data/lib/marcspec/solrfieldspec.rb

@@ -2,10 +2,19 @@ require 'stringio'
 require 'marc4j4r/controlfield'
 
 module MARCSpec
+  
+  
+  # The basic Solr Field spec -- a specification object that knows how to extract data
+  # from a MARC record.
+  
   class SolrFieldSpec
+    include Logback::Simple
+    
     attr_accessor :solrField, :first, :map, :noMapKeyDefault, :marcfieldspecs, :defaultValue,  :_mapname
     attr_reader :arity
 
+    # Get a new object
+    
     def initialize(opts)
       @solrField  = opts[:solrField]
       @first = opts[:firstOnly] || false      
@@ -16,11 +25,19 @@ module MARCSpec
       @marcfieldspecs = []
     end
 
+    # Add a new tag specification
+    # @param [MARCSpec::ControlFieldSpec, MARCSpec::VariableFieldSpec] tagspec The spec to add
+    
     def << tagspec
       @marcfieldspecs << tagspec
     end
 
-
+    # Get raw (not translated by a map or anything) values from the MARC
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Hash, SolrInputDocument] doc The hash-like object that contains previously-generated content
+    # @return [Array] an array of values from the MARC record
+    
     def raw_marc_values r, doc
       vals = []
       @marcfieldspecs.each do |ts|
@@ -28,7 +45,13 @@ module MARCSpec
       end
       return vals
     end
-      
+    
+    # Get the values from the MARC, provide a default or mapping as necessary
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Hash, SolrInputDocument] doc The hash-like object that contains previously-generated content
+    # @return [Array] an array of values from the MARC record after mapping/default/mapMissDefault/firstOnly
+ 
     def marc_values r, doc = {}
       vals = raw_marc_values r, doc
       return vals if @arity > 1
@@ -64,6 +87,9 @@ module MARCSpec
       return vals
     end
     
+    # Basic equality
+    # @param [MARCSpec::SolrFieldSpec] other The other object to compare to
+    # @return [Boolean] whether it's the same
     
     def == other
       return ((other.solrField == self.solrField) and
@@ -74,10 +100,15 @@ module MARCSpec
              (other.marcfieldspecs == self.marcfieldspecs))
     end
     
+    # Build an object from a asPPString string
+    # @deprecated Use the DSL
     def self.fromPPString str
       return self.fromHash eval(str)
     end
     
+    # Build an object from an eval'd asPPString string
+    # @deprecated Use the DSL
+    
     def self.fromHash h
       sfs = self.new(h)
       h[:specs].each do |s|
@@ -90,10 +121,43 @@ module MARCSpec
       return sfs
     end
     
+    # Output as a ruby hash
+    # @deprecated Use the DSL
+        
     def pretty_print pp
       pp.pp eval(self.asPPString)
     end
     
+    # Create a string representation suitable for inclusion in a DSL file
+    # @return [String] a DSL snippet
+    def asDSLString
+      s = StringIO.new
+      s.puts "field('#{@solrField}') do"
+      s.puts "  firstOnly" if @first
+      if @defaultValue
+        s.puts "  default " + 
+        PP.singleline_pp(@defaultValue + "\n", s)
+      end
+      if @map
+        s.print "  mapname "
+        PP.pp(@map.mapname, s)
+      end
+      if @noMapKeyDefault
+        s.print("  mapMissDefault ")
+        PP.singleline_pp(@noMapKeyDefault, s)
+        s.print("\n ")
+      end
+      @marcfieldspecs.each do |spec|
+        s.puts "  " + spec.asDSLString
+      end
+      s.puts "end"
+      return s.string
+    end
+      
+      
+    # Output as a string representation of a ruby hash
+    # @deprecated Use the DSL
+    
     def asPPString
       s = StringIO.new
       s.print "{\n :solrField=> "

data/lib/marcspec/specset.rb

@@ -26,20 +26,37 @@ module MARCSpec
   end
   
   
-
+  # A collection of the solr field specifications and maps necessary to turn a MARC record
+  # into a set of key=>value pairs suitable for sending to Solr
+  
   class SpecSet
+    include Logback::Simple
+    
     attr_accessor :tmaps, :solrfieldspecs, :benchmarks
     
+    # Generic new
     def initialize
       @tmaps = {}
       @solrfieldspecs = []
       @benchmarks = {}
     end
     
+    # Get the map object associated with the given name
+    # @param [String] name The name of the map you want
+    # @return [MARCSpec::Map, nil] Either the map or nil (if not found)
+    
     def map name
       return self.tmaps[name]
     end
     
+    # Get all the *.rb files in a directory, assume they're maps, and create entries for
+    # them in self
+    #
+    # Simple wrapper around MARCSpec::Map#fromFile. Note that if a mapname is not found
+    # in the map structure, the name of the file (without the trailing '.rb') will be used.
+    #
+    # @param [String] dir The directory to look in. Not recursive.
+    
     def loadMapsFromDir dir
       unless File.exist? dir
         raise ArgumentError, "Cannot load maps from #{dir}: does not exist"
@@ -50,15 +67,26 @@ module MARCSpec
     end
     
   
-    
+    # Add a map to self, using its name (map#mapname) as a key
+    # @param [MARCSpec::Map] map the map to add.
     def add_map map
       self.tmaps[map.mapname] = map
     end
     
+    # Build up a specset from the configuration in the given DSL file
+    # Note that this assumes that the maps have already been loaded!!
+    #
+    # @param [String, IO] f The name of the file, or an open IO object
+    # @return [MARCSpec::SpecSet] the new object
+    
     
-    def buildSpecsFromDSLFile file
-      f = File.open(file)
-      $LOG.fatal("Can't open file #{file}") unless f
+    def buildSpecsFromDSLFile f
+      f = File.open(f) if f.is_a? String
+
+      unless f
+        log.fatal("Can't open file #{file}") 
+        Process.exit
+      end
       self.instance_eval(f.read)
       self.check_and_fill_maps
     end
@@ -68,11 +96,10 @@ module MARCSpec
         if sfs._mapname
           map = self.map(sfs._mapname)
           if map
-            $LOG.debug "  Found map #{map.mapname} for solr field #{sfs.solrField}"
+            log.debug "  Found map #{map.mapname} for solr field #{sfs.solrField}"
             sfs.map = map
           else
-            $LOG.error "  Cannot find map #{sfs._mapname} for solr field #{sfs.solrField}"
-            STDERR.puts "FATAL  Cannot find map #{sfs._mapname} for solr field #{sfs.solrField}"
+            log.fatal "  Cannot find map #{sfs._mapname} for solr field #{sfs.solrField}"
             Process.exit
           end
         end
@@ -80,6 +107,8 @@ module MARCSpec
     end
       
     
+    # Build a specset from the result of eval'ing an old-style pp hash. 
+    # @deprecated Use the DSL
     
     def buildSpecsFromList speclist
       speclist.each do |spechash|
@@ -93,19 +122,23 @@ module MARCSpec
         if spechash[:mapname]
           map = self.map(spechash[:mapname])
           unless map
-            $LOG.error "  Cannot find map #{spechash[:mapname]} for field #{spechash[:solrField]}"
+            log.fatal "Cannot find map #{spechash[:mapname]} for field #{spechash[:solrField]}"
             Process.exit
           else
-            $LOG.debug "  Found map #{spechash[:mapname]} for field #{spechash[:solrField]}"
+            log.debug "  Found map #{spechash[:mapname]} for field #{spechash[:solrField]}"
             solrspec.map = map
           end
         end
         self.add_spec solrspec
-        $LOG.debug "Added spec #{solrspec.solrField}"
+        log.debug "Added spec #{solrspec.solrField}"
       end
     end
       
     
+    # Add a spec, making sure there's a slot in the benchmarking stats to keep track of it
+    #
+    # @param [MARCSpec::SolrFieldSpec] solrfieldspec The spec to add
+
     def add_spec solrfieldspec
       self.solrfieldspecs << solrfieldspec
       @benchmarks[solrfieldspec.solrField.to_s] = Benchmark::Tms.new(0,0,0,0, 0, solrfieldspec.solrField)      
@@ -113,12 +146,24 @@ module MARCSpec
     
     alias_method :<<, :add_spec
 
+
+    # Iterate over each of the solr field specs
     def each
       @solrfieldspecs.each do |fs|
         yield fs
       end
     end
     
+    # Fill a hashlike (either a hash or a SolrInputDocument) based on 
+    # the specs, maps, and passed-in record. 
+    #
+    # Result is the hashlike getting new data added to it. Nothing is returned; it's all
+    # side-effects.
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Hash, SolrInputDocument] hashlike The hash-like object that contains previously-generated content
+
+    
     def fill_hashlike_from_marc r, hashlike
       @solrfieldspecs.each do |sfs|
         if sfs.arity == 1
@@ -131,6 +176,14 @@ module MARCSpec
         end
       end
     end
+    
+    # Same as #fill_hashlike_from_marc, but keeps track of how
+    # long each solr field takes (cumulative; it's added to every
+    # time you get data from a record). 
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Hash, SolrInputDocument] hashlike The hash-like object that contains previously-generated content
+    
 
     def fill_hashlike_from_marc_benchmark r, hashlike
       @solrfieldspecs.each do |sfs|
@@ -148,6 +201,14 @@ module MARCSpec
     end
 
 
+    # Get a new SolrInputDocument based on the record passed in.
+    # Statistics will optionally be kept, and can be accessed
+    # via the @benchmarks intance varible later on.
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Boolean] timeit Whether to keep cumulative benchmarking statistics or not
+    # @return [SolrInputDocument] Thew new, filled SolrInputDocument    
+
     def doc_from_marc r, timeit = false
       doc = SolrInputDocument.new
       if timeit
@@ -158,6 +219,13 @@ module MARCSpec
       return doc
     end      
     
+    # Exactly the same as #doc_from_marc, but the return object is a 
+    # subclass of Hash
+    #
+    # @param [MARC4J4R::Record] r The record
+    # @param [Boolean] timeit Whether to keep cumulative benchmarking statistics or not
+    # @return [MockSolrDoc] Thew new, filled Hash    
+    
     def hash_from_marc r, timeit = false
       h = MARCSpec::MockSolrDoc.new
       if timeit

data/lib/marcspec/variablefieldspec.rb

@@ -14,22 +14,43 @@ module MARCSpec
   # vfs =  MARCSpec::VariableFieldSpec.new('245', 'a'..'b')
   
   class VariableFieldSpec
-
+    include Logback::Simple
+    
     attr_accessor :tag, :codes, :joiner, :ind1, :ind2, :codehistory
 
+    # Get a new object
+    #
+    # @param [String] tag The MARC field tag
+    # @param [String, Array] codes The list of subfield codes (as 'abc' or ['a', 'b', 'c']) whose values we want
+    # @param [String] joiner What string to use to join the subfield values
+    # @return [VariableFieldSpec] the new object
+    
     def initialize tag, codes=nil, joiner=' '
       @tag = tag
       @joiner = joiner || ' '
       self.codes = codes
       @codehistory = []
     end
-
+    
+    # Basic equality
+    # @param [VariableFieldSpec] other The other spec
+    # @return [Boolean] whether or not it matches in all values
+    
     def == other
       return ((self.tag == other.tag) and
               (self.codes = other.codes) and
               (self.joiner = other.joiner))
     end
 
+    
+    # Set the list of subfield codes we're concerned with. 
+    # Internally, we always store this as an array. For input, accept
+    # an array of single-letter codes, a string of codes like 'abjk09',
+    # or a range like 'a'..'z'. nil means to use all the subfields
+    #
+    # @param [String, Array<String>, Range<String>, nil] c The code(s) to use
+    # @return [Array] the new set of codes
+    
     def codes= c
       @codehistory << @codes if @codes
       if c.nil?
@@ -37,7 +58,7 @@ module MARCSpec
         return nil
       end
 
-      if( c.is_a? Array) or (c.is_a? Set) or (c.is_a? Range)
+      if( c.is_a? Array) or (c.is_a? Range)
         @codes = c.to_a
       else
         @codes = c.split(//)
@@ -46,6 +67,11 @@ module MARCSpec
       return @codes
     end
 
+    # Get the values associated with the tag (and optional subfield codes) for the given record
+    #
+    # @param [MARC4J4R::Record] r The record you want to extract values from
+    # @return [Array<String>] the extracted values, if any
+    
     def marc_values r
       fields = r.find_by_tag(@tag)
       vals = []
@@ -58,10 +84,30 @@ module MARCSpec
       return vals
     end
 
+
+    # Get a DSL snipped representing this object
+    # @return [String] the DSL string
+    
+    def asDSLString
+      subs = @codes.join('')
+      if subs.size > 0
+        # return "spec('#{@tag}') {subs '#{subs}'}"
+        return "spec('#{tag}#{subs}')"
+      else
+        return "spec('#{@tag}')"
+      end
+    end
+      
+        
+    # Print out hash version of this object
+    # @deprecated Use the DSL
     def pretty_print pp
       pp.pp eval(self.asPPString)
     end
-
+    
+    # Create a eval'able string of a hash version of this object
+    # @deprecated Use the DSL
+    
     def asPPString
       s = StringIO.new
       if @joiner and @joiner != ' '
@@ -72,6 +118,8 @@ module MARCSpec
       return s.string
     end
 
+   # Create an object from an asPPString string
+   # @deprecated Use the DSL
    def self.fromPPString str
      a = eval(str)
      return self.new(a[0], a[1], a[2])

data/spec/cachespot_spec.rb

@@ -25,6 +25,6 @@ describe "Cachespot" do
   
   it "should set a value and get it back" do
     @one.cachespot['one'] = 1
-    @one.cachespot['one'].should.equal 1
+    @one.cachespot['one'].should ==  1
   end
 end

data/spec/controlfieldspec_spec.rb

@@ -29,23 +29,23 @@ describe "ControlFieldSpec" do
   # 01234567890123 # index
   it "gets a single full value" do
     cfs = MARCSpec::ControlFieldSpec.new('001')
-    cfs.marc_values(@one).should.equal ["afc99990058366"]    
+    cfs.marc_values(@one).should == ["afc99990058366"]    
   end
   
   it "gets a single character" do
     cfs = MARCSpec::ControlFieldSpec.new('001', 10 )
-    cfs.marc_values(@one).should.equal ['8']
+    cfs.marc_values(@one).should == ['8']
   end
   
   it "gets a range of characters" do
     cfs = MARCSpec::ControlFieldSpec.new('001', 6..10 )
-    cfs.marc_values(@one).should.equal ['90058']
+    cfs.marc_values(@one).should == ['90058']
   end
   
   it "should round trip" do
     cfs = MARCSpec::ControlFieldSpec.new('001', 6..10 )
     cfs2 = MARCSpec::ControlFieldSpec.fromPPString(cfs.asPPString)
-    cfs.should.equal cfs2
+    cfs.should == cfs2
   end    
 end