Adding README and naming changes

9 files changed, 57 insertions, 29 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..f0cf0a9
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,28 @@
+Cinisis database reader
+=======================
+
+Naming conventions
+------------------
+
+The following naming conventions are used through Cinisis aiming to help
+iterating over all the data from a ISIS database.
+
+  - Database:  an ISIS database.
+  - Entry:     a given MFN in the database.
+  - Value:     all the data from a given entry in the database.
+  - Field:     a numbered set of values from a given entry.
+  - Row:       a single value from a given field.
+  - Main item: the data in a row without a qualifier.
+  - Subfield:  every data in a row within a qualifier.
+  - Item:      either a main item or subfield withing a row.
+
+Example:
+
+  MFN 1 with entry
+  10: First  row of field 10^aWith a subfield^bAnd another one
+  10: Second row of field 10^bJust with the second subfield
+  20: This is the main item^yAnd this is another item
+
+For that entry we have fields 10 and 20, where field 10 has two rows (i.e, two
+repetitions). The main field is the data wich is has no qualifier (^) and a
+subfield is the data with qualifiers (like subfields a and b from above).
diff --git a/classes/BiblioIsisDb.php b/classes/BiblioIsisDb.php
index eabf892..22586ed 100644
--- a/classes/BiblioIsisDb.php
+++ b/classes/BiblioIsisDb.php
@@ -127,11 +127,11 @@ class BiblioIsisDb implements IsisDb {
   }
 
   /**
-   * Return number of rows in the database.
+   * Return number of entries in the database.
    *
-   * @see IsisDb::read()
+   * @see IsisDb::entries()
    */  
-  public function rows() {
+  public function entries() {
     return $this->backend('count');
   }
 
diff --git a/classes/IsisConnector.php b/classes/IsisConnector.php
index fe8cd75..c0fd3fc 100644
--- a/classes/IsisConnector.php
+++ b/classes/IsisConnector.php
@@ -12,9 +12,9 @@ class IsisConnector {
     $this->isis = new CinisisDb();
 
     if ($this->isis->db) {
-      $this->rows   = $this->isis->db->rows();
-      $this->format = $this->isis->db->format;
-      $this->fields = $this->format['fields'];
+      $this->entries = $this->isis->db->entries();
+      $this->format  = $this->isis->db->format;
+      $this->fields  = $this->format['fields'];
     }
     else {
       return FALSE;
@@ -24,15 +24,15 @@ class IsisConnector {
   /**
    * Alias to $isis->db->read().
    *
-   * @param $row
+   * @param $entry
    *   Row number.
    *
    * @return
    *   Resulting data.
    */
-  public function read($row) {
+  public function read($entry) {
     // Always store the last result.
-    $this->result = $this->isis->db->read($row);
+    $this->result = $this->isis->db->read($entry);
 
     // Return the result.
     return $this->result;
diff --git a/classes/IsisDb.php b/classes/IsisDb.php
index 43a51dc..4a2218a 100644
--- a/classes/IsisDb.php
+++ b/classes/IsisDb.php
@@ -24,17 +24,17 @@ interface IsisDb {
    * Read an entry from the database.
    *
    * @param $id
-   *   Database row id.
+   *   Database entry id.
    */
   public function read($id);
 
   /**
-   * Return number of rows in the database.
+   * Return number of entries in the database.
    *
    * @return
-   *   Number of rows in the database.
+   *   Number of entries in the database.
    */
-  public function rows();
+  public function entries();
 
   /**
    * Return an example database schema.
diff --git a/classes/MaleteDb.php b/classes/MaleteDb.php
index e7d50a5..7983c2f 100644
--- a/classes/MaleteDb.php
+++ b/classes/MaleteDb.php
@@ -70,15 +70,15 @@ class MaleteDb implements IsisDb {
   }
 
   /**
-   * Return number of rows in the database.
+   * Return number of entries in the database.
    *
    * The Malete API doen't implement such feature so we
    * have to emulate it by iterating over all entries
    * until MaleteDb::read() returns FALSE.
    *
-   * @see IsisDb::read()
+   * @see IsisDb::entries()
    */  
-  public function rows() {
+  public function entries() {
     // The first entry in a malete database has id 1 and
     // not 0, therefore $id's initial value should be 1.
     $id = 1;
diff --git a/classes/PhpIsisDb.php b/classes/PhpIsisDb.php
index 03e9b7c..aa1c239 100644
--- a/classes/PhpIsisDb.php
+++ b/classes/PhpIsisDb.php
@@ -69,11 +69,11 @@ class PhpIsisDb implements IsisDb {
   }
 
   /**
-   * Return number of rows in the database.
+   * Return number of entries in the database.
    *
-   * @see IsisDb::rows()
+   * @see IsisDb::entries()
    */    
-  public function rows() {
+  public function entries() {
     return isis_last_mfn($this->db);
   }
 
diff --git a/tests/csv.php b/tests/csv.php
index 57bb890..e50249b 100644
--- a/tests/csv.php
+++ b/tests/csv.php
@@ -60,9 +60,9 @@ $isis = new CinisisDb();
 
 // Test connection.
 if ($isis->db) {
-  // Get format and number of rows.
-  $rows   = $isis->db->rows();
-  $format = $isis->db->format;
+  // Get format and number of entries.
+  $entries = $isis->db->entries();
+  $format  = $isis->db->format;
 
   // Prepare output.
   header("Content-type: application/text/x-csv");
@@ -84,7 +84,7 @@ if ($isis->db) {
   echo "\n";
 
   // Format output.
-  for ($n = 1; $n <= $rows; $n++) {
+  for ($n = 1; $n <= $entries; $n++) {
     $result = $isis->db->read($n);
 
     if ($result) {
diff --git a/tests/index.php b/tests/index.php
index 5a14f22..ebd465f 100644
--- a/tests/index.php
+++ b/tests/index.php
@@ -21,13 +21,13 @@ $isis = new CinisisDb();
 
 // Test connection.
 if ($isis->db) {
-  $result = $isis->db->read(1);
-  $rows   = $isis->db->rows();
+  $result  = $isis->db->read(1);
+  $entries = $isis->db->entries();
 
   // Format output.
   echo '<pre>';
   echo "Connection test:\n";
-  echo "Rows: $rows\n";
+  echo "Rows: $entries\n";
   print_r($result);
   echo '</pre>';
 }
diff --git a/tests/read.php b/tests/read.php
index 2cb49ac..1235c25 100644
--- a/tests/read.php
+++ b/tests/read.php
@@ -35,14 +35,14 @@ foreach ($configs as $config) {
 
   // Test connection.
   if ($isis->db) {
-    $result = $isis->db->read(1);
-    $rows   = $isis->db->rows();
+    $result  = $isis->db->read(1);
+    $entries = $isis->db->entries();
 
     // Format output.
     echo '<td>';
     echo '<pre>';
     echo 'Implementation: '. $config['implementation'] ."\n";
-    echo "Rows: $rows\n";
+    echo "Rows: $entries\n";
     print_r($result);
     echo '</pre>';
     echo '</td>';