libis-tools 0.9.20 → 0.9.21

data/lib/libis/tools/metadata/dublin_core_record.rb

@@ -6,10 +6,17 @@ module Libis
   module Tools
     module Metadata
 
+      # Conveniece class to create and read DC records.
+      # Most of the functionality is derived from the {::Libis::Tools::XmlDocument} base class. This class puts its
+      # focus on supporting the <dc:xxx> and <dcterms:xxx> namespaces. For most tags the namespaces are added
+      # automatically by checking which tag you want to add. In some cases the same tag exists in both namespaces and
+      # you may want to state the namespace explicitely. Even then things are made as easily as possible.
       class DublinCoreRecord < Libis::Tools::XmlDocument
 
+        # List of known tags in the DC namespace
         DC_ELEMENTS = %w'contributor coverage creator date description format identifier language' +
             %w'publisher relation rights source subject title type'
+        # List of known tags in the DCTERMS namespace
         DCTERMS_ELEMENTS = %w'abstract accessRights accrualMethod accrualPeriodicity accrualPolicy alternative' +
             %w'audience available bibliographicCitation conformsTo contributor coverage created creator date' +
             %w'dateAccepted dateCopyrighted dateSubmitted description educationLevel extent format hasFormat' +
@@ -18,6 +25,11 @@ module Libis
             %w'references relation replaces requires rights rightsHolder source spatial subject tableOfContents' +
             %w'temporal title type valid'
 
+        # Create new DC document.
+        # If the doc parameter is nil a new empty DC document will be created with the dc:record root element and all
+        # required namespaces defined.
+        # @note The input document is not checked if it is a valid DC record XML.
+        # @param [::Libis::Tools::XmlDocument,String,IO,Hash] doc optional document to read.
         def initialize(doc = nil)
           super()
           xml_doc = case doc
@@ -45,10 +57,9 @@ module Libis
           raise ArgumentError, 'XML document not valid.' if self.invalid?
         end
 
-        def all
-          @all_records ||= get_all_records
-        end
-
+        # Search the document with xpath.
+        # If no namespace is present, the 'dc:' namespace will be added.
+        # @param [String] path any valid XPath expression
         def xpath(path)
           m = /^([\/.]*\/)?(dc(terms)?:)?(.*)/.match(path.to_s)
           return [] unless m[4]
@@ -56,6 +67,13 @@ module Libis
           @document.xpath(path.to_s)
         end
 
+        # Add a node.
+        # You can omit the namespace in the name parameter. The method will add the correct namespace for you. If using
+        # symbols for name, an underscore ('_') can be used as separator instead of the colon (':').
+        # @param [String,Symbol] name tag name of the element
+        # @param [String] value content of the new element
+        # @param [Nokogiri::XML::Node] parent the new element will be attached to this node
+        # @param [Hash] attributes list of <attribute_name>, <attribute_value> pairs for the new element
         def add_node(name, value = nil, parent = nil, attributes = {})
           ns, tag = get_namespace(name.to_s)
           (attributes[:namespaces] ||= {})[:node_ns] ||= ns if ns

data/lib/libis/tools/metadata/field_format.rb

@@ -4,18 +4,56 @@ module Libis
   module Tools
     module Metadata
 
+      # Helper class for formatting field data.
+      #
+      # The FieldFormat class can omit prefix and or postfix if no data is present and omits the join string if only
+      # one data element is present.
       class FieldFormat
 
+        # [Array] the list that makes up the data
         attr_accessor :parts
+
+        # [String] the text that will be placed in front of the generated text
         attr_accessor :prefix
-        attr_accessor :join
+
+        # [String] the text that will be placed at the end of the generated text
         attr_accessor :postfix
 
+        # [String] the text used between the parts of the data
+        attr_accessor :join
+
+        # Create new formatter
+        #
+        # The method takes any number of arguments and processes them as data parts. If the last one is a Hash, it is
+        # interpreted as options hash. The data parts can either be given as an Array or set of arguments or within the
+        # options hash with key +:parts+.
+        #
+        # On each element in the data set the formatter will call the #to_s method to
+        # give each data object the opportunity to process it's data.
+        #
+        # @param [Array, Hash] parts whatever makes up the data to be formatted.
         def initialize(*parts)
           @parts = []
           self[*parts]
         end
 
+        # Parses the arguments, stripping of an optional last Hash as options.
+        # @param (see #initialize)
+        def [](*parts)
+          options = parts.last.is_a?(Hash) ? parts.pop : {}
+          add parts
+          x = options.delete(:parts)
+          add x if x
+          add_options options
+        end
+
+        # Set options.
+        #
+        # Besides the tree options +:prefix+, +:postfix+ and +:join+ it also accepts the option +:fix+. This combines
+        # both +:prefix+ and +:postfix+ options by specifying "<prefix>|<postfix>". If both prefix and postfix are only
+        # 1 character wide the format "<prefix><postfix>" is also allowed.
+        #
+        # @param [Hash] options the options list
         def add_options(options = {})
           if options[:fix]
             if options[:fix].size == 2
@@ -30,6 +68,10 @@ module Libis
           self
         end
 
+        # Add default options.
+        # (see #add_options)
+        # None of these options will be set if they are already set. If you need to overwrite them, use {#add_options}.
+        # @param (see #add_options)
         def add_default_options(options = {})
           options.delete(:prefix) if @prefix
           options.delete(:postfix) if @postfix
@@ -38,18 +80,14 @@ module Libis
           add_options options
         end
 
-        def [](*parts)
-          options = parts.last.is_a?(Hash) ? parts.pop : {}
-          add parts
-          x = options.delete(:parts)
-          add x if x
-          add_options options
-        end
-
+        # Shortcut class method for initializer
         def self.from(*h)
           self.new(*h)
         end
 
+        # The real formatter method.
+        # This method parses the data and applies the options to generate the formatted string.
+        # @return [String] the formatter string
         def to_s
           @parts.delete_if { |x|
             x.nil? or
@@ -63,6 +101,8 @@ module Libis
           result
         end
 
+        protected
+
         def add(part)
           case part
             when Hash

data/lib/libis/tools/metadata/fix_field.rb

@@ -4,16 +4,21 @@ module Libis
   module Tools
     module Metadata
 
+      # Helper class for implementing a fixed field for MARC
       class FixField
 
         attr_reader :tag
         attr_accessor :datas
 
+        # Create new fixed field
+        # @param [String] tag tag
+        # @param [String] datas field data
         def initialize(tag, datas)
           @tag = tag
           @datas = datas || ''
         end
 
+
         def [](from = nil, to = nil)
           return @datas unless from
           to ? @datas[from..to] : @datas[from]

data/lib/libis/tools/metadata/mapper.rb

@@ -8,8 +8,9 @@ require_relative 'parsers'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class Mapper
 
         attr_reader :target_parser, :selection_parser, :format_parser

data/lib/libis/tools/metadata/mappers/flandrica.rb

@@ -8,8 +8,15 @@ module Libis
       module Mappers
 
         # noinspection RubyResolve
+
+        # Mixin for {::Libis::Tools::Metadata::MarcRecord} to enable conversion into
+        # {Libis::Tools::Metadata::DublinCoreRecord}. This module implements the conversion mapping for Flandrica by
+        # extending the version for {::Libis::Tools::Metadata::Mappers::Kuleuven KU Leuven} and overwriting what's
+        # different. This means any change to the KU Leuven mapping may have effect on this mapping as well.
         module Flandrica
-          include Libis::Tools::Metadata::Mappers::Kuleuven
+          extend Libis::Tools::Metadata::Mappers::Kuleuven
+
+          protected
 
           def marc2dc_identifier(xml)
             Libis::Tools::Metadata::Mappers::Kuleuven.marc2dc_identifier(xml)

data/lib/libis/tools/metadata/mappers/kuleuven.rb

@@ -8,10 +8,15 @@ module Libis
   module Tools
     module Metadata
       module Mappers
-
         # noinspection RubyResolve
+
+        # Mixin for {::Libis::Tools::Metadata::MarcRecord} to enable conversion into
+        # {Libis::Tools::Metadata::DublinCoreRecord}. This module implements the conversion mapping for KU Leuven.
         module Kuleuven
 
+          # Main conversion method.
+          # @param [String] label optional extra identified to add to the DC record.
+          # @return [::Libis::Tools::Metadata::DublinCoreRecord]
           def to_dc(label = nil)
             assert(self.is_a? Libis::Tools::Metadata::MarcRecord)
 
@@ -1400,7 +1405,6 @@ module Libis
             if DOLLAR4TABLE[data.tag].has_key? code
               return DOLLAR4TABLE[data.tag][code][1]
             end
-            Application.logger.warn(self.class) { "Did not find $4 value in lookuptable: #{data.dump_line}" }
             :contributor
           end
 

data/lib/libis/tools/metadata/marc21_record.rb

@@ -8,6 +8,7 @@ module Libis
   module Tools
     module Metadata
 
+      # This class implements the missing private method 'get_all_records' to accomodate for the MARC-XML format.
       class Marc21Record < Libis::Tools::Metadata::MarcRecord
 
         private

data/lib/libis/tools/metadata/marc_record.rb

@@ -85,11 +85,19 @@ module Libis
 
         alias_method :each_tag, :all_tags
 
+        # Get all fields matching search criteria.
+        # As {#all_tags} but without subfield criteria.
+        # @param [String] tag Tag selection string. Tag name with indicators, '#' for wildcard, '_' for blank. If an
+        #     extra subfield name is added, a result will be created for each instance found of that subfield.
+        # @param [Proc] select_block block that will be executed once for each field found. The block takes one argument
+        #     (the field) and should return true or false. True selects the field, false rejects it.
+        # @return [Array] If a block was supplied to the method call, the array will contain the result of the block
+        #     for each tag found. Otherwise the array will just contain the data for each matching tag.
         def select_fields(tag, select_block = nil, &block)
           all_tags(tag, nil, select_block, &block)
         end
 
-        # Find the first field matching the criteria.
+        # Find the first tag matching the criteria.
         #
         # If a block is supplied, it will be called with the found field data. The return value will be whatever the
         # block returns. If no block is supplied, the field data will be returned. If nothing was found, the return
@@ -105,34 +113,43 @@ module Libis
           yield result
         end
 
+        # Find all fields matching the criteria.
+        # (see #first_tag)
+        # @param (see #first_tag)
         def all_fields(tag, subfields)
-          r = all_tags(tag, subfields).collect { |tag| tag.subfields_array(subfields) }.flatten.compact
+          r = all_tags(tag, subfields).collect { |t| t.subfields_array(subfields) }.flatten.compact
           return r unless block_given?
           r.map { |field| yield field }
           r.size > 0
         end
 
-        def first_field(t, s)
-          result = all_fields(t, s).first
+        # Find the first field matching the criteria
+        # (see #all_fields)
+        # @param (see #all_fields)
+        def first_field(tag, subfields)
+          result = all_fields(tag, subfields).first
           return result unless block_given?
           return false unless result
           yield result
           true
         end
 
-
-        def each_field(t, s)
-          all_fields(t, s).each do |field|
+        # Perform action on each field found. Code block required.
+        # @param (see #all_fields)
+        def each_field(tag, subfields)
+          all_fields(tag, subfields).each do |field|
             yield field
           end
         end
 
+        # Dump content to string.
         def marc_dump
           all.values.flatten.each_with_object([]) { |record, m| m << record.dump }.join
         end
 
+        # Save the current MARC record to file.
+        # @param [String] filename name of the file
         def save(filename)
-
           doc = ::Libis::Tools::XmlDocument.new
           doc.root = @node
 
@@ -142,23 +159,25 @@ module Libis
                                ::Nokogiri::XML::Node::SaveOptions::AS_XML |
                                ::Nokogiri::XML::Node::SaveOptions::FORMAT
                            )
-
         end
 
+        # Load XML document from file and create a new {MarcRecord} for it.
+        # @param [String] filename name of XML Marc file
         def self.load(filename)
-
           doc = ::Libis::Tools::XmlDocument.open(filename)
           self.new(doc.root)
-
         end
 
+        # Load XML document from stream and create a new {MarcRecord} for it.
+        # @param [IO,String] io input stream
         def self.read(io)
           io = StringIO.new(io) if io.is_a? String
           doc = ::Libis::Tools::XmlDocument.parse(io)
           self.new(doc.root)
-
         end
 
+        # Dump Marc record in Aleph Sequential format
+        # @return [String] Aleph sequential output
         def to_aseq
           record = ''
           doc_number = tag('001').datas

data/lib/libis/tools/metadata/parser/basic_parser.rb

@@ -7,6 +7,8 @@ module Libis
   module Tools
     module Metadata
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class BasicParser < Parslet::Parser
         # space
         rule(:space) { match('\s') }

data/lib/libis/tools/metadata/parser/dublin_core_parser.rb

@@ -7,8 +7,9 @@ require_relative 'basic_parser'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class DublinCoreParser < Libis::Tools::Metadata::BasicParser
         rule(:namespace) { match('[^:]').repeat(1).as(:namespace) >> str(':') }
         rule(:namespace?) { namespace.maybe }

data/lib/libis/tools/metadata/parser/marc21_parser.rb

@@ -8,8 +8,9 @@ require_relative 'marc_rules'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class Marc21Parser < Libis::Tools::Metadata::BasicParser
 
         root(:marc21)

data/lib/libis/tools/metadata/parser/marc_format_parser.rb

@@ -8,8 +8,9 @@ require_relative 'marc_rules'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class MarcFormatParser < Libis::Tools::Metadata::BasicParser
         include Libis::Tools::Metadata::MarcRules
 

data/lib/libis/tools/metadata/parser/marc_rules.rb

@@ -5,8 +5,9 @@ require 'parslet'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       module MarcRules
         include Parslet
 

data/lib/libis/tools/metadata/parser/marc_select_parser.rb

@@ -8,8 +8,9 @@ require_relative 'marc_rules'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class MarcSelectParser < Libis::Tools::Metadata::BasicParser
         include Libis::Tools::Metadata::MarcRules
         root(:MARC)

data/lib/libis/tools/metadata/parser/patch.rb

@@ -1,3 +1,4 @@
+# New style parsers and converters for metadata. New, not finished and untested.
 class Parslet::Pattern
 
   def element_match_hash(tree, exp, bindings)

data/lib/libis/tools/metadata/parser/subfield_criteria_parser.rb

@@ -7,8 +7,9 @@ require_relative 'basic_parser'
 module Libis
   module Tools
     module Metadata
-
       # noinspection RubyResolve
+
+      # New style parsers and converters for metadata. New, not finished and untested.
       class SubfieldCriteriaParser < Libis::Tools::Metadata::BasicParser
 
         root(:criteria)

data/lib/libis/tools/metadata/sharepoint_mapping.rb

@@ -8,6 +8,7 @@ require 'libis/tools/extend/hash'
 module Libis
   module Tools
 
+    # Copy of old Sharepoint mapping class. Needs inspection and probably a mayor update.
     class SharepointMapping < Hash
 
       def initialize(mapping_file)

data/lib/libis/tools/metadata/sharepoint_record.rb

@@ -9,6 +9,8 @@ module Libis
   module Tools
 
     # noinspection RubyTooManyMethodsInspection
+
+    # Copy of the old SharepointRecord class. Needs inspection and probably a mayor update.
     class SharepointRecord < Hash
 
       attr_accessor :node