Merge branch 'develop'

* develop:
  Add changelog
  Reword GROUP BY docs
  Add support for GROUP BY - issue #13
  Add support for DISTINCT - issue #13
  Fix a failing test caused by count() refactor
  Guard against missing result in count method
  Refactor and simplify count() method
  Fix cache key generation bug
  Add simple query caching - issue #11
  Refactor the way query results are fetched internally.
  Add is_dirty method to check whether a field has modified

1 files changed, 54 insertions, 0 deletions

diff --git a/README.markdown b/README.markdown
index b6ef1a6..10321f7 100644
--- a/README.markdown
+++ b/README.markdown
@@ -22,6 +22,20 @@ Features
 * Consists of just one class called `ORM`. Minimal global namespace pollution.
 * Database agnostic. Currently supports SQLite and MySQL. May support others, please give it a try!
 
+Changelog
+---------
+
+#### 1.0.0 - released 2010-12-01
+
+* Initial release
+
+#### 1.0.1 - released 2011-01-24
+
+* Add `is_dirty` method
+* Add basic query caching
+* Add `distinct` method
+* Add `group_by` method
+
 Philosophy
 ----------
 
@@ -182,6 +196,14 @@ Two methods are provided to add `ORDER BY` clauses to your query. These are `ord
 
     $people = ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many();
 
+#### Grouping ####
+
+*Note that this method **does not** escape it query parameter and so this should **not** by passed directly from user input.*
+
+To add a `GROUP BY` clause to your query, call the `group_by` method, passing in the column name. You can call this method multiple times to add further columns.
+
+    $poeple = ORM::for_table('person')->where('gender', 'female')->group_by('name')->find_many();
+
 #### Result columns ####
 
 By default, all columns in the `SELECT` statement are returned from your query. That is, calling:
@@ -225,6 +247,16 @@ Will result in the query:
 
     SELECT COUNT(*) AS `count` FROM `person`;
 
+#### DISTINCT ####
+
+To add a `DISTINCT` keyword before the list of result columns in your query, add a call to `distinct()` to your query chain.
+
+    $distinct_names = ORM::for_table('person')->distinct()->select('name')->find_many();
+
+This will result in the query:
+
+    SELECT DISTINCT `name` FROM `person`;
+
 #### Joins ####
 
 Idiorm has a family of methods for adding different types of `JOIN`s to the queries it constructs:
@@ -313,6 +345,12 @@ To add a new record, you need to first create an "empty" object instance. You th
 
 After the object has been saved, you can call its `id()` method to find the autogenerated primary key value that the database assigned to it.
 
+### Checking whether a property has been modified ###
+
+To check whether a property has been changed since the object was created (or last saved), call the `is_dirty` method:
+
+    $name_has_changed = $person->is_dirty('name'); // Returns true or false
+
 ### Deleting records ###
 
 To delete an object from the database, simply call its `delete` method.
@@ -402,3 +440,19 @@ Setting: `logging`
 Idiorm can log all queries it executes. To enable query logging, set the `logging` option to `true` (it is `false` by default).
 
 When query logging is enabled, you can use two static methods to access the log. `ORM::get_last_query()` returns the most recent query executed. `ORM::get_query_log()` returns an array of all queries executed.
+
+#### Query caching ####
+
+Setting: `caching`
+
+Idiorm can cache the queries it executes during a request. To enable query caching, set the `caching` option to `true` (it is `false` by default).
+
+When query caching is enabled, Idiorm will cache the results of every `SELECT` query it executes. If Idiorm encounters a query that has already been run, it will fetch the results directly from its cache and not perform a database query.
+
+##### Warnings and gotchas #####
+
+* Note that this is an in-memory cache that only persists data for the duration of a single request. This is *not* a replacement for a persistent cache such as [Memcached](http://www.memcached.org/).
+
+* Idiorm's cache is very simple, and does not attempt to invalidate itself when data changes. This means that if you run a query to retrieve some data, modify and save it, and then run the same query again, the results will be stale (ie, they will not reflect your modifications). This could potentially cause subtle bugs in your application. If you have caching enabled and you are experiencing odd behaviour, disable it and try again. If you do need to perform such operations but still wish to use the cache, you can call the `ORM::clear_cache()` to clear all existing cached queries.
+
+* Enabling the cache will increase the memory usage of your application, as all database rows that are fetched during each request are held in memory. If you are working with large quantities of data, you may wish to disable the cache.