doc: complete guide how to use squirrel

EXAMPLE.md

@@ -0,0 +1,87 @@
+# Complete Guide to Use Squirrel.
+
+### WHERE
+```go
+import sq "github.com/Masterminds/squirrel"
+
+// Single condition.
+query, args, err := sq.Select("*").From("users").Where("id = ?", 1).ToSql()
+
+// Multiple condition.
+query, args, err := sq.Select("*").From("users").Where(sq.Eq{
+	"age":   15,
+	"name": "alex",
+}).ToSql()
+
+// Using IN
+activeUserIds := []int{1, 2}
+query, args, err := sq.Select("*").From("users").Where("id IN (?, ?)", activeUserIds...).ToSql()
+
+// an alternative to using IN
+query, args, err := sq.Select("*").From("users").Where(sq.Eq{"id": []int{1, 2, 3, 4, 5}}).ToSql()
+```
+
+### INSERT
+```go
+import sq "github.com/Masterminds/squirrel"
+
+query, args, err := sq.Insert("users").Columns("name", "age").Values("John Doe", 25).ToSql()
+
+// Or using key value map like syntax.
+query, args, err := sq.Insert("users").SetMap(sq.Eq{
+    "name": "John Doe", 
+    "age":  25,
+}).ToSql()
+```
+
+### UPDATE
+```go
+import sq "github.com/Masterminds/squirrel"
+
+query, args, err := sq.Update("users").Set("age", 30).Where(sq.Eq{"id": 1}).ToSql()
+
+// Or using key value map like syntax.
+query, args, err := sq.Update("users").SetMap(sq.Eq{
+    "age": 30
+}).Where(sq.Eq{"id": 1}).ToSql()
+```
+
+### DELETE
+```go
+import sq "github.com/Masterminds/squirrel"
+
+query, args, err := sq.Delete("users").Where("id = ?", 1)
+```
+
+### SELECT
+```go
+import sq "github.com/Masterminds/squirrel"
+
+query, args, err := sq.Select("id", "name", "age").From("users").Where("deleted_at IS NULL")
+```
+
+### JOIN, LEFT JOIN & RIGHT JOIN
+```go
+import sq "github.com/Masterminds/squirrel"
+
+query, args, err := sq.
+	Select("users.name AS person_name", "class.name AS class_name").
+	From("users").
+	Join("class ON class.id = users.class_id").
+	Where("users.id = ?", 1).
+	ToSql()
+
+query, args, err := sq.
+	Select("users.name AS person_name", "class.name AS class_name").
+	From("users").
+	LeftJoin("class ON class.id = users.class_id").
+	Where("users.id = ?", 1).
+	ToSql()
+
+query, args, err := sq.
+	Select("users.name AS person_name", "class.name AS class_name").
+	From("users").
+	RightJoin("class ON class.id = users.class_id").
+	Where("users.id = ?", 1).
+	ToSql()
+```

README.md

@@ -106,6 +106,8 @@ will generate with the Dollar Placeholder:
 SELECT * FROM nodes WHERE meta->'format' ?| array[$1,$2]
 ```
 
+for more complete guide how to use squirrel, please check [EXAMPLE.md](EXAMPLE.md). 
+
 ## FAQ
 
 * **How can I build an IN query on composite keys / tuples, e.g. `WHERE (col1, col2) IN ((1,2),(3,4))`? ([#104](https://github.com/Masterminds/squirrel/issues/104))**
@@ -128,10 +130,6 @@ SELECT * FROM nodes WHERE meta->'format' ?| array[$1,$2]
 
     Values of type `[]byte` are handled specially by `database/sql`. In Go, [`byte` is just an alias of `uint8`](https://golang.org/pkg/builtin/#byte), so there is no way to distinguish `[]uint8` from `[]byte`.
 
-* **Some features are poorly documented!**
-
-    This isn't a frequent complaints section!
-
 * **Some features are poorly documented?**
 
     Yes. The tests should be considered a part of the documentation; take a look at those for ideas on how to express more complex queries.