vendor/github.com/fsouza/go-dockerclient/external/github.com/gorilla/context/doc.go

   1 // Copyright 2012 The Gorilla Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6 Package context stores values shared during a request lifetime.
   7
   8 For example, a router can set variables extracted from the URL and later
   9 application handlers can access those values, or it can be used to store
  10 sessions values to be saved at the end of a request. There are several
  11 others common uses.
  12
  13 The idea was posted by Brad Fitzpatrick to the go-nuts mailing list:
  14
  15         http://groups.google.com/group/golang-nuts/msg/e2d679d303aa5d53
  16
  17 Here's the basic usage: first define the keys that you will need. The key
  18 type is interface{} so a key can be of any type that supports equality.
  19 Here we define a key using a custom int type to avoid name collisions:
  20
  21         package foo
  22
  23         import (
  24                 "github.com/gorilla/context"
  25         )
  26
  27         type key int
  28
  29         const MyKey key = 0
  30
  31 Then set a variable. Variables are bound to an http.Request object, so you
  32 need a request instance to set a value:
  33
  34         context.Set(r, MyKey, "bar")
  35
  36 The application can later access the variable using the same key you provided:
  37
  38         func MyHandler(w http.ResponseWriter, r *http.Request) {
  39                 // val is "bar".
  40                 val := context.Get(r, foo.MyKey)
  41
  42                 // returns ("bar", true)
  43                 val, ok := context.GetOk(r, foo.MyKey)
  44                 // ...
  45         }
  46
  47 And that's all about the basic usage. We discuss some other ideas below.
  48
  49 Any type can be stored in the context. To enforce a given type, make the key
  50 private and wrap Get() and Set() to accept and return values of a specific
  51 type:
  52
  53         type key int
  54
  55         const mykey key = 0
  56
  57         // GetMyKey returns a value for this package from the request values.
  58         func GetMyKey(r *http.Request) SomeType {
  59                 if rv := context.Get(r, mykey); rv != nil {
  60                         return rv.(SomeType)
  61                 }
  62                 return nil
  63         }
  64
  65         // SetMyKey sets a value for this package in the request values.
  66         func SetMyKey(r *http.Request, val SomeType) {
  67                 context.Set(r, mykey, val)
  68         }
  69
  70 Variables must be cleared at the end of a request, to remove all values
  71 that were stored. This can be done in an http.Handler, after a request was
  72 served. Just call Clear() passing the request:
  73
  74         context.Clear(r)
  75
  76 ...or use ClearHandler(), which conveniently wraps an http.Handler to clear
  77 variables at the end of a request lifetime.
  78
  79 The Routers from the packages gorilla/mux and gorilla/pat call Clear()
  80 so if you are using either of them you don't need to clear the context manually.
  81 */
  82 package context