1 files changed, 361 insertions, 0 deletions

diff --git a/vendor/google.golang.org/appengine/datastore/doc.go b/vendor/google.golang.org/appengine/datastore/doc.go
new file mode 100644
index 0000000..85616cf
--- /dev/null
+++ b/vendor/google.golang.org/appengine/datastore/doc.go
@@ -0,0 +1,361 @@
+// Copyright 2011 Google Inc. All rights reserved.
+// Use of this source code is governed by the Apache 2.0
+// license that can be found in the LICENSE file.
+
+/*
+Package datastore provides a client for App Engine's datastore service.
+
+
+Basic Operations
+
+Entities are the unit of storage and are associated with a key. A key
+consists of an optional parent key, a string application ID, a string kind
+(also known as an entity type), and either a StringID or an IntID. A
+StringID is also known as an entity name or key name.
+
+It is valid to create a key with a zero StringID and a zero IntID; this is
+called an incomplete key, and does not refer to any saved entity. Putting an
+entity into the datastore under an incomplete key will cause a unique key
+to be generated for that entity, with a non-zero IntID.
+
+An entity's contents are a mapping from case-sensitive field names to values.
+Valid value types are:
+  - signed integers (int, int8, int16, int32 and int64),
+  - bool,
+  - string,
+  - float32 and float64,
+  - []byte (up to 1 megabyte in length),
+  - any type whose underlying type is one of the above predeclared types,
+  - ByteString,
+  - *Key,
+  - time.Time (stored with microsecond precision),
+  - appengine.BlobKey,
+  - appengine.GeoPoint,
+  - structs whose fields are all valid value types,
+  - slices of any of the above.
+
+Slices of structs are valid, as are structs that contain slices. However, if
+one struct contains another, then at most one of those can be repeated. This
+disqualifies recursively defined struct types: any struct T that (directly or
+indirectly) contains a []T.
+
+The Get and Put functions load and save an entity's contents. An entity's
+contents are typically represented by a struct pointer.
+
+Example code:
+
+        type Entity struct {
+                Value string
+        }
+
+        func handle(w http.ResponseWriter, r *http.Request) {
+                ctx := appengine.NewContext(r)
+
+                k := datastore.NewKey(ctx, "Entity", "stringID", 0, nil)
+                e := new(Entity)
+                if err := datastore.Get(ctx, k, e); err != nil {
+                        http.Error(w, err.Error(), 500)
+                        return
+                }
+
+                old := e.Value
+                e.Value = r.URL.Path
+
+                if _, err := datastore.Put(ctx, k, e); err != nil {
+                        http.Error(w, err.Error(), 500)
+                        return
+                }
+
+                w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+                fmt.Fprintf(w, "old=%q\nnew=%q\n", old, e.Value)
+        }
+
+GetMulti, PutMulti and DeleteMulti are batch versions of the Get, Put and
+Delete functions. They take a []*Key instead of a *Key, and may return an
+appengine.MultiError when encountering partial failure.
+
+
+Properties
+
+An entity's contents can be represented by a variety of types. These are
+typically struct pointers, but can also be any type that implements the
+PropertyLoadSaver interface. If using a struct pointer, you do not have to
+explicitly implement the PropertyLoadSaver interface; the datastore will
+automatically convert via reflection. If a struct pointer does implement that
+interface then those methods will be used in preference to the default
+behavior for struct pointers. Struct pointers are more strongly typed and are
+easier to use; PropertyLoadSavers are more flexible.
+
+The actual types passed do not have to match between Get and Put calls or even
+across different calls to datastore. It is valid to put a *PropertyList and
+get that same entity as a *myStruct, or put a *myStruct0 and get a *myStruct1.
+Conceptually, any entity is saved as a sequence of properties, and is loaded
+into the destination value on a property-by-property basis. When loading into
+a struct pointer, an entity that cannot be completely represented (such as a
+missing field) will result in an ErrFieldMismatch error but it is up to the
+caller whether this error is fatal, recoverable or ignorable.
+
+By default, for struct pointers, all properties are potentially indexed, and
+the property name is the same as the field name (and hence must start with an
+upper case letter).
+
+Fields may have a `datastore:"name,options"` tag. The tag name is the
+property name, which must be one or more valid Go identifiers joined by ".",
+but may start with a lower case letter. An empty tag name means to just use the
+field name. A "-" tag name means that the datastore will ignore that field.
+
+The only valid options are "omitempty" and "noindex".
+
+If the options include "omitempty" and the value of the field is empty, then the field will be omitted on Save.
+The empty values are false, 0, any nil interface value, and any array, slice, map, or string of length zero.
+Struct field values will never be empty.
+
+If options include "noindex" then the field will not be indexed. All fields are indexed
+by default. Strings or byte slices longer than 1500 bytes cannot be indexed;
+fields used to store long strings and byte slices must be tagged with "noindex"
+or they will cause Put operations to fail.
+
+To use multiple options together, separate them by a comma.
+The order does not matter.
+
+If the options is "" then the comma may be omitted.
+
+Example code:
+
+        // A and B are renamed to a and b.
+        // A, C and J are not indexed.
+        // D's tag is equivalent to having no tag at all (E).
+        // I is ignored entirely by the datastore.
+        // J has tag information for both the datastore and json packages.
+        type TaggedStruct struct {
+                A int `datastore:"a,noindex"`
+                B int `datastore:"b"`
+                C int `datastore:",noindex"`
+                D int `datastore:""`
+                E int
+                I int `datastore:"-"`
+                J int `datastore:",noindex" json:"j"`
+        }
+
+
+Structured Properties
+
+If the struct pointed to contains other structs, then the nested or embedded
+structs are flattened. For example, given these definitions:
+
+        type Inner1 struct {
+                W int32
+                X string
+        }
+
+        type Inner2 struct {
+                Y float64
+        }
+
+        type Inner3 struct {
+                Z bool
+        }
+
+        type Outer struct {
+                A int16
+                I []Inner1
+                J Inner2
+                Inner3
+        }
+
+then an Outer's properties would be equivalent to those of:
+
+        type OuterEquivalent struct {
+                A     int16
+                IDotW []int32  `datastore:"I.W"`
+                IDotX []string `datastore:"I.X"`
+                JDotY float64  `datastore:"J.Y"`
+                Z     bool
+        }
+
+If Outer's embedded Inner3 field was tagged as `datastore:"Foo"` then the
+equivalent field would instead be: FooDotZ bool `datastore:"Foo.Z"`.
+
+If an outer struct is tagged "noindex" then all of its implicit flattened
+fields are effectively "noindex".
+
+
+The PropertyLoadSaver Interface
+
+An entity's contents can also be represented by any type that implements the
+PropertyLoadSaver interface. This type may be a struct pointer, but it does
+not have to be. The datastore package will call Load when getting the entity's
+contents, and Save when putting the entity's contents.
+Possible uses include deriving non-stored fields, verifying fields, or indexing
+a field only if its value is positive.
+
+Example code:
+
+        type CustomPropsExample struct {
+                I, J int
+                // Sum is not stored, but should always be equal to I + J.
+                Sum int `datastore:"-"`
+        }
+
+        func (x *CustomPropsExample) Load(ps []datastore.Property) error {
+                // Load I and J as usual.
+                if err := datastore.LoadStruct(x, ps); err != nil {
+                        return err
+                }
+                // Derive the Sum field.
+                x.Sum = x.I + x.J
+                return nil
+        }
+
+        func (x *CustomPropsExample) Save() ([]datastore.Property, error) {
+                // Validate the Sum field.
+                if x.Sum != x.I + x.J {
+                        return nil, errors.New("CustomPropsExample has inconsistent sum")
+                }
+                // Save I and J as usual. The code below is equivalent to calling
+                // "return datastore.SaveStruct(x)", but is done manually for
+                // demonstration purposes.
+                return []datastore.Property{
+                        {
+                                Name:  "I",
+                                Value: int64(x.I),
+                        },
+                        {
+                                Name:  "J",
+                                Value: int64(x.J),
+                        },
+                }, nil
+        }
+
+The *PropertyList type implements PropertyLoadSaver, and can therefore hold an
+arbitrary entity's contents.
+
+
+Queries
+
+Queries retrieve entities based on their properties or key's ancestry. Running
+a query yields an iterator of results: either keys or (key, entity) pairs.
+Queries are re-usable and it is safe to call Query.Run from concurrent
+goroutines. Iterators are not safe for concurrent use.
+
+Queries are immutable, and are either created by calling NewQuery, or derived
+from an existing query by calling a method like Filter or Order that returns a
+new query value. A query is typically constructed by calling NewQuery followed
+by a chain of zero or more such methods. These methods are:
+  - Ancestor and Filter constrain the entities returned by running a query.
+  - Order affects the order in which they are returned.
+  - Project constrains the fields returned.
+  - Distinct de-duplicates projected entities.
+  - KeysOnly makes the iterator return only keys, not (key, entity) pairs.
+  - Start, End, Offset and Limit define which sub-sequence of matching entities
+    to return. Start and End take cursors, Offset and Limit take integers. Start
+    and Offset affect the first result, End and Limit affect the last result.
+    If both Start and Offset are set, then the offset is relative to Start.
+    If both End and Limit are set, then the earliest constraint wins. Limit is
+    relative to Start+Offset, not relative to End. As a special case, a
+    negative limit means unlimited.
+
+Example code:
+
+        type Widget struct {
+                Description string
+                Price       int
+        }
+
+        func handle(w http.ResponseWriter, r *http.Request) {
+                ctx := appengine.NewContext(r)
+                q := datastore.NewQuery("Widget").
+                        Filter("Price <", 1000).
+                        Order("-Price")
+                b := new(bytes.Buffer)
+                for t := q.Run(ctx); ; {
+                        var x Widget
+                        key, err := t.Next(&x)
+                        if err == datastore.Done {
+                                break
+                        }
+                        if err != nil {
+                                serveError(ctx, w, err)
+                                return
+                        }
+                        fmt.Fprintf(b, "Key=%v\nWidget=%#v\n\n", key, x)
+                }
+                w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+                io.Copy(w, b)
+        }
+
+
+Transactions
+
+RunInTransaction runs a function in a transaction.
+
+Example code:
+
+        type Counter struct {
+                Count int
+        }
+
+        func inc(ctx context.Context, key *datastore.Key) (int, error) {
+                var x Counter
+                if err := datastore.Get(ctx, key, &x); err != nil && err != datastore.ErrNoSuchEntity {
+                        return 0, err
+                }
+                x.Count++
+                if _, err := datastore.Put(ctx, key, &x); err != nil {
+                        return 0, err
+                }
+                return x.Count, nil
+        }
+
+        func handle(w http.ResponseWriter, r *http.Request) {
+                ctx := appengine.NewContext(r)
+                var count int
+                err := datastore.RunInTransaction(ctx, func(ctx context.Context) error {
+                        var err1 error
+                        count, err1 = inc(ctx, datastore.NewKey(ctx, "Counter", "singleton", 0, nil))
+                        return err1
+                }, nil)
+                if err != nil {
+                        serveError(ctx, w, err)
+                        return
+                }
+                w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+                fmt.Fprintf(w, "Count=%d", count)
+        }
+
+
+Metadata
+
+The datastore package provides access to some of App Engine's datastore
+metadata. This metadata includes information about the entity groups,
+namespaces, entity kinds, and properties in the datastore, as well as the
+property representations for each property.
+
+Example code:
+
+        func handle(w http.ResponseWriter, r *http.Request) {
+                // Print all the kinds in the datastore, with all the indexed
+                // properties (and their representations) for each.
+                ctx := appengine.NewContext(r)
+
+                kinds, err := datastore.Kinds(ctx)
+                if err != nil {
+                        serveError(ctx, w, err)
+                        return
+                }
+
+                w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+                for _, kind := range kinds {
+                        fmt.Fprintf(w, "%s:\n", kind)
+                        props, err := datastore.KindProperties(ctx, kind)
+                        if err != nil {
+                                fmt.Fprintln(w, "\t(unable to retrieve properties)")
+                                continue
+                        }
+                        for p, rep := range props {
+                                fmt.Fprintf(w, "\t-%s (%s)\n", p, strings.Join(rep, ", "))
+                        }
+                }
+        }
+*/
+package datastore // import "google.golang.org/appengine/datastore"