1 files changed, 209 insertions, 0 deletions
diff --git a/vendor/google.golang.org/appengine/search/doc.go b/vendor/google.golang.org/appengine/search/doc.go
new file mode 100644
index 0000000..da331ce
--- /dev/null
+++ b/vendor/google.golang.org/appengine/search/doc.go
@@ -0,0 +1,209 @@
+// Copyright 2015 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 search provides a client for App Engine's search service.
+
+
+Basic Operations
+
+Indexes contain documents. Each index is identified by its name: a
+human-readable ASCII string.
+
+Within an index, documents are associated with an ID, which is also
+a human-readable ASCII string. A document's contents are a mapping from
+case-sensitive field names to values. Valid types for field values are:
+  - string,
+  - search.Atom,
+  - search.HTML,
+  - time.Time (stored with millisecond precision),
+  - float64 (value between -2,147,483,647 and 2,147,483,647 inclusive),
+  - appengine.GeoPoint.
+
+The Get and Put methods on an Index load and save a document.
+A document's contents are typically represented by a struct pointer.
+
+Example code:
+
+	type Doc struct {
+		Author   string
+		Comment  string
+		Creation time.Time
+	}
+
+	index, err := search.Open("comments")
+	if err != nil {
+		return err
+	}
+	newID, err := index.Put(ctx, "", &Doc{
+		Author:   "gopher",
+		Comment:  "the truth of the matter",
+		Creation: time.Now(),
+	})
+	if err != nil {
+		return err
+	}
+
+A single document can be retrieved by its ID. Pass a destination struct
+to Get to hold the resulting document.
+
+	var doc Doc
+	err := index.Get(ctx, id, &doc)
+	if err != nil {
+		return err
+	}
+
+
+Search and Listing Documents
+
+Indexes have two methods for retrieving multiple documents at once: Search and
+List.
+
+Searching an index for a query will result in an iterator. As with an iterator
+from package datastore, pass a destination struct to Next to decode the next
+result. Next will return Done when the iterator is exhausted.
+
+	for t := index.Search(ctx, "Comment:truth", nil); ; {
+		var doc Doc
+		id, err := t.Next(&doc)
+		if err == search.Done {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(w, "%s -> %#v\n", id, doc)
+	}
+
+Search takes a string query to determine which documents to return. The query
+can be simple, such as a single word to match, or complex. The query
+language is described at
+https://cloud.google.com/appengine/docs/go/search/query_strings
+
+Search also takes an optional SearchOptions struct which gives much more
+control over how results are calculated and returned.
+
+Call List to iterate over all documents in an index.
+
+	for t := index.List(ctx, nil); ; {
+		var doc Doc
+		id, err := t.Next(&doc)
+		if err == search.Done {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(w, "%s -> %#v\n", id, doc)
+	}
+
+
+Fields and Facets
+
+A document's contents can be represented by a variety of types. These are
+typically struct pointers, but they can also be represented by any type
+implementing the FieldLoadSaver interface. The FieldLoadSaver allows metadata
+to be set for the document with the DocumentMetadata type. Struct pointers are
+more strongly typed and are easier to use; FieldLoadSavers are more flexible.
+
+A document's contents can be expressed in two ways: fields and facets.
+
+Fields are the most common way of providing content for documents. Fields can
+store data in multiple types and can be matched in searches using query
+strings.
+
+Facets provide a way to attach categorical information to a document. The only
+valid types for facets are search.Atom and float64. Facets allow search
+results to contain summaries of the categories matched in a search, and to
+restrict searches to only match against specific categories.
+
+By default, for struct pointers, all of the struct fields are used as document
+fields, and the field name used is the same as on the struct (and hence must
+start with an upper case letter). Struct fields may have a
+`search:"name,options"` tag. The name must start with a letter and be
+composed only of word characters. A "-" tag name means that the field will be
+ignored.  If options is "facet" then the struct field will be used as a
+document facet. If options is "" then the comma may be omitted. There are no
+other recognized options.
+
+Example code:
+
+	// A and B are renamed to a and b.
+	// A, C and I are facets.
+	// D's tag is equivalent to having no tag at all (E).
+	// F and G are ignored entirely by the search package.
+	// I has tag information for both the search and json packages.
+	type TaggedStruct struct {
+		A float64 `search:"a,facet"`
+		B float64 `search:"b"`
+		C float64 `search:",facet"`
+		D float64 `search:""`
+		E float64
+		F float64 `search:"-"`
+		G float64 `search:"-,facet"`
+		I float64 `search:",facet" json:"i"`
+	}
+
+
+The FieldLoadSaver Interface
+
+A document's contents can also be represented by any type that implements the
+FieldLoadSaver interface. This type may be a struct pointer, but it
+does not have to be. The search package will call Load when loading the
+document's contents, and Save when saving them. In addition to a slice of
+Fields, the Load and Save methods also use the DocumentMetadata type to
+provide additional information about a document (such as its Rank, or set of
+Facets). Possible uses for this interface include deriving non-stored fields,
+verifying fields or setting specific languages for string and HTML fields.
+
+Example code:
+
+	type CustomFieldsExample struct {
+		// Item's title and which language it is in.
+		Title string
+		Lang  string
+		// Mass, in grams.
+		Mass int
+	}
+
+	func (x *CustomFieldsExample) Load(fields []search.Field, meta *search.DocumentMetadata) error {
+		// Load the title field, failing if any other field is found.
+		for _, f := range fields {
+			if f.Name != "title" {
+				return fmt.Errorf("unknown field %q", f.Name)
+			}
+			s, ok := f.Value.(string)
+			if !ok {
+				return fmt.Errorf("unsupported type %T for field %q", f.Value, f.Name)
+			}
+			x.Title = s
+			x.Lang = f.Language
+		}
+		// Load the mass facet, failing if any other facet is found.
+		for _, f := range meta.Facets {
+			if f.Name != "mass" {
+				return fmt.Errorf("unknown facet %q", f.Name)
+			}
+			m, ok := f.Value.(float64)
+			if !ok {
+				return fmt.Errorf("unsupported type %T for facet %q", f.Value, f.Name)
+			}
+			x.Mass = int(m)
+		}
+		return nil
+	}
+
+	func (x *CustomFieldsExample) Save() ([]search.Field, *search.DocumentMetadata, error) {
+		fields := []search.Field{
+			{Name: "title", Value: x.Title, Language: x.Lang},
+		}
+		meta := &search.DocumentMetadata{
+			Facets: {
+				{Name: "mass", Value: float64(x.Mass)},
+			},
+		}
+		return fields, meta, nil
+	}
+*/
+package search