From be8bed0dab8b3079d2e0ced767dd45467602ab58 Mon Sep 17 00:00:00 2001 From: Anton Lindstrom Date: Thu, 21 Jul 2016 20:34:24 +0000 Subject: [PATCH] Add testable example in README This adds a testable example for the README to be able to make the user experience for new users better. --- .travis.yml | 6 ++++- Makefile | 16 ++++++++++-- README.md | 61 +++++++++++++++++++++++++++----------------- examples/sessions.go | 42 ++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 26 deletions(-) create mode 100644 examples/sessions.go diff --git a/.travis.yml b/.travis.yml index 32e28a8..fbe673b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,9 +5,13 @@ go: - 1.6 - tip -script: +install: - make get-deps + - go get github.com/campoy/embedmd + +script: - make metalint + - make docs-check - make check env: diff --git a/Makefile b/Makefile index 25325b0..ff2494d 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ get-deps: go get -v ./... .PHONY: test -test: get-deps metalint check +test: get-deps metalint docs-check check .PHONY: check check: @@ -29,7 +29,7 @@ docker-test: docker run -d -p 5432:5432 --name=pgstore_test_1 postgres:9.4 sleep 5 docker run --rm --link pgstore_test_1:postgres postgres:9.4 psql -c 'create database test;' -U postgres -h postgres - PGSTORE_TEST_CONN="postgres://postgres@127.0.0.1:5432/test?sslmode=disable" make check + PGSTORE_TEST_CONN="postgres://postgres@127.0.0.1:5432/test?sslmode=disable" make test docker kill pgstore_test_1 docker rm pgstore_test_1 @@ -37,3 +37,15 @@ docker-test: docker-clean: -docker kill pgstore_test_1 -docker rm pgstore_test_1 + +.PHONY: docs-dep + which embedmd > /dev/null || go get github.com/campoy/embedmd + +.PHONY: docs-check +docs-check: docs-dep + @echo "Checking if docs are generated, if this fails, run 'make docs'." + embedmd README.md | diff README.md - + +.PHONY: docs +docs: docs-dep + embedmd -w README.md diff --git a/README.md b/README.md index 6149668..097f983 100644 --- a/README.md +++ b/README.md @@ -14,34 +14,49 @@ See http://www.gorillatoolkit.org/pkg/sessions for full documentation on underly ### Example +[embedmd]:# (examples/sessions.go) ```go -// Fetch new store. -store, err := NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key")) -if err != nil { - log.Error(err.Error()) -} -defer store.Close() -// Run a background goroutine to clean up expired sessions from the database. -defer store.StopCleanup(store.Cleanup(time.Minute * 5)) +package examples -// Get a session. -session, err = store.Get(req, "session-key") -if err != nil { - log.Error(err.Error()) -} +import ( + "log" + "net/http" + "time" -// Add a value. -session.Values["foo"] = "bar" + "github.com/antonlindstrom/pgstore" +) -// Save. -if err = sessions.Save(req, rsp); err != nil { - t.Fatalf("Error saving session: %v", err) -} +// ExampleHandler is an example that displays the usage of PGStore. +func ExampleHandler(w http.ResponseWriter, r *http.Request) { + // Fetch new store. + store, err := pgstore.NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key")) + if err != nil { + log.Fatalf(err.Error()) + } + defer store.Close() -// Delete session. -session.Options.MaxAge = -1 -if err = sessions.Save(req, rsp); err != nil { - t.Fatalf("Error saving session: %v", err) + // Run a background goroutine to clean up expired sessions from the database. + defer store.StopCleanup(store.Cleanup(time.Minute * 5)) + + // Get a session. + session, err := store.Get(r, "session-key") + if err != nil { + log.Fatalf(err.Error()) + } + + // Add a value. + session.Values["foo"] = "bar" + + // Save. + if err = session.Save(r, w); err != nil { + log.Fatalf("Error saving session: %v", err) + } + + // Delete session. + session.Options.MaxAge = -1 + if err = session.Save(r, w); err != nil { + log.Fatalf("Error saving session: %v", err) + } } ``` diff --git a/examples/sessions.go b/examples/sessions.go new file mode 100644 index 0000000..66a330c --- /dev/null +++ b/examples/sessions.go @@ -0,0 +1,42 @@ +package examples + +import ( + "log" + "net/http" + "time" + + "github.com/antonlindstrom/pgstore" +) + +// ExampleHandler is an example that displays the usage of PGStore. +func ExampleHandler(w http.ResponseWriter, r *http.Request) { + // Fetch new store. + store, err := pgstore.NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key")) + if err != nil { + log.Fatalf(err.Error()) + } + defer store.Close() + + // Run a background goroutine to clean up expired sessions from the database. + defer store.StopCleanup(store.Cleanup(time.Minute * 5)) + + // Get a session. + session, err := store.Get(r, "session-key") + if err != nil { + log.Fatalf(err.Error()) + } + + // Add a value. + session.Values["foo"] = "bar" + + // Save. + if err = session.Save(r, w); err != nil { + log.Fatalf("Error saving session: %v", err) + } + + // Delete session. + session.Options.MaxAge = -1 + if err = session.Save(r, w); err != nil { + log.Fatalf("Error saving session: %v", err) + } +}