refactor: Replace Record::get with Record::query [BC]

Breaking change: Replace `Record::get()` with `Record::query()`, which returns a `QueryResult` object rather than an array of strings. This allows access to the marc fields / subfields matched by the query.

Author: danmichaelo

README.md

@@ -54,21 +54,55 @@ foreach ($collection->records as $record) {
 
 ```
 
-## Querying with MARC spec
+If you only have a single record, you can also use `Record::fromFile` or
+`Record::fromString`. These use the `Collection` methods under the hood,
+but returns a single `Record` object.
 
-Using the `Record::get()` method you can query a record using the MARC spec
-syntax provided by the [php-marc-spec package](https://github.com/MARCspec/php-marc-spec):
 
 ```php
-use Scriptotek\Marc\Collection;
+use Scriptotek\Marc\Record;
+
+$record = Record::fromFile($someFileName);
+```
 
-$collection = Collection::fromFile($someMarcFile);
+## Querying with MARCspec
 
-foreach ($collection->records as $record) {
-  echo $record->get('250$a');
+Use the `Record::query()` method to query a record using the
+[MARCspec](http://marcspec.github.io/) language as implemented in the
+[php-marc-spec package](https://github.com/MARCspec/php-marc-spec) package.
+The method returns a `QueryResult` object, which is a small wrapper around
+`File_MARC_Reference`.
+
+Example: To loop over all `650` fields having `$2 noubomn`:
+
+```php
+foreach ($record->query('650{2=\noubomn}') as $field) {
+   echo $field->getSubfield('a')->getData();
 }
 ```
 
+or we could reference the subfield directly, like so:
+
+```php
+foreach ($record->query('650$a{2=\noubomn}') as $subfield) {
+   echo $subfield->getData();
+}
+```
+
+You can retrieve single results using `first()`, which returns the first match,
+or `null` if no matches were found:
+
+```php
+$record->query('250$a')->first();
+```
+
+In the same way, `text()` returns the data content of the first match, or `null`
+if no matches were found:
+
+```php
+$record->query('250$a')->text();
+```
+
 ## Convenience methods on the Record class
 
 The `Record` class of File_MARC has been extended with a few

src/QueryResult.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace Scriptotek\Marc;
+
+use ArrayAccess;
+use ArrayIterator;
+use Countable;
+use File_MARC_Reference;
+use IteratorAggregate;
+use Traversable;
+
+class QueryResult implements IteratorAggregate, ArrayAccess, Countable
+{
+    protected $ref;
+
+    /**
+     * QueryResult constructor.
+     * @param File_MARC_Reference $spec
+     */
+    public function __construct(File_MARC_Reference $ref)
+    {
+        $this->ref = $ref;
+    }
+
+    public function getReference()
+    {
+        return $this->ref;
+    }
+
+    /**
+     * Get the first result (field or subfield), or null if no results.
+     *
+     * @return File_MARC_Field|File_MARC_Subfield|null
+     */
+    public function first()
+    {
+        return isset($this->ref->data[0]) ? $this->ref->data[0] : null;
+    }
+
+    /**
+     * Get the text content of the first result, or null if no results.
+     *
+     * @return string
+     */
+    public function text()
+    {
+        return isset($this->ref->content[0]) ? $this->ref->content[0] : null;
+    }
+
+    /**
+     * Retrieve an external iterator
+     * @link http://php.net/manual/en/iteratoraggregate.getiterator.php
+     * @return Traversable
+     */
+    public function getIterator()
+    {
+        return new ArrayIterator($this->ref->data);
+    }
+
+    /**
+     * Whether a offset exists
+     * @link http://php.net/manual/en/arrayaccess.offsetexists.php
+     * @param mixed $offset An offset to check for.
+     * @return boolean true on success or false on failure.
+     */
+    public function offsetExists($offset)
+    {
+        return isset($this->ref->data[$offset]);
+    }
+
+    /**
+     * Offset to retrieve
+     * @link http://php.net/manual/en/arrayaccess.offsetget.php
+     * @param mixed $offset The offset to retrieve.
+     * @return File_MARC_Field|File_MARC_Subfield
+     */
+    public function offsetGet($offset)
+    {
+        return $this->ref->data[$offset];
+    }
+
+    /**
+     * Offset to set
+     * @link http://php.net/manual/en/arrayaccess.offsetset.php
+     * @param mixed $offset The offset to assign the value to.
+     * @param mixed $value The value to set.
+     */
+    public function offsetSet($offset, $value)
+    {
+        $this->ref->data[$offset] = $value;
+    }
+
+    /**
+     * Offset to unset
+     * @link http://php.net/manual/en/arrayaccess.offsetunset.php
+     * @param mixed $offset The offset to unset.
+     */
+    public function offsetUnset($offset)
+    {
+        unset($this->ref->data[$offset]);
+    }
+
+    /**
+     * Count elements of an object
+     * @link http://php.net/manual/en/countable.count.php
+     * @return int The number of results
+     */
+    public function count()
+    {
+        return count($this->ref->data[$offset]);
+    }
+}

src/Record.php

@@ -2,6 +2,8 @@
 
 namespace Scriptotek\Marc;
 
+use File_MARC_Reference;
+
 class Record
 {
     protected $record;
@@ -143,11 +145,13 @@ protected function makeField($model, \File_MARC_Field $field)
         return $this->factory->makeField($model, $field);
     }
 
-    public function get($spec)
+    /**
+     * @param string $spec  The MARCspec string
+     * @return QueryResult
+     */
+    public function query($spec)
     {
-        $reference = new \File_MARC_Reference($spec, $this->record);
-
-        return $reference->content ?: array();
+        return new QueryResult(new File_MARC_Reference($spec, $this->record));
     }
 
     public function __call($name, $args)

tests/QueryResultTest.php

@@ -0,0 +1,59 @@
+<?php
+
+use Scriptotek\Marc\Record;
+use Scriptotek\Marc\QueryResult;
+
+class QueryResultTest extends \PHPUnit_Framework_TestCase
+{
+
+    protected $record;
+
+    public function setUp()
+    {
+        $this->record = Record::fromString('<?xml version="1.0" encoding="UTF-8" ?>
+          <record xmlns="http://www.loc.gov/MARC21/slim">
+            <leader>99999cam a2299999 u 4500</leader>
+            <controlfield tag="001">98218834x</controlfield>
+            <datafield tag="020" ind1=" " ind2=" ">
+              <subfield code="a">8200424421</subfield>
+              <subfield code="q">h.</subfield>
+              <subfield code="c">Nkr 98.00</subfield>
+            </datafield>
+            <datafield tag="020" ind1=" " ind2=" ">
+              <subfield code="a">9788200424420</subfield>
+              <subfield code="q">ib.</subfield>
+            </datafield>
+          </record>');
+    }
+
+    public function testInitialization()
+    {
+        $result = $this->record->query('020');
+        $this->assertInstanceOf(QueryResult::class, $result);
+    }
+
+    public function testFirstField()
+    {
+        $result = $this->record->query('020{$a}')->first();
+        $this->assertInstanceOf('File_MARC_Field', $result);
+    }
+
+    public function testFirstSubfield()
+    {
+        $result = $this->record->query('020$a')->first();
+        $this->assertInstanceOf('File_MARC_Subfield', $result);
+    }
+
+    public function testText()
+    {
+        $result = $this->record->query('020$a')->text();
+        $this->assertEquals('8200424421', $result);
+    }
+
+    public function testTextPattern()
+    {
+        $result = $this->record->query('020$a{$q=\ib.}')->text();
+        $this->assertEquals('9788200424420', $result);
+    }
+
+}