From f3556016aa899ffd991ec386e3c1bfcb1feb4fbb Mon Sep 17 00:00:00 2001
From: Justin Kramer <jkkramer@gmail.com>
Date: Fri, 13 Jul 2012 09:57:47 -0400
Subject: [PATCH] readme update

---
 README.md   | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 project.clj |  2 +-
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ecd4c01..313fec3 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,58 @@
 # Honey SQL
 
-SQL as data structures. Or SQL sugar, as it were.
+SQL as Clojure data structures.
+
+**Work in progress**
 
 ## Usage
 
-FIXME
+```clj
+(require '[honeysql.core :refer [format-sql sql merge-sql sql-fn sql-raw]])
+
+;; Everything is centered around maps representing SQL queries
+(def sqlmap {:select [:a :b :c]
+             :from [:foo]
+             :where [:= :f.a "baz"]})
+
+;; format-sql turns maps into clojure.java.jdbc-compatible, parameterized SQL
+(format-sql sqlmap)
+=> ["SELECT a, b, c FROM foo WHERE (f.a = ?)" ["baz"]]
+
+;; The sql function is a helper for building query maps
+(= sqlmap
+   (sql :select [:a :b :c]
+        :from :foo
+        :where [:= :f.a "baz"]))
+=> true
+
+;; Providing a map as the first argument to sql will use that map as a base,
+;; with the new clauses replacing old ones
+(format-sql (sql sqlmap :select :* :limit 10))
+=> ["SELECT * FROM foo WHERE (f.a = ?) LIMIT 10" ["baz"]]
+
+;; To add to clauses instead of replacing them, use merge-sql
+(format-sql
+  (merge-sql sqlmap :select [:d :e] :where [:> :b 10]))
+=> ["SELECT a, b, c, d, e FROM foo WHERE ((f.a = ?) AND (b > 10))" ["baz"]]
+
+;; Queries can be nested
+(format-sql
+  (sql :select :*
+       :from :foo
+       :where [:in :foo.a (sql :select :a
+                               :from :bar)]))
+=> ["SELECT * FROM foo WHERE (foo.a IN (SELECT a FROM bar))"]
+
+;; There are helper functions and data literals for handling SQL function
+;; calls and raw SQL fragments
+(sql :select [(sql-fn :count :*) (sql-raw "@var := foo.bar")]
+     :from :foo)
+=> {:from (:foo), :select (#sql/fn [:count :*] #sql/raw "@var := foo.bar")}
+
+(format-sql *1)
+=> ["SELECT COUNT(*), @var := foo.bar FROM foo"]
+
+```
 
 ## License
 
diff --git a/project.clj b/project.clj
index ee2e657..5f98386 100644
--- a/project.clj
+++ b/project.clj
@@ -1,5 +1,5 @@
 (defproject honeysql "0.1.0-SNAPSHOT"
-  :description "SQL as data structures"
+  :description "SQL as Clojure data structures"
   :license {:name "Eclipse Public License"
             :url "http://www.eclipse.org/legal/epl-v10.html"}
   :dependencies [[org.clojure/clojure "1.4.0"]])