Initial commit

.gitignore

+.build
+dist
+.tmp
+nbproject
+review
+vendor
+#*
+.#*
+TAGS

.hgignore

+syntax: glob
+
+.build
+.dist
+nbproject
+review
+tmp
+vendor
+#*
+.#*
+TAGS

README.org

+#+TITLE: PicaRecord -- Object oriented interface to Pica+ records
+#+AUTHOR: David Maus
+#+EMAIL: maus@hab.de
+
+* About
+
+PicaRecord provides an object oriented interface to Pica+ records, fields, and subfields. It does
+not provide the means to read or write Pica+ records. In order to do so you need to install the
+packages PicaReader and PicaWriter that are available via the same PEAR channel.
+
+PicaRecord is copyright (c) 2012 by Herzog August Bibliothek Wolfenbüttel and released under the
+terms of the GNU General Public License v3.
+
+* Installation
+
+PicaRecord should be installed using the [[http://pear.php.net][PEAR Installer]]. This installer is the PHP community's
+de-facto standard for installing PHP packages.
+
+#+BEGIN_EXAMPLE
+pear channel-discover hab20.hab.de/service/pear
+pear install --alldeps hab20.hab.de/service/pear/PicaRecord
+#+END_EXAMPLE
+
+PicaRecord depends on the [[http://phix-project.org/][Phix project's]] PSR0 compliant autolader, =Autoloader=.
+
+* Usage
+
+** Records, Fields, and Subfields
+
+*** Subfields
+
+Subfields are represented by the =Subfield= class. A Pica+ subfield is a cons (pair) of an
+alphanumeric case-sensitive ASCII character and a non-empty string value. The code of a subfield is
+considered to be immutable and the value must not be the empty string.
+
+*** Fields
+
+Field are represented by the =Field= class. A Pica+ field is an ordered list of subfields and
+partially identified[1] by two properties, the field tag and the field occurrence. Both properties
+are set on instantiation and considered to be immutable.
+
+In the following text the /field shorthand/ refers to a string consisting of the field tag, followed
+by a forward slash (ASCII 47) followed by two digits denoting the field occurrence. For example the
+field shorthand of the field 021A with an occurrence of 0 is =021A/00=.
+
+**** Retrieving subfields
+
+=Field::getSubfields()= returns all subfields of a field when called with no arguments. To retrieve
+specific subfields you can pass an arbitrary number of arguments each representing a subfield
+code. If you do so the returned array will be constructed as follows:
+
+Each element of the returned array corresponds to a subfield code in the argument list. If the field
+has a subfield with the specified code the element of the returned array contains the subfield. If
+the field does not have a subfield with the specified code the element of the returned array
+contains =NULL=. In order to retrieve multiple subfields with the same subfield code you need to
+repeat the subfield code in the argument list. The first occurrence of the code in the argument list
+refers to the first subfield with the specified code, the second occurrence to the second subfield
+and so on.
+
+Because =Field::getSubfields()= when called with subfield codes as arguments returns an array with a
+known size (as much elements as arguments were passed to the function) you can conveniently use
+PHP's =list()= operation.
+
+Example: To retrieve the first and last name of the author encoded in the Pica+ field =028A/00= you
+can call =Field::getSubfields()= as follows:
+
+#+BEGIN_EXAMPLE
+list($firstName, $lastName, $personalName) = $field->getSubfields('d', 'a', '5');
+#+END_EXAMPLE
+
+**** Manipulating the subfield list
+
+You can use =Field::addSubfield()= to add a field to the end of the subfield list. If the subfield
+is already part of the subfield list an =InvalidArgumentException= is thrown. For more sophisticated
+manipulations of a field's subfield list you can use =Field::setSubfields()= to replace the subfield
+list of a field. 
+
+A subfield can be deleted using =Field::removeSubfield()= which takes the subfield to delete as sole
+argument and throws an =InvalidArgumentException= if the field does not contain the subfield.
+
+*** Records
+
+**** Record classes
+
+PicaRecord provides classes for the four record types of /title records/, /authority records/,
+/local records/, and /copy records/. The relationship of title, local, and copy records is as
+follows: A title record may contain zero or more local records. Each local record may contain up to
+99 copy records.
+
+Local records can be identified by the internal library number (ILN) of the library they belong to
+and retrieved either by =TitleRecord::getLocalRecord()=, which returns an array of all local
+records, or =TitleRecord::getLocalRecordByILN()= which retrieves a single local record identifed by
+its first argument.
+
+Copy records hold information about particular items (exemplars) and are identified by the number of
+the item in the local record. You can use =LocalRecord::getCopyRecords()= or
+=LocalRecord::getLocalRecordByItemNumber()= to retrieve an array with all copy records or a single
+copy record with a specified item number respectively.
+
+All record classes implement the two methods =Record::isEmpty()= which returns =TRUE= if a record is
+empty (does not contain any fields) and =Record::isValid()= which performs a preliminary validation
+of the record.
+
+**** Selecting and deleting fields
+
+=Record::getFields()= returns all fields of the record when called without arguments. If you call it
+with the body of a regular expression as argument it will only return the fields whose shorthand is
+matched by the regular expression.
+
+=Record::select()= provides a more generic access to a record's fields. It takes a predicate
+function as argument and returns all fields that fullfill the predicate. A predicate function can be
+any valid PHP callback that takes a Field as argument and return TRUE if the field fullfills the
+predicate or otherwise FALSE.
+
+=Record::delete()= deletes all fields that match a predicate function (see above).
+
+If a record contains other records, i.e. if a record is a title or local record, =Record::delete()=,
+=Record::select()=, and =Record::getFields()= operate on all fields of the record, including the
+fields of the contained records.
+
+**** Appending fields to a record
+
+Append fields to an existing record is not as straightforward as selecting or deleting fields. Each
+record class has its own restrictions when it comes to appending a field to it via the
+=Record::append()= function:
+
+- you can only append fields with a level of 0 to title and authority records
+- you can append fields with a level of 1 to local records
+- you can only append fields with a level of 2 to copy records; as an additional restriction the
+  occurrence value of the field must be equal to the item number of the copy record
+
+#+CAPTION: Allowed field levels per record class
+| Record class    | Allowed field level in append() |
+|-----------------+---------------------------------|
+| TitleRecord     | Level 0                         |
+| AuthorityRecord | Level 0                         |
+| LocalRecord     | Level 1                         |
+| CopyRecord      | Level 2                         |
+
+The attempt to add a field with a different level then the allowed level results in an
+=InvalidArgumentException= to be thrown.
+
+* Development
+
+If you want to patch or enhance this component, you will need to create a suitable development
+environment. The easiest way to do that is to install phix4componentdev:
+
+#+BEGIN_EXAMPLE
+apt-get install php5-xdebug
+apt-get install php5-imagick
+pear channel-discover pear.phix-project.org
+pear -D auto_discover=1 install -Ba phix/phix4componentdev
+#+END_EXAMPLE
+
+You can then clone the Git repository:
+
+#+BEGIN_EXAMPLE
+git clone git://gitorious.org/php-pica/picarecord.git
+#+END_EXAMPLE
+
+Then, install a local copy of the package's dependencies to complete the development environment:
+
+#+BEGIN_EXAMPLE
+phing build-vender
+#+END_EXAMPLE
+
+To make life easier for you, common tasks (such as running unit tests, generating code review
+analytics, and creating the PEAR package) have been automated using [[http://phing.info][Phing]]. You'll find the
+automated steps inside the build.xml file that ships with the component.
+
+Run the command 'phing' in the component's top-level folder to see the full list of available
+automated tasks.
+
+* Acknowledgments
+
+The [[http://phix-project.org][Phix project]] makes it easy to setup and maintain a package repository for a PEAR-installable
+package and integrates important tools such as [[http://phpunit.de][PHPUnit]], [[http://phing.info][Phing]], [[http://pear.php.net][PEAR]], and [[http://pirum.sensiolabs.org/][Pirum]]. Large parts of this
+package would not have been possible without studying the source of [[http://search.cpan.org/dist/PICA-Record/][Pica::Record]], an open source
+Perl library for handling Pica+ records by Jakob Voß, and the practical knowledge of our library's
+catalogers.
+
+* Footnotes
+
+[1] E.g. a title record may contain zero or more fields with tag =101@= and occurrence =00=; fields with this
+shorthand indicate the start of a local record.

build.local.xml

+<project name="local" default="help">
+  <target name="help">
+    <echo message="This component has no local build targets." />
+  </target>
+</project>
+<!-- vim: set tabstop=2 shiftwidth=2 expandtab: -->

build.properties

+project.name=PicaRecord
+project.channel=hab20.hab.de/service/pear
+project.majorVersion=0
+project.minorVersion=1
+project.patchLevel=0
+project.snapshot=true
+
+component.type=php-library
+component.version=11

package.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<package packagerversion="1.9.1" version="2.0"
+	 xmlns="http://pear.php.net/dtd/package-2.0"
+	 xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
+	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	 xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
+			     http://pear.php.net/dtd/tasks-1.0.xsd
+			     http://pear.php.net/dtd/package-2.0
+			     http://pear.php.net/dtd/package-2.0.xsd">
+  <name>${project.name}</name>
+  <channel>${project.channel}</channel>
+  <summary>Object oriented interface to Pica+ records</summary>
+  <description>
+    PicaRecord provides an object oriented interface to Pica+ records,
+    fields, and subfields.
+  </description>
+  <lead>
+    <name>David Maus</name>
+    <user>dmaus</user>
+    <email>maus@hab.de</email>
+    <active>yes</active>
+  </lead>
+  <date>${build.date}</date>
+  <time>${build.time}</time>
+  <version>
+    <release>${project.version}</release>
+    <api>${project.majorVersion}.${project.minorVersion}</api>
+  </version>
+  <stability>
+    <release>${project.stability}</release>
+    <api>stable</api>
+  </stability>
+  <license>GNU General Public License v3</license>
+  <notes>
+    The PicaRecord package does not provide the means to read or write
+    Pica+ records. In order to do so you need to install the packages
+    PicaReader and PicaWriter that are available via this PEAR
+    channel.
+  </notes>
+  <contents>
+    <dir baseinstalldir="/" name="/">
+      ${contents}
+    </dir>
+  </contents>
+  <dependencies>
+    <required>
+      <php>
+	<min>5.3.0</min>
+      </php>
+      <pearinstaller>
+	<min>1.9.4</min>
+      </pearinstaller>
+      <package>
+	<name>Autoloader</name>
+	<channel>pear.phix-project.org</channel>
+	<min>3.0.0</min>
+	<max>3.999.9999</max>
+      </package>
+    </required>
+  </dependencies>
+  <phprelease />
+  <changelog>
+    <release>
+      <version>
+	<release>0.1.0</release>
+	<api>0.1</api>
+      </version>
+      <stability>
+	<release>stable</release>
+	<api>stable</api>
+      </stability>
+      <date>2012-02-15</date>
+      <license>GNU General Public License v3</license>
+      <notes>
+      </notes>
+    </release>
+  </changelog>
+</package>
+<!-- vim: set tabstop=2 shiftwidth=2 expandtab: -->

phpunit.xml.dist

+<?xml version="1.0"?>
+<phpunit bootstrap="src/tests/unit-tests/bootstrap.php">
+    <testsuites>
+        <testsuite name="Unit Tests">
+            <directory suffix="Test.php">src/tests/unit-tests</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <blacklist>
+            <directory suffix=".php">vendor</directory>
+            <directory suffix=".php">src/tests</directory>
+        </blacklist>
+        <whitelist addUncoveredFilesFromWhitelist="true">
+            <directory suffix=".php">src/bin</directory>
+            <directory suffix=".php">src/php</directory>
+        </whitelist>
+    </filter>
+    <logging>
+        <log type="coverage-html" target="review/code-coverage"/>
+        <log type="coverage-clover" target="review/logs/phpunit.xml"/>
+        <log type="json" target="review/logs/phpunit.json"/>
+        <log type="tap" target="review/logs/phpunit.tap"/>
+        <log type="junit" target="review/logs/phpunit-junit.xml"/>
+        <log type="testdox-html" target="review/testdox.html"/>
+        <log type="testdox-text" target="review/testdox.txt"/>
+    </logging>
+</phpunit>
+<!-- vim: set tabstop=4 shiftwidth=4 expandtab: -->

src/README.txt

+Your src/ folder
+================
+
+This src/ folder is where you put all of your code for release.  There's
+a folder for each type of file that the PEAR Installer supports.  You can
+find out more about these file types online at:
+
+http://blog.stuartherbert.com/php/2011/04/04/explaining-file-roles/
+
+  * bin/
+
+    If you're creating any command-line tools, this is where you'd put
+    them.  Files in here get installed into /usr/bin on Linux et al.
+
+    There is more information available here: http://blog.stuartherbert.com/php/2011/04/06/php-components-shipping-a-command-line-program/
+
+    You can find an example here: https://github.com/stuartherbert/phix/tree/master/src/bin
+
+  * data/
+
+    If you have any data files (any files that aren't PHP code, and which
+    don't belong in the www/ folder), this is the folder to put them in.
+
+    There is more information available here: http://blog.stuartherbert.com/php/2011/04/11/php-components-shipping-data-files-with-your-components/
+
+    You can find an example here: https://github.com/stuartherbert/ComponentManagerPhpLibrary/tree/master/src/data
+
+  * php/
+
+    This is where your component's PHP code belongs.  Everything that goes
+    into this folder must be PSR0-compliant, so that it works with the
+    supplied autoloader.
+
+    There is more information available here: http://blog.stuartherbert.com/php/2011/04/05/php-components-shipping-reusable-php-code/
+
+    You can find an example here: https://github.com/stuartherbert/ContractLib/tree/master/src/php
+
+  * tests/functional-tests/
+
+    Right now, this folder is just a placeholder for future functionality.
+    You're welcome to make use of it yourself.
+
+  * tests/integration-tests/
+
+    Right now, this folder is just a placeholder for future functionality.
+    You're welcome to make use of it yourself.
+
+  * tests/unit-tests/
+
+    This is where all of your PHPUnit tests go.
+
+    It needs to contain _exactly_ the same folder structure as the src/php/
+    folder.  For each of your PHP classes in src/php/, there should be a
+    corresponding test file in test/unit-tests.
+
+    There is more information available here: http://blog.stuartherbert.com/php/2011/08/15/php-components-shipping-unit-tests-with-your-component/
+
+    You can find an example here: https://github.com/stuartherbert/ContractLib/tree/master/test/unit-tests
+
+  * www/
+
+    This folder is for any files that should be published in a web server's
+    DocRoot folder.
+
+    It's quite unusual for components to put anything in this folder, but
+    it is there just in case.
+
+    There is more information available here: http://blog.stuartherbert.com/php/2011/08/16/php-components-shipping-web-pages-with-your-components/

src/php/HAB/Pica/Record/AuthorityRecord.php

+<?php
+
+/**
+ * The AuthorityRecord class file.
+ *
+ * This file is part of PicaRecord.
+ *
+ * PicaRecord is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PicaRecord is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with PicaRecord.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @package   PicaRecord
+ * @author    David Maus <maus@hab.de>
+ * @copyright Copyright (c) 2012 by Herzog August Bibliothek Wolfenbüttel
+ * @license   http://www.gnu.org/licenses/gpl.html GNU General Public License v3
+ */
+
+namespace HAB\Pica\Record;
+
+/**
+ * The Pica+ authority record.
+ *
+ * @package   PicaRecord
+ * @author    David Maus <maus@hab.de>
+ * @copyright Copyright (c) 2012 by Herzog August Bibliothek Wolfenbüttel
+ * @license   http://www.gnu.org/licenses/gpl.html GNU General Public License v3
+ */
+class AuthorityRecord extends Record {
+
+  /**
+   * Append a field to the record.
+   *
+   * @see Record::append()
+   *
+   * @throws \InvalidArgumentException Field level other than 0
+   * @throws \InvalidArgumentException Field already in record
+   * @param  Field $field Field to append
+   * @return void
+   */
+  public function append (Field $field) {
+    if ($field->getLevel() !== 0) {
+      throw new \InvalidArgumentException("Invalid field level {$field->getLevel()}");
+    }
+    return parent::append($field);
+  }
+
+  /**
+   * Return the Pica production number (record identifier).
+   *
+   * @return string|null Pica production number or NULL if none exists
+   */
+  public function getPPN () {
+    $ppnField = reset($this->getFields('003@/00'));
+    if ($ppnField) {
+      $ppnSubfield = reset($ppnField->getSubfields('0'));
+      if ($ppnSubfield) {
+        return $ppnSubfield->getValue();
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Set the Pica production number.
+   *
+   * Create a field 003@/00 if necessary.
+   *
+   * @param  string $ppn Pica production number
+   * @return void
+   */
+  public function setPPN ($ppn) {
+    $ppnField = reset($this->getFields('003@/00'));
+    if ($ppnField) {
+      $ppnSubfield = reset($ppnField->getSubfields('0'));
+      if ($ppnSubfield) {
+        $ppnSubfield->setValue($ppn);
+      } else {
+        $ppnField->append(new Subfield('0', $ppn));
+      }
+    } else {
+      $this->append(new Field('003@', 0, array(new Subfield('0', $ppn))));
+    }
+  }
+
+  /**
+   * Return TRUE if the record is valid.
+   *
+   * A valid authority record MUST have exactly one valid PPN field
+   * (003@/00$0) and exactly one type field (002@/0$0) with a type indicator
+   * `T'.
+   *
+   * @see \HAB\Pica\Record\AuthorityRecord::checkPPN();
+   * @see \HAB\Pica\Record\AuthorityRecord::checkType();
+   *
+   * @return boolean TRUE if the record is valid
+   */
+  public function isValid () {
+    return parent::isValid() && $this->checkPPN() && $this->checkType();
+  }
+
+  /**
+   * Return TRUE if the record has exactly one PPN field (003@/00) with a
+   * subfield $0.
+   *
+   * @return boolean TRUE if the record has a valid PPN field
+   */
+  protected function checkPPN () {
+    $ppnField = $this->getFields('003@/00');
+    if (count($ppnField) === 1) {
+      $ppnSubfield = reset(reset($ppnField)->getSubfields('0'));
+      if ($ppnSubfield) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Return TRUE if the record has exactly one type field (002@/00) with a
+   * subfield $0 whose first character is `T'.
+   *
+   * @return boolean TRUE if the record has a valid type field
+   */
+  protected function checkType () {
+    $typeField = $this->getFields('002@/00');
+    if (count($typeField) === 1) {
+      $typeSubfield = reset(reset($typeField)->getSubfields('0'));
+      if ($typeSubfield) {
+        $typeCode = $typeSubfield->getValue();
+        if ($typeCode === 'T') {
+          return true;
+        }
+      }
+    }
+  }
+}
\ No newline at end of file

src/php/HAB/Pica/Record/CopyRecord.php

+<?php
+
+/**
+ * The CopyRecord class file.
+ *
+ * This file is part of PicaRecord.
+ *
+ * PicaRecord is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PicaRecord is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with PicaRecord.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @package   PicaRecord
+ * @author    David Maus <maus@hab.de>
+ * @copyright Copyright (c) 2012 by Herzog August Bibliothek Wolfenbüttel
+ * @license   http://www.gnu.org/licenses/gpl.html GNU General Public License v3
+ */
+
+namespace HAB\Pica\Record;
+
+/**
+ * The Pica+ copy record.
+ *
+ * @package   PicaRecord
+ * @author    David Maus <maus@hab.de>
+ * @copyright Copyright (c) 2012 by Herzog August Bibliothek Wolfenbüttel
+ * @license   http://www.gnu.org/licenses/gpl.html GNU General Public License v3
+ */
+class CopyRecord extends Record {
+
+  /**
+   * The item number.
+   *
+   * @var integer
+   */
+  protected $_itemNumber;
+
+  /**
+   * Append a field to the copy record.
+   *
+   * You can only append field of level 2 to a copy record. 
+   *
+   * @see Record::append()
+   *
+   * @throws \InvalidArgumentException Field level other than 2
+   * @throws \InvalidArgumentException Item number mismatch
+   * @throws \InvalidArgumentException Field already in record
+   * @param  \HAB\Pica\Record\Field $field Field to append
+   * @return void