Update README.md and license. Add examples

Signed-off-by: Vartan Benohanian <vartanbeno@gmail.com>

LICENSE

@@ -17,3 +17,35 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+======================
+Portions of the client are based on code at:
+https://github.com/google/go-github/
+
+Copyright (c) 2013 The go-github AUTHORS. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -2,6 +2,8 @@
 
 go-reddit is a Go client library for accessing the Reddit API.
 
+You can view Reddit's official API documentation [here](https://www.reddit.com/dev/api/).
+
 ## Install
 
 To get a specific version from the list of [versions](https://github.com/vartanbeno/go-reddit/releases):
@@ -15,3 +17,67 @@ Or for the latest version:
 ```sh
 go get github.com/vartanbeno/go-reddit
 ```
+
+## Usage
+
+Make sure to have a Reddit app with a valid client id and secret. [Here](https://github.com/reddit-archive/reddit/wiki/OAuth2-Quick-Start-Example#first-steps) is a quick guide on how to create an app and get credentials.
+
+```go
+package main
+
+import "github.com/vartanbeno/go-reddit"
+
+func main() {
+    withCredentials := reddit.WithCredentials("id", "secret", "username", "password")
+    client, _ := reddit.NewClient(nil, withCredentials)
+}
+```
+
+The first argument (the one set to `nil`) is of type `*http.Client`. It will be used to make the requests. If nil, it will be set to `&http.Client{}`.
+
+The `WithCredentials` option sets the credentials used to make requests to the Reddit API.
+
+## Examples
+
+<details>
+    <summary>Configure the client from environment variables.</summary>
+
+```go
+client, _ := reddit.NewClient(nil, reddit.FromEnv)
+```
+</details>
+
+<details>
+    <summary>Upvote a post.</summary>
+
+```go
+_, err := client.Post.Upvote(context.Background(), "t3_postid")
+if err != nil {
+    fmt.Printf("Something bad happened: %v\n", err)
+    return err
+}
+```
+</details>
+
+<details>
+    <summary>Get a subreddit's top 5 posts of all time.</summary>
+
+```go
+result, _, err := client.Subreddit.Top(context.Background(), "golang", reddit.SetLimit(5), reddit.FromAllTime)
+if err != nil {
+    fmt.Printf("Something bad happened: %v\n", err)
+    return err
+}
+fmt.Printf("Received %d posts.\n", len(result.Posts))
+```
+</details>
+
+More examples are available in the [examples](examples) folder.
+
+## Design
+
+The package design and structure are heavily inspired from [Google's GitHub API client](https://github.com/google/go-github) and [DigitalOcean's API client](https://github.com/digitalocean/godo).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

examples/client-on-request-completed/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/vartanbeno/go-reddit"
+)
+
+var ctx = context.Background()
+
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() (err error) {
+	withCredentials := reddit.WithCredentials("id", "secret", "username", "password")
+
+	client, err := reddit.NewClient(nil, withCredentials)
+	if err != nil {
+		return
+	}
+
+	client.OnRequestCompleted(logResponse)
+
+	client.Subreddit.Search(ctx, "programming", reddit.SetLimit(10))
+	client.Subreddit.SearchNames(ctx, "monitor")
+	client.Subreddit.SearchPosts(ctx, "react", "webdev", reddit.SortByNumberOfComments)
+	client.User.Posts(ctx, reddit.SetLimit(50))
+
+	return
+}
+
+func logResponse(req *http.Request, res *http.Response) {
+	fmt.Printf("%s %s %s\n", req.Method, req.URL, res.Status)
+}

examples/get-subreddit/main.go

@@ -0,0 +1,35 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/vartanbeno/go-reddit"
+)
+
+var ctx = context.Background()
+
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() (err error) {
+	withCredentials := reddit.WithCredentials("id", "secret", "username", "password")
+
+	client, err := reddit.NewClient(nil, withCredentials)
+	if err != nil {
+		return
+	}
+
+	sr, _, err := client.Subreddit.Get(ctx, "golang")
+	if err != nil {
+		return
+	}
+
+	fmt.Printf("%s was created on %s and has %d subscribers.\n", sr.NamePrefixed, sr.Created.Local(), sr.Subscribers)
+
+	return
+}

examples/get-top-posts/main.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/vartanbeno/go-reddit"
+)
+
+var ctx = context.Background()
+
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() (err error) {
+	withCredentials := reddit.WithCredentials("id", "secret", "username", "password")
+
+	client, err := reddit.NewClient(nil, withCredentials)
+	if err != nil {
+		return
+	}
+
+	// Let's get the top 200 posts of r/golang.
+	// Reddit returns a maximum of 100 posts at a time,
+	// so we'll need to separate this into 2 requests.
+	result, _, err := client.Subreddit.Top(ctx, "golang", reddit.SetLimit(100), reddit.FromAllTime)
+	if err != nil {
+		return
+	}
+
+	for _, post := range result.Posts {
+		fmt.Println(post.Title)
+	}
+
+	// The SetAfter option sets the id of an item that Reddit
+	// will use as an anchor point for the returned listing.
+	result, _, err = client.Subreddit.Top(ctx, "golang", reddit.SetLimit(100), reddit.FromAllTime, reddit.SetAfter(result.After))
+	if err != nil {
+		return
+	}
+
+	for _, post := range result.Posts {
+		fmt.Println(post.Title)
+	}
+
+	return
+}

examples/submit-post/main.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/vartanbeno/go-reddit"
+)
+
+var ctx = context.Background()
+
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() (err error) {
+	withCredentials := reddit.WithCredentials("id", "secret", "username", "password")
+
+	client, err := reddit.NewClient(nil, withCredentials)
+	if err != nil {
+		return
+	}
+
+	post, _, err := client.Post.SubmitText(ctx, reddit.SubmitTextOptions{
+		Subreddit: "test",
+		Title:     "This is a title",
+		Text:      "This is some text",
+	})
+	if err != nil {
+		return
+	}
+
+	fmt.Printf("The text post is available at: %s\n", post.URL)
+
+	post, _, err = client.Post.SubmitLink(ctx, reddit.SubmitLinkOptions{
+		Subreddit: "test",
+		Title:     "This is a title",
+		URL:       "http://example.com",
+		Resubmit:  true,
+	})
+	if err != nil {
+		return
+	}
+
+	fmt.Printf("The link post is available at: %s\n", post.URL)
+
+	return
+}