metacrunch-marcxml 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 108b2f6697c4cc1fd07f61231da1a5b0219e7fe1
-  data.tar.gz: 8ca7bdf5edc53577c1dd700e00af500b388bb386
+SHA256:
+  metadata.gz: 3634c811258d11102cde40466592986814cb3ecf463985fd4ff139934539fe8b
+  data.tar.gz: 9b86c52e489af8bd05f698af04526d3c1561d67180fd37db88d797d351481ca9
 SHA512:
-  metadata.gz: 80c1d9f509ee566035a76f62429662fd524d4f123b50a303776aea4e301479ad41c380e89f9622d3063b96733fec6fdaf72b4ce146ca027a7ef07836dc6e55b1
-  data.tar.gz: dd1abb2e6f24dd197ffdcb3b8e1b774d127d9b5a3fc13cb7e464f5e6fcb1ffa83f8054bef2a132ce4fed31236333947d6be3970d6047b59621a38417c1616bab
+  metadata.gz: 170cb959fb34cd493867c07e0d6ff3553385ccb7c7cca41beeee1f70208725921ea80f2a3765511fd87d330a1d61b90ab7167cf3a25df65797f6194960f8ec7b
+  data.tar.gz: ccfd0da9bfc9cb8d66dbf6fb632f0b7949fc0fb539586a9eff1ef2d148446f8d611ddea48346dbbb82052ff794ed6b8704fa5d3ed967a38c4c61f3b7eeabc33e

data/.circleci/config.yml

@@ -0,0 +1,35 @@
+version: 2.1
+orbs:
+  ruby: circleci/ruby@1.1.1
+
+jobs:
+  build:
+    docker:
+      - image: circleci/ruby:2.6-node-browsers
+
+    working_directory: ~/repo
+
+    steps:
+      - checkout
+
+      - run:
+          name: Install dependencies
+          command: bundle install --jobs=4 --retry=3 --path vendor/bundle
+
+      - run:
+          name: Install CodeClimate test coverage reporter
+          command: |
+            curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+            chmod +x ./cc-test-reporter
+            ./cc-test-reporter before-build
+
+      - run:
+          name: Run tests
+          command: |
+            mkdir /tmp/test-results
+            bundle exec rspec --format progress --format RspecJunitFormatter --out /tmp/test-results/rspec.xml
+
+      - run:
+          name: Upload test coverage report to CodeClimate
+          command: ./cc-test-reporter after-build --exit-code $?
+

data/Gemfile

@@ -5,7 +5,6 @@ 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"
@@ -13,5 +12,7 @@ group :development do
 end
 
 group :test do
-  gem "simplecov", ">= 0.15.0"
+  gem "rspec",                 ">= 3.5.0", "< 4.0.0"
+  gem "rspec_junit_formatter", ">= 0.3.0"
+  gem "simplecov",             "= 0.17.1"
 end

data/Readme.md

@@ -1,8 +1,10 @@
 metacrunch-marcxml
 ==================
 
-[![Build Status](https://travis-ci.org/ubpb/metacrunch-marcxml.svg)](https://travis-ci.org/ubpb/metacrunch-marcxml)
+[![Gem Version](https://badge.fury.io/rb/metacrunch-marcxml.svg)](http://badge.fury.io/rb/metacrunch-marcxml)
 [![Code Climate](https://codeclimate.com/github/ubpb/metacrunch-marcxml/badges/gpa.svg)](https://codeclimate.com/github/ubpb/metacrunch-marcxml)
+[![Test Coverage](https://codeclimate.com/github/ubpb/metacrunch-marcxml/badges/coverage.svg)](https://codeclimate.com/github/ubpb/metacrunch-marcxml/coverage)
+[![CircleCI](https://circleci.com/gh/ubpb/metacrunch-marcxml.svg?style=svg)](https://circleci.com/gh/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.
 
@@ -17,7 +19,7 @@ Installation
 Include the gem in your `Gemfile`
 
 ```ruby
-gem "metacrunch-marcxml", "~> 2.0.0"
+gem "metacrunch-marcxml", "~> 3.0.0"
 ```
 
 and run `$ bundle install` to install it.
@@ -32,28 +34,33 @@ $ gem install metacrunch-marcxml
 Usage example
 -------------
 
-**Loading the library**
+*Note: For working examples on how to use this package in a metacrunch job check out our [demo repository](https://github.com/ubpb/metacrunch-demo).*
+
+**Load 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}
+marcxml = URI.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
+# .. or 
+document = Metacrunch::Marcxml[marcxml]
+# .. or
 document = Metacrunch::Marcxml(marcxml)
 ```
 
-**Accessing control fields**
+**Access control fields**
+
 ```ruby
 controlfield = document.controlfield("005")
-# same as ...
-controlfield = document.controlfield(5)
 # => #<Metacrunch::Marcxml::Document::Controlfield:0x007fd4c5120ec0 ...>
 
 tag = controlfield.tag
@@ -62,16 +69,17 @@ value = controlfield.value
 # => "20130926112144.0"
 ```
 
-**Accessing data fields / sub fields**
+**Access data fields / sub fields**
+
 ```ruby
-# Find fields matching tag=100 and indicator1=1 (author)
-datafield_set = document.datafields(100, ind1: "1")
+# Find fields matching tag=100 and ind1=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)
+# Get the sub fields matching code=a (author name)
 subfield_set = first_author.subfields("a")
 # => #<Metacrunch::Marcxml::Document::SubfieldSet:0x007fd4c4c779f0 ...>
 
@@ -82,8 +90,45 @@ first_author_subfield = subfield_set.first # subfield_set is an Enumerable
 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
+# ... this can be a one liner
+first_author_name = document.datafields(100, ind1: "1").subfields("a").values.first
+```
+
+**Direct value access using a query string**
+
+Access fields as described above is flexible but very verbose. Most of the time you know your data and you are interested in a simple and direct way to access the field values.
+
+For this case we provide a way to query field values using a simple query string.
+
+```ruby
+# Get the value of control field "005"
+document["005"]
+# => "20130926112144.0"
+
+# Get the first value of data field tag=100, ind1=1, sub field code=a
+document["1001*a"].first
+# => "Orwell, George"
+```
+
+The query string syntax is simple. Each query string starts with three letters for the tag. If the tag starts with `00` it is considered a query for a control field value. Otherwise it is considered a data field / sub field query. In that case the next two characters are used to match ind1 and ind2. The default value is `*` which matches every indicator value. `-`, `_` and ` ` are interpreted as `blank`. The last characters are used to match the code of the sub fields. To query for more than one sub field code you may separate them using commas.
+
+**Examples**
+
+```ruby
+document["1001*a"] 
+# => ["Orwell, George"]
+
+document["020**a,c"]
+# => ["9783548267456",
+# "kart. : EUR 6.00 (DE), EUR 6.20 (AT), sfr 11.00",
+# "3548267459",
+# "kart. : EUR 6.00 (DE), EUR 6.20 (AT), sfr 11.00"]
+
+document["2463_a"]
+# => ["Neunzehnhundertvierundachtzig"]
+
+document["264_1a,b,c"]
+# => ["Berlin", "Ullstein", "2007"]
 ```
 
 License

data/lib/metacrunch/marcxml.rb

@@ -32,6 +32,16 @@ module Metacrunch
       def parse(xml)
         Parser.new.parse(xml)
       end
+
+      #
+      # Convenience method for Metacrunch::Marcxml.parse
+      #
+      # @return [Metacrunch::Marcxml::Document] the parsed {Metacrunch::Marcxml::Document}
+      # @see Metacrunch::Marcxml#parse
+      #
+      def [](xml)
+        self.parse(xml)
+      end
     end
   end
 

data/lib/metacrunch/marcxml/document.rb

@@ -23,7 +23,7 @@ module Metacrunch
       #
       # @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
+      # @return [Metacrunch::Marcxml::Document::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)
@@ -48,20 +48,18 @@ module Metacrunch
       #   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
+      # @param ind1 [nil, String, 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
+      # @param ind2 [nil, String, 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
+        matched_datafields = if tag.nil?
           @datafields_map.values.flatten(1)
-        when Enumerable
+        elsif tag.is_a?(Enumerable)
           tag.map{ |_tag| @datafields_map[normalize_tag(_tag)] }.compact.flatten(1)
         else
           @datafields_map[normalize_tag(tag)]
@@ -82,13 +80,57 @@ module Metacrunch
         datafield
       end
 
+      # ------------------------------------------------------------------------------
+      # Query API
+      # ------------------------------------------------------------------------------
+
+      #
+      # Returns a control field value or data field/sub field values matching the
+      # given query string.
+      #
+      # @param query_string [String] a query string.
+      #
+      # @return [Array<String>] The sub field values matching the query. Is empty if no match
+      #  is found.
+      #
+      def [](query_string)
+        # Control field query
+        if query_string.starts_with?("00")
+          # Example: "005"
+          # [0..2] => Control field tag
+          tag = query_string[0..2].presence
+          controlfield(tag)&.value
+
+        # Data field / sub field query
+        else
+          # Example: "100**a,e"
+          # [0..2] => Data field tag (required).
+          # [3]    => Ind1, defaults to `*`, which matches any indicator 1 (optional). ` `, `-` or `_` will be interpreted as `blank`.
+          # [4]    => Ind2, defaults to `*`, which matches any indicator 2 (optional). ` `, `-` or `_` will be interpreted as `blank`.
+          # [5]    => Sub field code(s) (optional).
+          tag      = query_string[0..2].presence
+
+          ind1     = query_string[3].presence
+          ind1     = nil    if ind1 == "*"
+          ind1     = :blank if ind1 == "-" || ind1 == "_" || ind1 == " "
+
+          ind2     = query_string[4].presence
+          ind2     = nil    if ind2 == "*"
+          ind2     = :blank if ind2 == "-" || ind2 == "_" || ind2 == " "
+
+          subfield_codes = query_string[5..-1]&.split(",")&.map(&:strip).compact.presence
+
+          datafields(tag, ind1: ind1, ind2: ind2).subfields(subfield_codes).values
+        end
+      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?)
+          elsif _requested_ind == :blank && (datafield_ind == " " || datafield_ind == "-" || datafield_ind == "_" || datafield_ind.nil?)
             true
           elsif _requested_ind == datafield_ind
             true
@@ -101,8 +143,8 @@ module Metacrunch
       def normalize_tag(tag)
         case tag
         when Integer then tag.to_s.rjust(3, "0")
-        when String  then tag
-        else tag.to_s
+        when String  then tag[0..2]
+        else tag.to_s[0..2]
         end
       end
 

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

@@ -28,14 +28,6 @@ module Metacrunch
           @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

data/lib/metacrunch/marcxml/parser.rb

@@ -2,7 +2,7 @@ module Metacrunch
   module Marcxml
     class Parser < Ox::Sax
 
-      def parse(mab_xml)
+      def parse(marc_xml)
         # initialize state machine
         @in_controlfield = @in_datafield = @in_subfield = false
 
@@ -11,8 +11,9 @@ module Metacrunch
         @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)
+        # parsing, which minifies the amount of entities we have to decode using
+        # html_entities_coder in #text.
+        Ox.sax_parse(self, marc_xml, convert_special: true)
 
         return @document
       end

data/lib/metacrunch/marcxml/version.rb

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

data/metacrunch-marcxml.gemspec

@@ -19,6 +19,6 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "activesupport", ">= 5.1"
   spec.add_dependency "htmlentities",  ">= 4.3"
-  spec.add_dependency "ox",            ">= 2.8"
+  spec.add_dependency "ox",            ">= 2.11"
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metacrunch-marcxml
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - René Sprotte
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2017-09-27 00:00:00.000000000 Z
+date: 2020-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,23 +44,23 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '2.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.8'
-description: 
+        version: '2.11'
+description:
 email: r.sprotte@ub.uni-paderborn.de
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
 - ".yardopts"
 - Gemfile
 - License.txt
@@ -81,7 +81,7 @@ homepage: http://github.com/ubpb/metacrunch-marcxml
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -96,9 +96,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: MARCXML package for the metacrunch ETL toolkit.
 test_files: []

data/.travis.yml

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