move to markdown for syntax awesomeness

Author: brianmario

README.rdoc renamed to README.md

@@ -1,4 +1,4 @@
-= Mysql2 - A modern, simple and very fast Mysql library for Ruby - binding to libmysql
+# Mysql2 - A modern, simple and very fast Mysql library for Ruby - binding to libmysql
 
 The Mysql2 gem is meant to serve the extremely common use-case of connecting, querying and iterating on results.
 Some database libraries out there serve as direct 1:1 mappings of the already complex C API's available.
@@ -12,198 +12,237 @@ Mysql2::Client - your connection to the database
 
 Mysql2::Result - returned from issuing a #query on the connection. It includes Enumerable.
 
-== Installing
+## Installing
 
-  gem install mysql2
+``` sh
+gem install mysql2
+```
 
 You may have to specify --with-mysql-config=/some/random/path/bin/mysql_config
 
-== Usage
+## Usage
 
 Connect to a database:
 
-  # this takes a hash of options, almost all of which map directly
-  # to the familiar database.yml in rails
-  # See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
-  client = Mysql2::Client.new(:host => "localhost", :username => "root")
+``` ruby
+# this takes a hash of options, almost all of which map directly
+# to the familiar database.yml in rails
+# See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
+client = Mysql2::Client.new(:host => "localhost", :username => "root")
+```
 
 Then query it:
 
-  results = client.query("SELECT * FROM users WHERE group='githubbers'")
+``` ruby
+results = client.query("SELECT * FROM users WHERE group='githubbers'")
+```
 
 Need to escape something first?
 
-  escaped = client.escape("gi'thu\"bbe\0r's")
-  results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
+``` ruby
+escaped = client.escape("gi'thu\"bbe\0r's")
+results = client.query("SELECT * FROM users WHERE group='#{escaped}'")
+```
 
 Finally, iterate over the results:
 
-  results.each do |row|
-    # conveniently, row is a hash
-    # the keys are the fields, as you'd expect
-    # the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
-    # Here's an otter: http://farm1.static.flickr.com/130/398077070_b8795d0ef3_b.jpg
-  end
+``` ruby
+results.each do |row|
+  # conveniently, row is a hash
+  # the keys are the fields, as you'd expect
+  # the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
+  # Here's an otter: http://farm1.static.flickr.com/130/398077070_b8795d0ef3_b.jpg
+end
+```
 
 Or, you might just keep it simple:
 
-  client.query("SELECT * FROM users WHERE group='githubbers'").each do |row|
-    # do something with row, it's ready to rock
-  end
+``` ruby
+client.query("SELECT * FROM users WHERE group='githubbers'").each do |row|
+  # do something with row, it's ready to rock
+end
+```
 
 How about with symbolized keys?
 
-  # NOTE: the :symbolize_keys and future options will likely move to the #query method soon
-  client.query("SELECT * FROM users WHERE group='githubbers'").each(:symbolize_keys => true) do |row|
-    # do something with row, it's ready to rock
-  end
+``` ruby
+# NOTE: the :symbolize_keys and future options will likely move to the #query method soon
+client.query("SELECT * FROM users WHERE group='githubbers'").each(:symbolize_keys => true) do |row|
+  # do something with row, it's ready to rock
+end
+```
 
 You can get the headers and the columns in the order that they were returned
 by the query like this:
 
-  headers = results.fields # <= that's an array of field names, in order
-  results.each(:as => :array) do |row|
-  # Each row is an array, ordered the same as the query results
-  # An otter's den is called a "holt" or "couch"
-  end
+``` ruby
+headers = results.fields # <= that's an array of field names, in order
+results.each(:as => :array) do |row|
+# Each row is an array, ordered the same as the query results
+# An otter's den is called a "holt" or "couch"
+end
+```
 
-== Cascading config
+## Cascading config
 
 The default config hash is at:
 
- Mysql2::Client.default_query_options
+``` ruby
+Mysql2::Client.default_query_options
+```
 
 which defaults to:
 
- {:async => false, :as => :hash, :symbolize_keys => false}
+``` ruby
+{:async => false, :as => :hash, :symbolize_keys => false}
+```
 
 that can be used as so:
 
- # these are the defaults all Mysql2::Client instances inherit
- Mysql2::Client.default_query_options.merge!(:as => :array)
+``` ruby
+# these are the defaults all Mysql2::Client instances inherit
+Mysql2::Client.default_query_options.merge!(:as => :array)
+```
 
 or
 
- # this will change the defaults for all future results returned by the #query method _for this connection only_
- c = Mysql2::Client.new
- c.query_options.merge!(:symbolize_keys => true)
+``` ruby
+# this will change the defaults for all future results returned by the #query method _for this connection only_
+c = Mysql2::Client.new
+c.query_options.merge!(:symbolize_keys => true)
+```
 
 or
 
- # this will set the options for the Mysql2::Result instance returned from the #query method
- c = Mysql2::Client.new
- c.query(sql, :symbolize_keys => true)
+``` ruby
+# this will set the options for the Mysql2::Result instance returned from the #query method
+c = Mysql2::Client.new
+c.query(sql, :symbolize_keys => true)
+```
 
-== Result types
+## Result types
 
-=== Array of Arrays
+### Array of Arrays
 
-Pass the :as => :array option to any of the above methods of configuration
+Pass the `:as => :array` option to any of the above methods of configuration
 
-=== Array of Hashes
+### Array of Hashes
 
 The default result type is set to :hash, but you can override a previous setting to something else with :as => :hash
 
-=== Others...
+### Others...
 
-I may add support for :as => :csv or even :as => :json to allow for *much* more efficient generation of those data types from result sets.
+I may add support for `:as => :csv` or even `:as => :json` to allow for *much* more efficient generation of those data types from result sets.
 If you'd like to see either of these (or others), open an issue and start bugging me about it ;)
 
-=== Timezones
+### Timezones
 
 Mysql2 now supports two timezone options:
 
-  :database_timezone - this is the timezone Mysql2 will assume fields are already stored as, and will use this when creating the initial Time objects in ruby
-  :application_timezone - this is the timezone Mysql2 will convert to before finally handing back to the caller
+``` ruby
+:database_timezone # this is the timezone Mysql2 will assume fields are already stored as, and will use this when creating the initial Time objects in ruby
+:application_timezone # this is the timezone Mysql2 will convert to before finally handing back to the caller
+```
 
-In other words, if :database_timezone is set to :utc - Mysql2 will create the Time objects using Time.utc(...) from the raw value libmysql hands over initially.
-Then, if :application_timezone is set to say - :local - Mysql2 will then convert the just-created UTC Time object to local time.
+In other words, if `:database_timezone` is set to `:utc` - Mysql2 will create the Time objects using `Time.utc(...)` from the raw value libmysql hands over initially.
+Then, if `:application_timezone` is set to say - `:local` - Mysql2 will then convert the just-created UTC Time object to local time.
 
-Both options only allow two values - :local or :utc - with the exception that :application_timezone can be [and defaults to] nil
+Both options only allow two values - `:local` or `:utc` - with the exception that `:application_timezone` can be [and defaults to] nil
 
-=== Casting "boolean" columns
+### Casting "boolean" columns
 
 You can now tell Mysql2 to cast tinyint(1) fields to boolean values in Ruby with the :cast_booleans option.
 
-  client = Mysql2::Client.new
-  result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
+``` ruby
+client = Mysql2::Client.new
+result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
+```
 
-=== Async
+### Async
 
 Mysql2::Client takes advantage of the MySQL C API's (undocumented) non-blocking function mysql_send_query for *all* queries.
 But, in order to take full advantage of it in your Ruby code, you can do:
 
-  client.query("SELECT sleep(5)", :async => true)
+``` ruby
+client.query("SELECT sleep(5)", :async => true)
+```
 
 Which will return nil immediately. At this point you'll probably want to use some socket monitoring mechanism
 like EventMachine or even IO.select. Once the socket becomes readable, you can do:
 
-  # result will be a Mysql2::Result instance
-  result = client.async_result
+``` ruby
+# result will be a Mysql2::Result instance
+result = client.async_result
+```
 
 NOTE: Because of the way MySQL's query API works, this method will block until the result is ready.
 So if you really need things to stay async, it's best to just monitor the socket with something like EventMachine.
 If you need multiple query concurrency take a look at using a connection pool.
 
-=== Row Caching
+### Row Caching
 
 By default, Mysql2 will cache rows that have been created in Ruby (since this happens lazily).
 This is especially helpful since it saves the cost of creating the row in Ruby if you were to iterate over the collection again.
 
-If you only plan on using each row once, then it's much more efficient to disable this behavior by setting the :cache_rows option to false.
+If you only plan on using each row once, then it's much more efficient to disable this behavior by setting the `:cache_rows` option to false.
 This would be helpful if you wanted to iterate over the results in a streaming manner. Meaning the GC would cleanup rows you don't need anymore as you're iterating over the result set.
 
-== ActiveRecord
+## ActiveRecord
 
 To use the ActiveRecord driver (with our without rails), all you should need to do is have this gem installed and set the adapter in your database.yml to "mysql2".
 That was easy right? :)
 
-== Asynchronous ActiveRecord
+NOTE: as of 0.3.0, and ActiveRecord 3.1 - the ActiveRecord adapter has been pulled out of this gem and into ActiveRecord itself. If you need to use mysql2 with
+Rails versions < 3.1 make sure and specify `gem "mysql2", "~> 0.2.7"` in your Gemfile
+
+## Asynchronous ActiveRecord
 
 You can also use Mysql2 with asynchronous Rails (first introduced at http://www.mikeperham.com/2010/04/03/introducing-phat-an-asynchronous-rails-app/) by
 setting the adapter in your database.yml to "em_mysql2".  You must be running Ruby 1.9, thin and the rack-fiber_pool middleware for it to work.
 
-== Sequel
+## Sequel
 
 The Sequel adapter was pulled out into Sequel core (will be part of the next release) and can be used by specifying the "mysql2://" prefix to your connection specification.
 
-== EventMachine
+## EventMachine
 
 The mysql2 EventMachine deferrable api allows you to make async queries using EventMachine,
 while specifying callbacks for success for failure. Here's a simple example:
 
-  require 'mysql2/em'
+``` ruby
+require 'mysql2/em'
 
-  EM.run do
-    client1 = Mysql2::EM::Client.new
-    defer1 = client1.query "SELECT sleep(3) as first_query"
-    defer1.callback do |result|
-      puts "Result: #{result.to_a.inspect}"
-    end
+EM.run do
+  client1 = Mysql2::EM::Client.new
+  defer1 = client1.query "SELECT sleep(3) as first_query"
+  defer1.callback do |result|
+    puts "Result: #{result.to_a.inspect}"
+  end
 
-    client2 = Mysql2::EM::Client.new
-    defer2 = client2.query "SELECT sleep(1) second_query"
-    defer2.callback do |result|
-      puts "Result: #{result.to_a.inspect}"
-    end
+  client2 = Mysql2::EM::Client.new
+  defer2 = client2.query "SELECT sleep(1) second_query"
+  defer2.callback do |result|
+    puts "Result: #{result.to_a.inspect}"
   end
+end
+```
 
-== Lazy Everything
+## Lazy Everything
 
 Well... almost ;)
 
 Field name strings/symbols are shared across all the rows so only one object is ever created to represent the field name for an entire dataset.
 
 Rows themselves are lazily created in ruby-land when an attempt to yield it is made via #each.
-For example, if you were to yield 4 rows from a 100 row dataset, only 4 hashes will be created. The rest will sit and wait in C-land until you want them (or when the GC goes to cleanup your Mysql2::Result instance).
+For example, if you were to yield 4 rows from a 100 row dataset, only 4 hashes will be created. The rest will sit and wait in C-land until you want them (or when the GC goes to cleanup your `Mysql2::Result` instance).
 Now say you were to iterate over that same collection again, this time yielding 15 rows - the 4 previous rows that had already been turned into ruby hashes would be pulled from an internal cache, then 11 more would be created and stored in that cache.
 Once the entire dataset has been converted into ruby objects, Mysql2::Result will free the Mysql C result object as it's no longer needed.
 
 This caching behavior can be disabled by setting the :cache_rows option to false.
 
 As for field values themselves, I'm workin on it - but expect that soon.
 
-== Compatibility
+## Compatibility
 
 The specs pass on my system (SL 10.6.3, x86_64) in these rubies:
 
@@ -215,7 +254,7 @@ The specs pass on my system (SL 10.6.3, x86_64) in these rubies:
 
 The ActiveRecord driver should work on 2.3.5 and 3.0
 
-== Yeah... but why?
+## Yeah... but why?
 
 Someone: Dude, the Mysql gem works fiiiiiine.
 
@@ -227,29 +266,34 @@ Someone: OK fine, but do_mysql can already give me back values with Ruby objects
 
 Me: Yep, but it's API is considerably more complex *and* can be ~2x slower.
 
-== Benchmarks
+## Benchmarks
 
 Performing a basic "SELECT * FROM" query on a table with 30k rows and fields of nearly every Ruby-representable data type,
 then iterating over every row using an #each like method yielding a block:
 
-# These results are from the query_with_mysql_casting.rb script in the benchmarks folder
-   user       system     total       real
-  Mysql2
-   0.750000   0.180000   0.930000 (  1.821655)
-  do_mysql
-   1.650000   0.200000   1.850000 (  2.811357)
-  Mysql
-   7.500000   0.210000   7.710000 (  8.065871)
+These results are from the `query_with_mysql_casting.rb` script in the benchmarks folder
+
+``` sh
+ user       system     total       real
+Mysql2
+ 0.750000   0.180000   0.930000 (  1.821655)
+do_mysql
+ 1.650000   0.200000   1.850000 (  2.811357)
+Mysql
+ 7.500000   0.210000   7.710000 (  8.065871)
+```
 
-== Development
+## Development
 
 To run the tests, you can use RVM and Bundler to create a pristine environment for mysql2 development/hacking.
 Use 'bundle install' to install the necessary development and testing gems:
 
-    bundle install
-    rake
+``` sh
+bundle install
+rake
+```
 
-== Special Thanks
+## Special Thanks
 
 * Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
 * Yury Korolev (http://github.com/yury) - for TONS of help testing the ActiveRecord adapter