ruby-marc-spec 0.1.0

data/.rubocop.yml

@@ -0,0 +1,269 @@
+inherit_mode:
+  merge:
+    - Exclude
+    - Include
+
+# Allow one line around block body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+# Allow one line around class body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+# Allow one line around module body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+# Reasonable line-length check; it's too easy for the cure to be worse than the disease
+Layout/LineLength:
+  Max: 150
+
+# Make indents consistent regardless of the lengths of variables and method names and whatnot
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Produces monsters
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+# We meant to do that
+Naming/MemoizedInstanceVariableName:
+  Enabled: False
+
+# It works in context, trust us
+Naming/MethodParameterName:
+  Enabled: False
+
+# Confusing and weird
+Naming/VariableNumber:
+  Enabled: False
+
+# Do what's readable in the context you're in
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+# 👎 to cultural imperialism
+Style/AsciiComments:
+  Enabled: false
+
+# Seriously?
+Style/CommentedKeyword:
+  Enabled: False
+
+# Disable problematic module documentation check (see https://github.com/bbatsov/rubocop/issues/947)
+Style/Documentation:
+  Enabled: false
+
+# Adding more line noise to format strings will not improve them
+Style/FormatStringToken:
+  Enabled: false
+
+# Putting '# frozen_string_literal: true' everywhere does not make the world a better place
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Requiring the lambda() method just makes wordy calls wordier
+Style/Lambda:
+  EnforcedStyle: literal
+
+# `foo.positive?` is cute, but it's not actually more readable than `foo > 0`
+Style/NumericPredicate:
+  Enabled: false
+
+# Unclear why it's a good idea to give parameters semantically meaningless names
+Style/SingleLineBlockParams:
+  Enabled: false
+
+# The semantics of `foo&.bar` are a lot less interchangeable with `foo && foo.bar` than RuboCop thinks
+Style/SafeNavigation:
+  Enabled: false
+
+# Short arrays are often more readable as plain arrays
+Style/WordArray:
+  MinSize: 3
+
+############################################################
+# Added in RuboCop 0.80
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.81
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.82
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: false
+
+############################################################
+# Added in RuboCop 0.83
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.84
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.85
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.86
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.87
+
+# Sometimes we separate things for a reason
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.88
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+# Indiscriminately calling `to_ary` and `to_a` isn't always a good idea
+Style/ArrayCoercion:
+  Enabled: false
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.89
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+
+Lint/DuplicateRescueException:
+  Enabled: true
+
+Lint/EmptyConditionalBody:
+  Enabled: true
+
+Lint/FloatComparison:
+  Enabled: true
+
+Lint/MissingSuper:
+  Enabled: true
+
+Lint/OutOfRangeRegexpRef:
+  Enabled: true
+
+Lint/SelfAssignment:
+  Enabled: true
+
+Lint/TopLevelReturnWithArgument:
+  Enabled: true
+
+Lint/UnreachableLoop:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: true
+
+Style/GlobalStdStream:
+  Enabled: true
+
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+Style/SingleArgumentDig:
+  Enabled: true
+
+Style/SoleNestedConditional:
+  Enabled: true
+
+Style/StringConcatenation:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.90
+
+Lint/DuplicateRequire:
+  Enabled: true
+
+Lint/EmptyFile:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
+Lint/UselessMethodDefinition:
+  Enabled: true
+
+Style/CombinableLoops:
+  Enabled: true
+
+Style/KeywordParametersOrder:
+  Enabled: true
+
+Style/RedundantSelfAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.91
+
+Layout/BeginEndAlignment:
+  Enabled: true
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: true
+
+Lint/IdentityComparison:
+  Enabled: true
+
+Lint/UselessTimes:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+2.7

data/.simplecov

@@ -0,0 +1,8 @@
+require 'simplecov-rcov'
+
+SimpleCov.start 'rails' do
+  add_filter 'module_info.rb'
+  coverage_dir 'artifacts'
+  formatter SimpleCov::Formatter::RcovFormatter
+  minimum_coverage 100
+end

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.1.0 (2021-03-15)
+
+- Initial release.

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# TODO: Remove once 1.1.2 or later is released
+gem 'marc', '~> 1.1', git: 'https://github.com/ruby-marc/ruby-marc.git', ref: '335a02065136440c8fb57c8f18e99dcd6e23791a'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2021 The Regents of the University of California
+
+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/README.md

@@ -0,0 +1,172 @@
+[![Build Status](https://github.com/BerkeleyLibrary/marc-spec/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/BerkeleyLibrary/marc-spec/actions/workflows/build.yml)
+[![Gem Version](https://img.shields.io/gem/v/ruby-marc-spec.svg)](https://github.com/ruby-marc-spec/releases)
+
+# MARC::Spec
+
+A implementation of the [MARCspec](http://marcspec.github.io/MARCspec/marc-spec.html) 
+query language for Ruby and [ruby-marc](https://github.com/ruby-marc/ruby-marc).
+
+## Usage
+
+Add `ruby-marc-spec` to your Gemfile or gemspec, or just install it:
+
+- Gemfile:
+
+  ```ruby
+  gem 'ruby-marc-spec'
+  ```
+
+- gemspec
+
+  ```ruby
+  spec.add_dependency 'ruby-marc-spec'
+  ```
+
+- from the command line:
+
+  ```sh
+  gem install ruby-marc-spec
+  ```
+
+Then, in your code:
+
+```ruby
+require 'marc/spec'
+```
+
+The entry point for `MARC::Spec` is the `MARC::Spec#find` method, which takes a string
+MARCspec query and a `MARC::Record` object.
+
+```ruby
+MARC::Spec.find('245$a', marc_record)
+# => [#<MARC::Subfield:0x00007ffa1686e3f0 @code="a", @value="Arithmetic /">] 
+```
+
+Note that for simplicity's sake `MARC::Spec#find` always returns an array, even for 
+queries that can only return a single-element result, e.g.
+
+```ruby
+MARC::Spec.find('LDR', marc_record)
+# => ["01142cam  2200301 a 4500"]
+```
+
+## Examples
+
+All examples below are based on the record [`sandburg.xml`](spec/data/sandburg.xml)
+from the Library of Congress [MARCXML](https://www.loc.gov/standards/marcxml/) documentation.
+
+```ruby
+marc_record = MARC::XMLReader.new('sandburg.xml').first
+```
+
+### Retrieving the leader
+
+```ruby
+MARC::Spec.find('LDR', marc_record)
+# => ["01142cam  2200301 a 4500"]
+```
+
+### Retrieving control fields
+
+Find all fields whose tag begins with `00`:
+
+```ruby
+MARC::Spec.find('00.', marc_record)
+# => [
+#  #<MARC::ControlField:0x00007ff9f706ac40 @tag="001", @value="   92005291 ">,
+#  #<MARC::ControlField:0x00007ff9f70686c0 @tag="003", @value="DLC">,
+#  #<MARC::ControlField:0x00007ff9f7062450 @tag="005", @value="19930521155141.9">,
+#  #<MARC::ControlField:0x00007ff9f70600d8 @tag="008", @value="920219s1993    caua   j      000 0 eng  ">
+# ]
+```
+
+### Retrieving substrings of a control field value:
+
+Find the first six characters (characters 0 through 6) of the `008` field:
+
+```ruby
+MARC::Spec.find('008/0-5', marc_record)
+# => ["920219"]
+```
+
+### Retrieving data fields
+
+Find the first two `650` fields (fields 0 and 1):
+
+```ruby
+MARC::Spec.find('650[0-1]', marc_record)
+# => [#<MARC::DataField:0x00007ffa1799a5c0
+#   @indicator1=" ",
+#   @indicator2="0",
+#   @subfields=[#<MARC::Subfield:0x00007ffa17999878 @code="a", @value="Arithmetic">, #<MARC::Subfield:0x00007ffa179984a0 @code="x", @value="Juvenile poetry.">],
+#   @tag="650">,
+#  #<MARC::DataField:0x00007ffa17992618
+#   @indicator1=" ",
+#   @indicator2="0",
+#   @subfields=[#<MARC::Subfield:0x00007ffa179918d0 @code="a", @value="Children's poetry, American.">],
+#   @tag="650">] 
+```
+
+### Retrieving subfields
+
+Find subfield `a` of all 650 fields:
+
+```ruby
+MARC::Spec.find('650$a', marc_record)
+#  => 
+# [#<MARC::Subfield:0x00007ffa17999878 @code="a", @value="Arithmetic">,
+#  #<MARC::Subfield:0x00007ffa179918d0 @code="a", @value="Children's poetry, American.">,
+#  #<MARC::Subfield:0x00007ffa1798acb0 @code="a", @value="Arithmetic">,
+#  #<MARC::Subfield:0x00007ffa17982cb8 @code="a", @value="American poetry.">,
+#  #<MARC::Subfield:0x00007ffa17980120 @code="a", @value="Visual perception.">]
+``` 
+
+### Retrieving subfield values
+
+Find the first six characters (characters 0 through 5) of subfield `a` 
+of the fifth (zero-indexed) `650` field:
+
+```ruby
+MARC::Spec.find('650[4]$a/0-5', marc_record)
+# => ["Visual"]
+```
+
+### Limiting results based on conditions:
+
+Find all `650` fields having a value of `0` for the second indicator:
+
+```ruby
+MARC::Spec.find('650{^2=\0}', marc_record)
+# => 
+# [#<MARC::DataField:0x00007ffa1799a5c0
+#   @indicator1=" ",
+#   @indicator2="0",
+#   @subfields=[#<MARC::Subfield:0x00007ffa17999878 @code="a", @value="Arithmetic">, #<MARC::Subfield:0x00007ffa179984a0 @code="x", @value="Juvenile poetry.">],
+#   @tag="650">,
+#  #<MARC::DataField:0x00007ffa17992618
+#   @indicator1=" ",
+#   @indicator2="0",
+#   @subfields=[#<MARC::Subfield:0x00007ffa179918d0 @code="a", @value="Children's poetry, American.">],
+#   @tag="650">] 
+```
+
+Find subfield `a` of each `650` field that also has a subfield `x`:
+
+```ruby
+MARC::Spec.find('650$a{$x}', marc_record)
+# => [#<MARC::Subfield:0x00007ffa17999878 @code="a", @value="Arithmetic">, #<MARC::Subfield:0x00007ffa1798acb0 @code="a", @value="Arithmetic">] 
+```
+
+Note that this `650$a{$x}` could also be written `650$a{?$x}`; the `?` ("exists") operator
+is implicit if no other operator is specified.
+
+Find the first seven characters of `260$b`, but only if the corresponding `$a` contains
+the string `San Diego` and there is at least one `050$b` containing as a substring characters
+7 through 10 of the `008` field:
+
+```ruby
+MARC::Spec.find('260$b/0-7{$a~\San\sDiego}{050$b~008/7-10}', marc_record)
+# => ["Harcourt"]
+```
+
+For further examples, see the MARCSpec [documentation](http://marcspec.github.io/MARCspec/marc-spec.html#marcspec-explained).

data/Rakefile

@@ -0,0 +1,20 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
+
+# ------------------------------------------------------------
+# Application code
+
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+# ------------------------------------------------------------
+# CI
+
+ENV['RAILS_ENV'] = 'test' if ENV['CI']
+
+# ------------------------------------------------------------
+# Custom tasks
+
+desc 'Run tests, check test coverage, check code style'
+task default: %i[coverage rubocop bundle:audit gem]

data/lib/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_from: ../.rubocop.yml
+
+Style/ParallelAssignment:
+  Enabled: false
+

data/lib/marc/spec/module_info.rb

@@ -0,0 +1,14 @@
+module MARC
+  module Spec
+    class ModuleInfo
+      NAME = 'ruby-marc-spec'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'MARCspec for Ruby'.freeze
+      DESCRIPTION = 'An implementation of the MARCspec query language for Ruby and ruby-marc'.freeze
+      LICENSE = 'MIT'.freeze
+      VERSION = '0.1.0'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/marc-spec'.freeze
+    end
+  end
+end

data/lib/marc/spec/parsing/closed_int_range.rb

@@ -0,0 +1,28 @@
+require 'parslet'
+
+module MARC
+  module Spec
+    module Parsing
+      class ClosedIntRange < Parslet::Atoms::Base
+        SIMPLE_CLASS_NAME = ClosedIntRange.name.split('::').last
+
+        INT_RANGE_RE = /^(0|[1-9][0-9]*)-(0|[1-9][0-9]*)/.freeze
+
+        def try(source, context, _consume_all)
+          source_str = source.instance_variable_get(:@str) # TODO: something less hacky
+          return context.err(self, source, 'Not a non-negative integer range') unless (range_str = source_str.check(INT_RANGE_RE))
+
+          s, e = range_str.match(INT_RANGE_RE)[1, 2]
+          return context.err(self, source, "#{s} !<= #{e}") unless s.to_i <= e.to_i
+
+          sv, _, ev = [s.size, 1, e.size].map { |l| source.consume(l) } # discard hyphen
+          succ(from: sv, to: ev)
+        end
+
+        def to_s_inner(_prec)
+          SIMPLE_CLASS_NAME
+        end
+      end
+    end
+  end
+end

data/lib/marc/spec/parsing/closed_lc_alpha_range.rb

@@ -0,0 +1,28 @@
+require 'parslet'
+
+module MARC
+  module Spec
+    module Parsing
+      class ClosedLcAlphaRange < Parslet::Atoms::Base
+        SIMPLE_CLASS_NAME = ClosedLcAlphaRange.name.split('::').last
+
+        LCALPHA_RANGE_RE = /^([a-z])-([a-z])/.freeze
+
+        def try(source, context, _consume_all)
+          source_str = source.instance_variable_get(:@str) # TODO: something less hacky
+          return context.err(self, source, 'Not a lower-case alphabetic range') unless (range_str = source_str.check(LCALPHA_RANGE_RE))
+
+          s, e = range_str.match(LCALPHA_RANGE_RE)[1, 2]
+          return context.err(self, source, "#{s} !<= #{e}") unless s < e
+
+          sv, _, ev = [s.size, 1, e.size].map { |l| source.consume(l) } # discard hyphen
+          succ(from: sv, to: ev)
+        end
+
+        def to_s_inner(_prec)
+          SIMPLE_CLASS_NAME
+        end
+      end
+    end
+  end
+end