metacrunch-marcxml 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 108b2f6697c4cc1fd07f61231da1a5b0219e7fe1
+  data.tar.gz: 8ca7bdf5edc53577c1dd700e00af500b388bb386
+SHA512:
+  metadata.gz: 80c1d9f509ee566035a76f62429662fd524d4f123b50a303776aea4e301479ad41c380e89f9622d3063b96733fec6fdaf72b4ce146ca027a7ef07836dc6e55b1
+  data.tar.gz: dd1abb2e6f24dd197ffdcb3b8e1b774d127d9b5a3fc13cb7e464f5e6fcb1ffa83f8054bef2a132ce4fed31236333947d6be3970d6047b59621a38417c1616bab

data/.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+/doc
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - ruby-2.3.3
+  - ruby-2.4.0
+addons:
+  code_climate:
+    repo_token: edec9ede0a6915474955b4afc932be887f09bcd5257433adc79a13ef3451f36d
+after_success:
+  - bundle exec codeclimate-test-reporter

data/.yardopts

@@ -0,0 +1,9 @@
+--no-cache
+--no-output
+--verbose
+--markup markdown
+--markup-provider redcarpet
+--asset doc/images:images
+--readme Readme.md
+--hide-void-return
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,17 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "bundler", ">= 1.15"
+  gem "rake",    ">= 12.1"
+  gem "rspec",   ">= 3.5.0", "< 4.0.0"
+
+  if !ENV["CI"]
+    gem "pry-byebug", ">= 3.5.0"
+  end
+end
+
+group :test do
+  gem "simplecov", ">= 0.15.0"
+end

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2017 René Sprotte
+
+MIT License
+
+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 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/Rakefile

@@ -0,0 +1,6 @@
+require "rspec/core/rake_task"
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/Readme.md

@@ -0,0 +1,92 @@
+metacrunch-marcxml
+==================
+
+[![Build Status](https://travis-ci.org/ubpb/metacrunch-marcxml.svg)](https://travis-ci.org/ubpb/metacrunch-marcxml)
+[![Code Climate](https://codeclimate.com/github/ubpb/metacrunch-marcxml/badges/gpa.svg)](https://codeclimate.com/github/ubpb/metacrunch-marcxml)
+
+This is the official [MARCXML](http://www.loc.gov/standards/marcxml/) package for the [metacrunch ETL toolkit](https://github.com/ubpb/metacrunch). It allows you to access MARCXML data by a simple and powerful Ruby API.
+
+There is no runtime dependency to metacrunch, so it's fine to use this gem in any Ruby application where you need to access MARCXML data.
+
+*Note: Before 2.0 this package was incorrectly named `metacrunch-mab2` and has been renamed to `metacrunch-marcxml`. Due to this renaming and further development there are breaking API changes if you upgrade from 1.x to 2.x.*
+
+
+Installation
+------------
+
+Include the gem in your `Gemfile`
+
+```ruby
+gem "metacrunch-marcxml", "~> 2.0.0"
+```
+
+and run `$ bundle install` to install it.
+
+Or install it manually
+
+```
+$ gem install metacrunch-marcxml
+```
+
+
+Usage example
+-------------
+
+**Loading the library**
+```ruby
+require "metacrunch/marcxml"
+```
+
+**Parsing a [MARCXML file](http://d-nb.info/982392028/about/marcxml)**
+```ruby
+# Load a MARCXML file (from a remote location in this example).
+require "open-uri"
+marcxml = open("http://d-nb.info/982392028/about/marcxml"){|io| io.read}
+
+# Now parse the file
+document = Metacrunch::Marcxml.parse(marcxml)
+# .. or use the convenience method
+document = Metacrunch::Marcxml(marcxml)
+```
+
+**Accessing control fields**
+```ruby
+controlfield = document.controlfield("005")
+# same as ...
+controlfield = document.controlfield(5)
+# => #<Metacrunch::Marcxml::Document::Controlfield:0x007fd4c5120ec0 ...>
+
+tag = controlfield.tag
+# => "005"
+value = controlfield.value
+# => "20130926112144.0"
+```
+
+**Accessing data fields / sub fields**
+```ruby
+# Find fields matching tag=100 and indicator1=1 (author)
+datafield_set = document.datafields(100, ind1: "1")
+# => #<Metacrunch::Marcxml::Document::DatafieldSet:0x007fd4c4ce4b40 ...>
+
+first_author = datafield_set.first # set is an Enumerable
+# => #<Metacrunch::Marcxml::Document::Datafield:0x007fd4c5129480 ...>
+
+# Get the subfields matching code=a (author name)
+subfield_set = first_author.subfields("a")
+# => #<Metacrunch::Marcxml::Document::SubfieldSet:0x007fd4c4c779f0 ...>
+
+# because sub field "a" is not repeatable we know there can only be one match
+first_author_subfield = subfield_set.first # subfield_set is an Enumerable
+# => #<Metacrunch::Marcxml::Document::Subfield:0x007fd4c5129660 ...>
+
+first_author_name = first_author_subfield.value
+# => "Orwell, George"
+
+# ... there is a shortcut for this case
+first_author_name = document.datafields(100, ind1: "1").subfields("a").first_value
+```
+
+License
+-------
+
+metacrunch-marcxml is available at [github](https://github.com/ubpb/metacrunch-marcxml) under [MIT license](https://github.com/ubpb/metacrunch-marcxml/blob/master/License.txt).

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "metacrunch/marcxml"
+
+begin
+  require "pry"
+rescue LoadError ; end
+
+if defined?(Pry)
+  Pry.start
+else
+  require "irb"
+  IRB.start
+end

data/lib/metacrunch/marcxml/document/controlfield.rb

@@ -0,0 +1,17 @@
+module Metacrunch
+  module Marcxml
+    class Document
+      class Controlfield
+
+        attr_reader :tag
+        attr_reader :value
+
+        def initialize(tag, value)
+          @tag = tag
+          @value = value
+        end
+
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/document/datafield.rb

@@ -0,0 +1,50 @@
+module Metacrunch
+  module Marcxml
+    class Document
+      class Datafield
+
+        attr_reader :tag
+        attr_reader :ind1, :ind2
+
+        def initialize(tag, ind1:nil, ind2:nil)
+          @tag  = tag
+          @ind1 = ind1
+          @ind2 = ind2
+          @subfields_map = {}
+        end
+
+        #
+        # Returns the sub fields matching the given code.
+        #
+        # @param [String, nil, Array<String>] code of the sub field
+        # @return [Metacrunch::Marcxml::Document::SubfieldSet] sub field with the given code. The set
+        #  is empty if the sub field doesn't exists.
+        #
+        def subfields(code = nil)
+          matched_subfields = if code.nil?
+            @subfields_map.values.flatten(1)
+          else
+            if (codes = code).is_a?(Array)
+              codes.map{ |_code| @subfields_map[_code] }.compact.flatten(1)
+            else
+              @subfields_map[code]
+            end
+          end
+
+          SubfieldSet.new(matched_subfields)
+        end
+
+        #
+        # Adds a new sub field.
+        #
+        # @param [Metacrunch::Marcxml::Document::Subfield] subfield
+        #
+        def add_subfield(subfield)
+          (@subfields_map[subfield.code] ||= []) << subfield
+          subfield
+        end
+
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/document/datafield_set.rb

@@ -0,0 +1,39 @@
+module Metacrunch
+  module Marcxml
+    class Document
+      class DatafieldSet
+        include Enumerable
+
+        def initialize(datafields)
+          @datafields = datafields || []
+        end
+
+        def each(&block)
+          @datafields.each(&block)
+        end
+
+        def to_a
+          @datafields
+        end
+
+        def empty?
+          @datafields.empty?
+        end
+
+        def present?
+          !empty?
+        end
+
+        # @return [Metacrunch::Marcxml::Document::SubfieldSet]
+        def subfields(code = nil)
+          subfields = @datafields.map do |datafield|
+            datafield.subfields(code).to_a
+          end.flatten(1)
+
+          Metacrunch::Marcxml::Document::SubfieldSet.new(subfields)
+        end
+
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/document/subfield.rb

@@ -0,0 +1,17 @@
+module Metacrunch
+  module Marcxml
+    class Document
+      class Subfield
+
+        attr_reader :code
+        attr_reader :value
+
+        def initialize(code, value)
+          @code  = code
+          @value = value
+        end
+
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/document/subfield_set.rb

@@ -0,0 +1,42 @@
+module Metacrunch
+  module Marcxml
+    class Document
+      class SubfieldSet
+        include Enumerable
+
+        def initialize(subfields)
+          @subfields = subfields || []
+        end
+
+        def each(&block)
+          @subfields.each(&block)
+        end
+
+        def to_a
+          @subfields
+        end
+
+        def empty?
+          @subfields.empty?
+        end
+
+        def present?
+          !empty?
+        end
+
+        def values
+          @subfields.map{ |subfield| subfield.value }
+        end
+
+        def present_values
+          values.map{ |v| v.presence }.compact
+        end
+
+        def first_value
+          present_values[0]
+        end
+
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/document.rb

@@ -0,0 +1,111 @@
+require_relative "document/controlfield"
+require_relative "document/datafield"
+require_relative "document/datafield_set"
+require_relative "document/subfield"
+require_relative "document/subfield_set"
+
+module Metacrunch
+  module Marcxml
+    class Document
+
+      def initialize
+        @controlfields_map = {}
+        @datafields_map    = {}
+      end
+
+      # ------------------------------------------------------------------------------
+      # Control fields
+      # ------------------------------------------------------------------------------
+
+      #
+      # Returns the control field matching the given tag or nil if a control field
+      # with the given tag does not exist.
+      #
+      # @param tag [String, Integer] the tag of the control field. The tag can be
+      #   a string or an integer.
+      # @return [Controlfield, nil] the control field with the matching tag or nil
+      #   if a control field with a matching tag does not exist.
+      #
+      def controlfield(tag)
+        @controlfields_map[normalize_tag(tag)]
+      end
+
+      #
+      # @!visibility private
+      #
+      def add_controlfield(controlfield)
+        @controlfields_map[controlfield.tag] = controlfield
+      end
+
+      # ------------------------------------------------------------------------------
+      # Data fields
+      # ------------------------------------------------------------------------------
+
+      #
+      # Returns the data fields matching the given tag(s) and/or ind1/ind2.
+      #
+      # @param tag [String, Integer, #each, nil] filter by tag(s). Can be `nil`
+      #   to match all data fields. The tag can be a string or an integer. To filter for
+      #   more than a single tag, `tag` also accepts any object that responds to `#each` like
+      #   `Array` and `Range`.
+      #
+      # @param ind1 [String, nil, Array<String>] filter by indicator 1. Can be nil to match
+      #   any indicator.
+      # @param ind2 [String, nil, Array<String>] filter by indicator 2. Can be nil to match
+      #   any indicator.
+      #
+      # @return [Metacrunch::Marcxml::Document::DatafieldSet] Set of data fields matching the
+      #  given tag(s) and ind1/ind2. The set is empty if a matching field doesn't exist.
+      #
+      def datafields(tag = nil, ind1: nil, ind2: nil)
+        matched_datafields = case tag
+        when nil
+          @datafields_map.values.flatten(1)
+        when Enumerable
+          tag.map{ |_tag| @datafields_map[normalize_tag(_tag)] }.compact.flatten(1)
+        else
+          @datafields_map[normalize_tag(tag)]
+        end
+
+        matched_datafields = (matched_datafields || []).select do |datafield|
+          match_indicator(ind1, datafield.ind1) && match_indicator(ind2, datafield.ind2)
+        end
+
+        DatafieldSet.new(matched_datafields)
+      end
+
+      #
+      # @!visibility private
+      #
+      def add_datafield(datafield)
+        (@datafields_map[datafield.tag] ||= []) << datafield
+        datafield
+      end
+
+    private
+
+      def match_indicator(requested_ind, datafield_ind)
+        [*[requested_ind]].flatten.map do |_requested_ind|
+          if !_requested_ind
+            true
+          elsif _requested_ind == :blank && (datafield_ind == " " || datafield_ind == "-" || datafield_ind.nil?)
+            true
+          elsif _requested_ind == datafield_ind
+            true
+          else
+            false
+          end
+        end.any?
+      end
+
+      def normalize_tag(tag)
+        case tag
+        when Integer then tag.to_s.rjust(3, "0")
+        when String  then tag
+        else tag.to_s
+        end
+      end
+
+    end
+  end
+end

data/lib/metacrunch/marcxml/parser.rb

@@ -0,0 +1,81 @@
+module Metacrunch
+  module Marcxml
+    class Parser < Ox::Sax
+
+      def parse(mab_xml)
+        # initialize state machine
+        @in_controlfield = @in_datafield = @in_subfield = false
+
+        @controlfield = @datafield = @subfield = nil
+        @document = Document.new
+        @html_entities_coder = HTMLEntities.new
+
+        # convert_special tells ox to convert some html entities already during
+        # parsing, which minifies the amount of entities we have to decode ourself
+        Ox.sax_parse(self, mab_xml, convert_special: true)
+
+        return @document
+      end
+
+      def start_element(name)
+        if name == :subfield
+          @in_subfield = true
+          @subfield = {}
+        elsif name == :datafield
+          @in_datafield = true
+          @datafield = {subfields: []}
+        elsif name == :controlfield
+          @in_controlfield = true
+          @controlfield = {}
+        end
+      end
+
+      def end_element(name)
+        if @in_subfield
+          @in_subfield = false
+
+          subfield = Document::Subfield.new(@subfield[:code], @subfield[:value])
+          @datafield[:subfields] << subfield
+        elsif @in_datafield
+          @in_datafield = false
+
+          datafield = Document::Datafield.new(@datafield[:tag], ind1: @datafield[:ind1], ind2: @datafield[:ind2])
+          @datafield[:subfields].each do |subfield|
+            datafield.add_subfield(subfield)
+          end
+
+          @document.add_datafield(datafield)
+        elsif @in_controlfield
+          @in_controlfield = false
+
+          controlfield = Document::Controlfield.new(@controlfield[:tag], @controlfield[:values])
+          @document.add_controlfield(controlfield)
+        end
+      end
+
+      def attr(name, value)
+        if @in_subfield
+          @subfield[:code] = value if name == :code
+        elsif @in_datafield
+          if name == :tag
+            @datafield[:tag] = value
+          elsif name == :ind1
+            @datafield[:ind1] = value
+          elsif name == :ind2
+            @datafield[:ind2] = value
+          end
+        elsif @in_controlfield
+          @controlfield[:tag] = value if name == :tag
+        end
+      end
+
+      def text(value)
+        if @in_subfield
+          @subfield[:value] = value.include?("&") ? @html_entities_coder.decode(value) : value
+        elsif @in_controlfield
+          @controlfield[:values] = value
+        end
+      end
+    end
+  end
+end

data/lib/metacrunch/marcxml/version.rb

@@ -0,0 +1,5 @@
+module Metacrunch
+  module Marcxml
+    VERSION = "2.0.0"
+  end
+end

data/lib/metacrunch/marcxml.rb

@@ -0,0 +1,38 @@
+require "active_support"
+require "active_support/core_ext"
+require "htmlentities"
+require "ox"
+
+module Metacrunch
+  require_relative "marcxml/version"
+  require_relative "marcxml/parser"
+  require_relative "marcxml/document"
+
+  class << self
+    #
+    # Convenience method for Metacrunch::Marcxml.parse
+    #
+    # @return [Metacrunch::Marcxml::Document] the parsed {Metacrunch::Marcxml::Document}
+    # @see Metacrunch::Marcxml#parse
+    #
+    def Marcxml(xml)
+      Metacrunch::Marcxml.parse(xml)
+    end
+  end
+
+
+  module Marcxml
+    class << self
+      #
+      # Parses a MARCXML string into a {Metacrunch::Marcxml::Document}.
+      #
+      # @param xml [String] the MARCXML document as a string
+      # @return [Metacrunch::Marcxml::Document] the parsed {Metacrunch::Marcxml::Document}
+      #
+      def parse(xml)
+        Parser.new.parse(xml)
+      end
+    end
+  end
+
+end

data/metacrunch-marcxml.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "metacrunch/marcxml/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "metacrunch-marcxml"
+  spec.version       = Metacrunch::Marcxml::VERSION
+  spec.authors       = ["René Sprotte"]
+  spec.email         = "r.sprotte@ub.uni-paderborn.de"
+  spec.summary       = %q{MARCXML package for the metacrunch ETL toolkit.}
+  spec.homepage      = "http://github.com/ubpb/metacrunch-marcxml"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 5.1"
+  spec.add_dependency "htmlentities",  ">= 4.3"
+  spec.add_dependency "ox",            ">= 2.8"
+end
+

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: metacrunch-marcxml
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- René Sprotte
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-09-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: htmlentities
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.3'
+- !ruby/object:Gem::Dependency
+  name: ox
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: 
+email: r.sprotte@ub.uni-paderborn.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- License.txt
+- Rakefile
+- Readme.md
+- bin/console
+- lib/metacrunch/marcxml.rb
+- lib/metacrunch/marcxml/document.rb
+- lib/metacrunch/marcxml/document/controlfield.rb
+- lib/metacrunch/marcxml/document/datafield.rb
+- lib/metacrunch/marcxml/document/datafield_set.rb
+- lib/metacrunch/marcxml/document/subfield.rb
+- lib/metacrunch/marcxml/document/subfield_set.rb
+- lib/metacrunch/marcxml/parser.rb
+- lib/metacrunch/marcxml/version.rb
+- metacrunch-marcxml.gemspec
+homepage: http://github.com/ubpb/metacrunch-marcxml
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: MARCXML package for the metacrunch ETL toolkit.
+test_files: []