From: Michael Wallner <mike@php.net>
Date: Wed, 15 Oct 2014 14:51:50 +0000 (+0200)
Subject: finished Row
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=7ea2f1057ec672dca70fe59926ee2b6c0538f408;p=mdref%2Fmdref-pq-gateway

finished Row
---

diff --git a/pq-gateway/pq/Gateway/Row.md b/pq-gateway/pq/Gateway/Row.md
new file mode 100644
index 0000000..430558b
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row.md
@@ -0,0 +1,13 @@
+# class pq\Gateway\Row implements JsonSerializable
+
+The row gateway.
+
+## Properties:
+
+* protected pq\Gateway\Table $table  
+  The originating table.
+* protected array $data  
+  The row's data.
+* protected array $cell  
+  The list of cells abstracting access to the row's data.
+
diff --git a/pq-gateway/pq/Gateway/Row/__construct.md b/pq-gateway/pq/Gateway/Row/__construct.md
new file mode 100644
index 0000000..9351b9b
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__construct.md
@@ -0,0 +1,13 @@
+# void pq\Gateway\Row::__construct(pq\Gateway\Table $table[, array $data = NULL[, bool $prime = FALSE]])
+
+Create a new row gateway.
+
+## Params:
+
+* pq\Gateway\Table $table  
+  The originating table.
+* Optional array $data = NULL  
+  The data of the row.
+* Optional bool $prime = FALSE  
+  Whether to prime the rows cells with the data.
+
diff --git a/pq-gateway/pq/Gateway/Row/__get.md b/pq-gateway/pq/Gateway/Row/__get.md
new file mode 100644
index 0000000..93cd1cf
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__get.md
@@ -0,0 +1,12 @@
+# pq\Gateway\Cell pq\Gateway\Row::__get(string $p)
+
+Cell read accessor through properties.
+
+## Params:
+
+* string $p  
+  The property/column name.
+
+## Returns:
+
+* pq\Gateway\Cell, the cell managing access to the column data.
diff --git a/pq-gateway/pq/Gateway/Row/__invoke.md b/pq-gateway/pq/Gateway/Row/__invoke.md
new file mode 100644
index 0000000..8117ae2
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__invoke.md
@@ -0,0 +1,12 @@
+# pq\Gateway\Row pq\Gateway\Row::__invoke(array $data)
+
+Copy constructor.
+
+## Params:
+
+* array $data  
+  The data of the clone of the row.
+
+## Returns:
+
+* pq\Gateway\Row, clone.
diff --git a/pq-gateway/pq/Gateway/Row/__isset.md b/pq-gateway/pq/Gateway/Row/__isset.md
new file mode 100644
index 0000000..8c64905
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__isset.md
@@ -0,0 +1,12 @@
+# bool pq\Gateway\Row::__isset(string $p)
+
+Check whether the column isset.
+
+## Params:
+
+* string $p  
+  The column/property name.
+
+## Returns:
+
+* bool, whether the column isset.
diff --git a/pq-gateway/pq/Gateway/Row/__set.md b/pq-gateway/pq/Gateway/Row/__set.md
new file mode 100644
index 0000000..cec6d05
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__set.md
@@ -0,0 +1,9 @@
+# void pq\Gateway\Row::__set(string $p)
+
+Cell write accessor through properties.
+See pq\Gateway\Cell::set().
+
+## Params:
+
+* string $p  
+  The property/column name.
diff --git a/pq-gateway/pq/Gateway/Row/__unset.md b/pq-gateway/pq/Gateway/Row/__unset.md
new file mode 100644
index 0000000..731d71d
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/__unset.md
@@ -0,0 +1,8 @@
+# void pq\Gateway\Row::__unset(string $p)
+
+Unset the columnd within the row.
+
+## Params:
+
+* string $p  
+  The property/column name.
diff --git a/pq-gateway/pq/Gateway/Row/allOf.md b/pq-gateway/pq/Gateway/Row/allOf.md
new file mode 100644
index 0000000..3d97bd9
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/allOf.md
@@ -0,0 +1,25 @@
+# mixed pq\Gateway\Row::allOf(mixed $foreign[, string $ref = NULL[, string $order = NULL[, int $limit = 0[, int $offset = 0]]]])
+
+Find the child rows by foreign key.
+See pq\Gateway\Table::of().
+
+## Params:
+
+* mixed $foreign  
+  The foreign table (name).
+* Optional string $ref = NULL  
+  A specific relation name if there are more than one foreign keys on the same table.
+* Optional string $order = NULL  
+  Sorting clause.
+* Optional int $limit = 0  
+  Row count limit.
+* Optional int $offset = 0  
+  Row count offset.
+
+## Returns:
+
+* a [deferred promise of React/Promise](https://github.com/reactphp/promise#deferred-1), when using pq\Query\AsyncExecutor, the asynchronous executor.  
+  Else:
+* pq\Result, if pq\Result::$status != pq\Result::TUPLES_OK.
+* pq\Result, if the rowset prototype pq\Gateway\Table::$rowset is empty.
+* pq\Gateway\Rowset, an instance of the rowset prototype.
diff --git a/pq-gateway/pq/Gateway/Row/cell.md b/pq-gateway/pq/Gateway/Row/cell.md
new file mode 100644
index 0000000..6f22032
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/cell.md
@@ -0,0 +1,13 @@
+# protected pq\Gateway\Cell pq\Gateway\Row::cell(string $col)
+
+Create or retrieve an already primed cell.
+
+## Params:
+
+* string $col  
+  The column name.
+
+
+## Returns:
+
+* pq\Gateway\Cell, the cell manging access to the column data.
diff --git a/pq-gateway/pq/Gateway/Row/changes.md b/pq-gateway/pq/Gateway/Row/changes.md
new file mode 100644
index 0000000..f065926
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/changes.md
@@ -0,0 +1,11 @@
+# protected pq\Gateway\Row::changes()
+
+Export modified data.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of modified columns and their values.
diff --git a/pq-gateway/pq/Gateway/Row/create.md b/pq-gateway/pq/Gateway/Row/create.md
new file mode 100644
index 0000000..3f85106
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/create.md
@@ -0,0 +1,12 @@
+# pq\Gateway\Row pq\Gateway\Row::create()
+
+Create this row in the database.
+Notifies the table about the "create" event.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Row, self.
diff --git a/pq-gateway/pq/Gateway/Row/criteria.md b/pq-gateway/pq/Gateway/Row/criteria.md
new file mode 100644
index 0000000..308f43a
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/criteria.md
@@ -0,0 +1,11 @@
+# protected array pq\Gateway\Row::criteria()
+
+Convert the row's identity to to where criteria.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of where criteria.
diff --git a/pq-gateway/pq/Gateway/Row/delete.md b/pq-gateway/pq/Gateway/Row/delete.md
new file mode 100644
index 0000000..3fea80b
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/delete.md
@@ -0,0 +1,16 @@
+# pq\Query\Row pq\Query\Row::delete()
+
+Delete this row in the database.
+Notifies the table about the "delete" event.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Row, self with primed cells.
+
+## Throws:
+
+* UnexpectedValueExceptio, if the result indicates that no row was deleted.
diff --git a/pq-gateway/pq/Gateway/Row/export.md b/pq-gateway/pq/Gateway/Row/export.md
new file mode 100644
index 0000000..04f1531
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/export.md
@@ -0,0 +1,15 @@
+# array pq\Gateway\Row::export()
+
+Export the current state.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the row's plain data.
+
+## Throws:
+
+* UnexpectedValueException, if any of the row's cells contain expressions.
diff --git a/pq-gateway/pq/Gateway/Row/exportPublic.md b/pq-gateway/pq/Gateway/Row/exportPublic.md
new file mode 100644
index 0000000..4446d8f
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/exportPublic.md
@@ -0,0 +1,12 @@
+# array pq\Gateway\Row::exportPublic()
+
+Export current state with security sensitive data removed.
+Calls pq\Gateway\Row::export() by default; to be overriden.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the row's plain data except security sensitive data like passwords, etc.
diff --git a/pq-gateway/pq/Gateway/Row/getData.md b/pq-gateway/pq/Gateway/Row/getData.md
new file mode 100644
index 0000000..adead57
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/getData.md
@@ -0,0 +1,11 @@
+# array pq\Gateway\Row::getData()
+
+Retrieve the original row data.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the original data.
diff --git a/pq-gateway/pq/Gateway/Row/getIdentity.md b/pq-gateway/pq/Gateway/Row/getIdentity.md
new file mode 100644
index 0000000..2e34cff
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/getIdentity.md
@@ -0,0 +1,15 @@
+# array pq\Gateway\Row::getIdentity()
+
+Retrieve a list of columns and their values (the primary key, if it exists, else all columns) to identify the row in the table.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of columns and values identifying this row.
+
+## Throws:
+
+* OutOfBoundsException, if a primary key column does not exist due to possible out-of-date cache.
diff --git a/pq-gateway/pq/Gateway/Row/getTable.md b/pq-gateway/pq/Gateway/Row/getTable.md
new file mode 100644
index 0000000..91a28aa
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/getTable.md
@@ -0,0 +1,11 @@
+# pq\Gateway\Table pq\Gateway\Row::getTable()
+
+Retrieve the table from which this row originates.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Table, the originating table.
diff --git a/pq-gateway/pq/Gateway/Row/isDirty.md b/pq-gateway/pq/Gateway/Row/isDirty.md
new file mode 100644
index 0000000..754a779
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/isDirty.md
@@ -0,0 +1,11 @@
+# bool pq\Gateway\Row::isDirty()
+
+Whether the row has been modified.
+
+## Params:
+
+None.
+
+## Returns:
+
+* bool, whether any the row's cell is dirty.
diff --git a/pq-gateway/pq/Gateway/Row/jsonSerialize.md b/pq-gateway/pq/Gateway/Row/jsonSerialize.md
new file mode 100644
index 0000000..bf0ad98
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/jsonSerialize.md
@@ -0,0 +1,12 @@
+# array pq\Gateway\Row::jsonSerialize()
+
+Implements JsonSerializable.
+Calls pq\Gateway\Row::exportPublic() by default.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the row's data for JSON serialization.
diff --git a/pq-gateway/pq/Gateway/Row/ofWhich.md b/pq-gateway/pq/Gateway/Row/ofWhich.md
new file mode 100644
index 0000000..32828a0
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/ofWhich.md
@@ -0,0 +1,19 @@
+# mixed pq\Gateway\Row::ofWhich(mixed $foreign[, string $ref = NULL])
+
+Find the parent row by foreign key.
+See pq\Gateway\Table::by().
+
+## Params:
+
+* mixed $foreign  
+  The foreign table (name).
+* Optional string $ref = NULL  
+  A specific relation name if there are more than one foreign keys to the same table.
+
+## Returns:
+
+* a [deferred promise of React/Promise](https://github.com/reactphp/promise#deferred-1), when using pq\Query\AsyncExecutor, the asynchronous executor.  
+  Else:
+* pq\Result, if pq\Result::$status != pq\Result::TUPLES_OK.
+* pq\Result, if the rowset prototype pq\Gateway\Table::$rowset is empty.
+* pq\Gateway\Rowset, an instance of the rowset prototype.
diff --git a/pq-gateway/pq/Gateway/Row/prime.md b/pq-gateway/pq/Gateway/Row/prime.md
new file mode 100644
index 0000000..8c48040
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/prime.md
@@ -0,0 +1,11 @@
+# protected pq\Gateway\Row pq\Gateway\Row::prime()
+
+Prime the cells with dirty data.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Row, self.
diff --git a/pq-gateway/pq/Gateway/Row/refresh.md b/pq-gateway/pq/Gateway/Row/refresh.md
new file mode 100644
index 0000000..05f4dd0
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/refresh.md
@@ -0,0 +1,12 @@
+# pq\Gateway\Row pq\Gateway\Row::refresh()
+
+Refresh the columns data from the table.
+Resets all modifications.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Row, self.
diff --git a/pq-gateway/pq/Gateway/Row/update.md b/pq-gateway/pq/Gateway/Row/update.md
new file mode 100644
index 0000000..8646fd2
--- /dev/null
+++ b/pq-gateway/pq/Gateway/Row/update.md
@@ -0,0 +1,16 @@
+# pq\Gateway\Row pq\Gateway\Row::update()
+
+Update this row in the database.
+Notifies the table about the "update" event.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Gateway\Row, self.
+
+## Throws:
+
+* UnexpectedValueExceptio, if the result indicates that no row was updated.