initial commit

Signed-off-by: Derek McQuay <derekmcquay@gmail.com>
2018-04-10 19:17:26 -07:00
commit 59af8fc84f
2025 changed files with 456739 additions and 0 deletions
@@ -0,0 +1,16 @@
+# Build doc.go from template and snippets.
+
+SHELL=/bin/bash
+
+../doc.go: build doc-snippets.go doc.template snipdoc.awk
+	@tmp=$$(mktemp) && \
+	awk -f snipdoc.awk doc-snippets.go doc.template > $$tmp && \
+	chmod +w $@ && \
+	mv $$tmp $@ && \
+	chmod -w $@
+	@echo "wrote $@"
+
+.PHONY: build
+
+build:
+	go build doc-snippets.go
@@ -0,0 +1,161 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package internal
+
+import (
+	"fmt"
+
+	firestore "cloud.google.com/go/firestore"
+
+	"golang.org/x/net/context"
+	"google.golang.org/api/iterator"
+)
+
+const ELLIPSIS = 0
+
+//[ structDef
+type State struct {
+	Capital    string  `firestore:"capital"`
+	Population float64 `firestore:"pop"` // in millions
+}
+
+//]
+
+func f1() {
+	//[ NewClient
+	ctx := context.Background()
+	client, err := firestore.NewClient(ctx, "projectID")
+	if err != nil {
+		// TODO: Handle error.
+	}
+	//]
+	//[ refs
+	states := client.Collection("States")
+	ny := states.Doc("NewYork")
+	// Or, in a single call:
+	ny = client.Doc("States/NewYork")
+	//]
+	//[ docref.Get
+	docsnap, err := ny.Get(ctx)
+	if err != nil {
+		// TODO: Handle error.
+	}
+	dataMap := docsnap.Data()
+	fmt.Println(dataMap)
+	//]
+	//[ DataTo
+	var nyData State
+	if err := docsnap.DataTo(&nyData); err != nil {
+		// TODO: Handle error.
+	}
+	//]
+	//[ GetAll
+	docsnaps, err := client.GetAll(ctx, []*firestore.DocumentRef{
+		states.Doc("Wisconsin"), states.Doc("Ohio"),
+	})
+	if err != nil {
+		// TODO: Handle error.
+	}
+	for _, ds := range docsnaps {
+		_ = ds // TODO: Use ds.
+	}
+	//[ docref.Create
+	wr, err := ny.Create(ctx, State{
+		Capital:    "Albany",
+		Population: 19.8,
+	})
+	if err != nil {
+		// TODO: Handle error.
+	}
+	fmt.Println(wr)
+	//]
+	//[ docref.Set
+	ca := states.Doc("California")
+	_, err = ca.Set(ctx, State{
+		Capital:    "Sacramento",
+		Population: 39.14,
+	})
+	//]
+
+	//[ docref.Update
+	_, err = ca.Update(ctx, []firestore.Update{{Path: "capital", Value: "Sacramento"}})
+	//]
+
+	//[ docref.Delete
+	_, err = ny.Delete(ctx)
+	//]
+
+	//[ LUT-precond
+	docsnap, err = ca.Get(ctx)
+	if err != nil {
+		// TODO: Handle error.
+	}
+	_, err = ca.Update(ctx,
+		[]firestore.Update{{Path: "capital", Value: "Sacramento"}},
+		firestore.LastUpdateTime(docsnap.UpdateTime))
+	//]
+
+	//[ WriteBatch
+	writeResults, err := client.Batch().
+		Create(ny, State{Capital: "Albany"}).
+		Update(ca, []firestore.Update{{Path: "capital", Value: "Sacramento"}}).
+		Delete(client.Doc("States/WestDakota")).
+		Commit(ctx)
+	//]
+	_ = writeResults
+
+	//[ Query
+	q := states.Where("pop", ">", 10).OrderBy("pop", firestore.Desc)
+	//]
+	//[ Documents
+	iter := q.Documents(ctx)
+	for {
+		doc, err := iter.Next()
+		if err == iterator.Done {
+			break
+		}
+		if err != nil {
+			// TODO: Handle error.
+		}
+		fmt.Println(doc.Data())
+	}
+	//]
+
+	//[ CollQuery
+	iter = client.Collection("States").Documents(ctx)
+	//]
+}
+
+func txn() {
+	var ctx context.Context
+	var client *firestore.Client
+	//[ Transaction
+	ny := client.Doc("States/NewYork")
+	err := client.RunTransaction(ctx, func(ctx context.Context, tx *firestore.Transaction) error {
+		doc, err := tx.Get(ny) // tx.Get, NOT ny.Get!
+		if err != nil {
+			return err
+		}
+		pop, err := doc.DataAt("pop")
+		if err != nil {
+			return err
+		}
+		return tx.Update(ny, []firestore.Update{{Path: "pop", Value: pop.(float64) + 0.2}})
+	})
+	if err != nil {
+		// TODO: Handle error.
+	}
+	//]
+}
@@ -0,0 +1,145 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// DO NOT EDIT doc.go. Modify internal/doc.template, then run make -C internal.
+
+/*
+Package firestore provides a client for reading and writing to a Cloud Firestore
+database.
+
+See https://cloud.google.com/firestore/docs for an introduction
+to Cloud Firestore and additional help on using the Firestore API.
+
+Note: you can't use both Cloud Firestore and Cloud Datastore in the same
+project.
+
+Creating a Client
+
+To start working with this package, create a client with a project ID:
+
+[NewClient]
+
+CollectionRefs and DocumentRefs
+
+In Firestore, documents are sets of key-value pairs, and collections are groups of
+documents. A Firestore database consists of a hierarchy of alternating collections
+and documents, referred to by slash-separated paths like
+"States/California/Cities/SanFrancisco".
+
+This client is built around references to collections and documents. CollectionRefs
+and DocumentRefs are lightweight values that refer to the corresponding database
+entities. Creating a ref does not involve any network traffic.
+
+[refs]
+
+Reading
+
+Use DocumentRef.Get to read a document. The result is a DocumentSnapshot.
+Call its Data method to obtain the entire document contents as a map.
+
+[docref.Get]
+
+You can also obtain a single field with DataAt, or extract the data into a struct
+with DataTo. With the type definition
+
+[structDef]
+
+we can extract the document's data into a value of type State:
+
+[DataTo]
+
+Note that this client supports struct tags beginning with "firestore:" that work like
+the tags of the encoding/json package, letting you rename fields, ignore them, or
+omit their values when empty.
+
+To retrieve multiple documents from their references in a single call, use
+Client.GetAll.
+
+[GetAll]
+
+Writing
+
+For writing individual documents, use the methods on DocumentReference.
+Create creates a new document.
+
+[docref.Create]
+
+The first return value is a WriteResult, which contains the time
+at which the document was updated.
+
+Create fails if the document exists. Another method, Set, either replaces an existing
+document or creates a new one.
+
+[docref.Set]
+
+To update some fields of an existing document, use Update. It takes a list of
+paths to update and their corresponding values.
+
+[docref.Update]
+
+Use DocumentRef.Delete to delete a document.
+
+[docref.Delete]
+
+Preconditions
+
+You can condition Deletes or Updates on when a document was last changed. Specify
+these preconditions as an option to a Delete or Update method. The check and the
+write happen atomically with a single RPC.
+
+[LUT-precond]
+
+Here we update a doc only if it hasn't changed since we read it.
+You could also do this with a transaction.
+
+To perform multiple writes at once, use a WriteBatch. Its methods chain
+for convenience.
+
+WriteBatch.Commit sends the collected writes to the server, where they happen
+atomically.
+
+[WriteBatch]
+
+Queries
+
+You can use SQL to select documents from a collection. Begin with the collection, and
+build up a query using Select, Where and other methods of Query.
+
+[Query]
+
+Call the Query's Documents method to get an iterator, and use it like
+the other Google Cloud Client iterators.
+
+[Documents]
+
+To get all the documents in a collection, you can use the collection itself
+as a query.
+
+[CollQuery]
+
+Transactions
+
+Use a transaction to execute reads and writes atomically. All reads must happen
+before any writes. Transaction creation, commit, rollback and retry are handled for
+you by the Client.RunTransaction method; just provide a function and use the
+read and write methods of the Transaction passed to it.
+
+[Transaction]
+
+Authentication
+
+See examples of authorization and authentication at
+https://godoc.org/cloud.google.com/go#pkg-examples.
+*/
+package firestore
@@ -0,0 +1,116 @@
+# Copyright 2017 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# snipdoc merges code snippets from Go source files into a template to
+# produce another go file (typically doc.go).
+#
+# Call with one or more .go files and a template file.
+#
+#    awk -f snipmd.awk foo.go bar.go doc.template
+#
+# In the Go files, start a snippet with
+#    //[ NAME
+# and end it with
+#    //]
+#
+# In the template, write
+#    [NAME]
+# on a line by itself to insert the snippet NAME on that line.
+#
+# The following transformations are made to the Go code:
+# - Trailing blank lines are removed.
+# - `ELLIPSIS` and `_ = ELLIPSIS` are replaced by `...`
+
+
+/^[ \t]*\/\/\[/ { # start snippet in Go file
+  if (inGo()) {
+    if ($2 == "") {
+      die("missing snippet name")
+    }
+    curSnip = $2
+    next
+  }
+}
+
+/^[ \t]*\/\/]/ {  # end snippet in Go file
+  if (inGo()) {
+    if (curSnip != "") {
+      # Remove all trailing newlines.
+      gsub(/[\t\n]+$/, "", snips[curSnip])
+      curSnip = ""
+      next
+    } else {
+      die("//] without corresponding //[")
+    }
+  }
+}
+
+ENDFILE {
+  if (curSnip != "") {
+    die("unclosed snippet: " curSnip)
+  }
+}
+
+/^\[.*\]$/ { # Snippet marker in template file.
+  if (inTemplate()) {
+    name = substr($1, 2, length($1)-2)
+    if (snips[name] == "") {
+      die("no snippet named " name)
+    }
+    printf("%s\n", snips[name])
+    afterSnip = 1
+    next
+  }
+}
+
+# Matches every line.
+{
+  if (curSnip != "") {
+    # If the first line in the snip has no indent, add the indent.
+    if (snips[curSnip] == "") {
+      if (index($0, "\t") == 1) {
+        extraIndent = ""
+      } else {
+        extraIndent = "\t"
+      }
+    }
+
+    line = $0
+    # Replace ELLIPSIS.
+    gsub(/_ = ELLIPSIS/, "...", line)
+    gsub(/ELLIPSIS/, "...", line)
+
+    snips[curSnip] = snips[curSnip] extraIndent line "\n"
+  } else if (inTemplate()) {
+    afterSnip = 0
+    # Copy to output.
+    print
+  }
+}
+
+
+
+function inTemplate() {
+  return match(FILENAME, /\.template$/)
+}
+
+function inGo() {
+  return match(FILENAME, /\.go$/)
+}
+
+
+function die(msg) {
+  printf("%s:%d: %s\n", FILENAME, FNR, msg) > "/dev/stderr"
+  exit 1
+}