From dce251dbc0fd2dc72b3111d2e9d356a21196e1b1 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Tue, 26 Aug 2014 22:47:10 -0400 Subject: [PATCH] docs: jsdoc + travis auto build to gh-pages. --- .jsdoc.json | 18 + .travis.yml | 29 +- README.md | 454 +--- docs/dataset.html | 1696 ++++++++++++++ docs/dataset.js.html | 398 ++++ docs/index.html | 391 ++++ docs/index.js.html | 120 + docs/index.js_.html | 155 ++ docs/index.js__.html | 471 ++++ docs/module-datastore.html | 356 +++ docs/module-gcloud.html | 391 ++++ docs/module-storage.html | 2070 ++++++++++++++++++ docs/query.html | 1640 ++++++++++++++ docs/query.js.html | 313 +++ docs/scripts/linenumber.js | 25 + docs/scripts/prettify/Apache-License-2.0.txt | 202 ++ docs/scripts/prettify/lang-css.js | 2 + docs/scripts/prettify/prettify.js | 28 + docs/styles/jsdoc-default.css | 333 +++ docs/styles/prettify-jsdoc.css | 111 + docs/styles/prettify-tomorrow.css | 132 ++ lib/common/connection.js | 21 +- lib/common/util.js | 15 +- lib/datastore/dataset.js | 106 +- lib/datastore/entity.js | 86 +- lib/datastore/index.js | 31 +- lib/datastore/pb.js | 1 + lib/datastore/query.js | 46 +- lib/datastore/transaction.js | 24 +- lib/index.js | 92 +- lib/pubsub/index.js | 17 +- lib/storage/index.js | 40 +- package.json | 6 +- 33 files changed, 9181 insertions(+), 639 deletions(-) create mode 100644 .jsdoc.json create mode 100644 docs/dataset.html create mode 100644 docs/dataset.js.html create mode 100644 docs/index.html create mode 100644 docs/index.js.html create mode 100644 docs/index.js_.html create mode 100644 docs/index.js__.html create mode 100644 docs/module-datastore.html create mode 100644 docs/module-gcloud.html create mode 100644 docs/module-storage.html create mode 100644 docs/query.html create mode 100644 docs/query.js.html create mode 100644 docs/scripts/linenumber.js create mode 100644 docs/scripts/prettify/Apache-License-2.0.txt create mode 100644 docs/scripts/prettify/lang-css.js create mode 100644 docs/scripts/prettify/prettify.js create mode 100644 docs/styles/jsdoc-default.css create mode 100644 docs/styles/prettify-jsdoc.css create mode 100644 docs/styles/prettify-tomorrow.css diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 00000000000..80a80573e2a --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,18 @@ +{ + "opts": { + "destination": "docs", + "encoding": "utf-8" + }, + "plugins": [ + "plugins/markdown" + ], + "source": { + "include": [ + "lib/datastore/index.js", + "lib/datastore/dataset.js", + "lib/datastore/query.js", + "lib/storage/index.js", + "lib/index.js" + ] + } +} diff --git a/.travis.yml b/.travis.yml index 76c7a309932..999472a095e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,27 @@ -language: node_js -script: "npm run-script lint && npm run-script test" +language: + node_js node_js: - - "0.10" + - 0.10 +branches: + only: + - master +env: + global: + - secure: "B1vanjI2TMf+YnmbcF5HWAMNnmT+CFr2EB1CCIcyoWqs2RIBvgiDH0gDR46iUDdfPRSt3Eokaru1fY8ptZDRnrt3oKokWp4ZrRO0x7uUGbkGfdmHHxnOlUA1m9rVhaOBCWl5opfaA8ncWcXwdWZGg7HWpS7EfTNr2dIr7lAC2mU=" + - GH_OWNER: GoogleCloudPlatform + - GH_PROJECT_NAME: gcloud-node +script: + - npm run lint + - npm run test +after_success: + - git submodule add -b gh-pages https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME} site > /dev/null 2>&1 + - cd site + - if git checkout gh-pages; then git checkout -b gh-pages; fi + - git rm -r . + - cp -R ../docs/* . + - cp ../docs/.* . + - git add -f . + - git config user.email "sawchuk@gmail.com" + - git config user.name "stephenplusplus" + - git commit -am "building gh-pages [ci skip]" + - git push https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME} HEAD:gh-pages > /dev/null 2>&1 diff --git a/README.md b/README.md index 087a4862ab7..9eff29c0b3d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # Google Cloud Node.js Client - -Node idiomatic client for Google Cloud services. Work in progress... Watch the repo for notifications. +> Node idiomatic client for Google Cloud services. [![NPM Version](https://img.shields.io/npm/v/gcloud.svg)](https://www.npmjs.org/package/gcloud) ![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-node.svg) @@ -10,14 +9,18 @@ This client supports the following Google Cloud services: * [Google Cloud Datastore](https://developers.google.com/datastore/) * [Google Cloud Storage](https://cloud.google.com/products/cloud-storage/) -* [Google Cloud Pub/Sub](https://developers.google.com/pubsub/) -* Planned but not yet started: [Google Compute Engine](https://developers.google.com/compute), and [Google BigQuery](https://developers.google.com/bigquery/) +* [Google Cloud Pub/Sub (experimental)](https://developers.google.com/pubsub/) + +Planned, but not yet available: + +* [Google Compute Engine](https://developers.google.com/compute) +* [Google BigQuery](https://developers.google.com/bigquery/) ## Quickstart -~~~~ -npm install gcloud -~~~~ +```sh +$ npm install gcloud +``` ### On Google Compute Engine @@ -40,230 +43,15 @@ If you are not running this client on Google Compute Engine, you need a Google D your private key. The downloaded file contains credentials you'll need for authorization. -* You'll the following for auth configuration: +* You'll need the following for auth configuration: * Developers Console project's ID (e.g. bamboo-shift-455) * The path to the JSON key file. -## Developer's Guide - -* [Google Cloud Datastore](#google-cloud-datastore) - * [Configuration](#configuration) - * [Entities and Keys](#entities-and-keys) - * [Getting, Saving and Deleting Entities](#getting-saving-and-deleting-entities) - * [Querying](#querying) - * [Allocating IDs](#allocating-ids-id-generation) - * [Transactions](#transactions) -* [Google Cloud Storage](#google-cloud-storage) - * [Configuration](#configuration-1) - * [Listing Files](#listing-files) - * [Stat Files](#stat-files) - * [Read file contents](#read-file-contents) - * [Write file contents and metadata](#write-file-contents-and-metadata) - * [Copy files](#copy-files) - * [Remove files](#remove-files) -* [Google Cloud Pub/Sub](#google-cloud-pubsub-experimental) - * [Configuration](#configuration-2) - * [Topics and Subscriptions](#topics-and-subscriptions) - * [Publishing a message](#publishing-a-message) - * [Listening for messages](#listening-for-messages) - ### Google Cloud Datastore [Google Cloud Datastore](https://developers.google.com/datastore/) is a fully managed, schemaless database for storing non-relational data. Cloud Datastore automatically scales with your users and supports ACID transactions, high availability of reads and writes, strong consistency for reads and ancestor queries, and eventual consistency for all other queries. -#### Configuration - -If you're running this client on Google Compute Engine, you need to construct a dataset with your Compute Engine enabled project's ID (e.g. bamboo-shift-454). Project ID is listed on the [Google Developers Console](https://console.developers.google.com/project). - -~~~~ js -var gcloud = require('gcloud'), - datastore = gcloud.datastore, - ds = new datastore.Dataset({ projectId: YOUR_PROJECT_ID }); -~~~~ - -Elsewhere, initiate with project ID and private key downloaded from Developer's Console. - -~~~~ js -var gcloud = require('gcloud'), - ds = new gcloud.datastore.Dataset({ - projectId: YOUR_PROJECT_ID, - keyFilename: '/path/to/the/key.json' - }); -~~~~ - -#### Entities and Keys - -TODO - -#### Getting, Saving and Deleting Entities - -Get operations require a valid key to retrieve the key identified entity from Datastore. Skip to the "Querying" section if you'd like to learn more about querying against Datastore. - -~~~~ js -ds.get(ds.key('Company', 123), function(err, entity) {}); - -// alternatively, you can retrieve multiple entities at once. -ds.get([ - ds.key('Company', 123), - ds.key('Product', 'Computer') -], function(err, entities) {}); -~~~~ - -You can insert arbitrary objects by providing an incomplete key during saving. If the key is not incomplete, the existing entity is updated or inserted with the provided key. - -To learn more about keys and incomplete keys, skip to the Keys section. - -~~~~ js -ds.save({ - key: ds.key('Company', null), data: {/*...*/} -}, function(err, key) { - // First arg is an incomplete key for Company kind. - // console.log(key) will output ['Company', 599900452312]. -}); -// alternatively, you can save multiple entities at once. -ds.save([ - { key: ds.key('Company', 123), data: {/*...*/} }, - { key: ds.key('Product', 'Computer'), data: {/*...*/} } -], function(err, keys) { - // if the first key was incomplete, keys[0] will return the generated key. -}); -~~~~ - -Deletion requires the key of the entity to be deleted. - -~~~~ js -ds.delete(['Company', 599900452312], function(err) {}); - -// alternatively, you can delete multiple entities of different -// kinds at once. -ds.delete([ - ds.key('Company', 599900452312), - ds.key('Company', 599900452315), - ds.key('Office', 'mtv'), - ds.key('Company', 123, 'Employee', 'jbd') -], function(err) {}); -~~~~ - -#### Querying - -Datastore allows you to query entities by kind, filter them by property filters and sort them by a property name. Projection and pagination are -also supported. - -~~~~ js -// retrieves 5 companies -var q = ds.createQuery('Company').limit(5); -ds.runQuery(q, function(err, entities, nextQuery) { - // nextQuery is not null if there are more results. - if (nextQuery) { - ds.runQuery(nextQuery, callback); - } -}); -~~~~ - -##### Filtering - -Datastore allows querying on properties. Supported comparison operators are -`=`, `<`, `>`, `<=`, `>=`. Not equal and `IN` operators are currently not -supported. - -~~~~ js -// lists all companies named Google and -// have less than 400 employees. -var q = ds.createQuery('Company') - .filter('name =', 'Google') - .filter('size <', 400); -~~~~ - -To filter by key, use `__key__` for the property name. Filtering on keys -stored as properties is not currently supported. - -~~~~ js -var q = ds.createQuery('Company') - .filter('__key__ =', ds.key('Company', 'Google')) -~~~~ - -In order to filter by ancestors, use `hasAncestor` helper. - -~~~ js -var q = ds.createQuery('Child') - .hasAncestor(ds.key('Parent', 123)); -~~~ - -##### Sorting - -You can sort the results by a property name ascendingly or descendingly. - -~~~~ js -// sorts by size ascendingly. (default) -var q = ds.createQuery('Company').order('size'); - -// sorts by size descendingly. -var q = ds.createQuery('Company').order('-size'); -~~~~ - -##### Selection (or Projection) - -You may prefer to retrieve only a few of the properties of the entities. - -~~~~ js -// retrieves names and sizes of all companies. -var q = ds.createQuery('Company').select(['name', 'size']); -~~~~ - -##### Pagination - -Pagination allows you to set an offset, limit and starting cursor to a query. - -~~~~ js -var q = ds.createQuery('Company') - .start(cursorToken) // continue to retrieve results from the given cursor. - .offset(100) // start from the 101th result after start cursor. - .limit(10); // return only 10 results -~~~~ - -#### Allocating IDs (ID generation) - -You can generate IDs without creating entities. The following call will create -100 new IDs from the Company kind which exists under the dataset's namespace. If -no namespace was provided when the dataset was created, the default namespace -will be used. - -~~~~ js -ds.allocateIds(ds.key('Company', null), 100, function(err, keys) { - -}); -~~~~ - -#### Transactions - -Datastore has support for transactions. Transactions allow you to perform -multiple operations and commiting your changes atomically. - -`transaction` is a utility method to work with transactions. - -~~~~ js -ds.transaction(function(transaction, done) { - // call datastore methods as usual - // when you're done, call done - transaction.get(key, function(err, entity) { - if (err) { - transaction.rollback(done); - return; - } - // do any other operations with entity. - done(); - }); -}, function(err) { - // err exists if error during transaction - // creation or auto-commit. -}); -~~~~ - -* transaction.get([key], callback); -* transaction.save([{ key: '', data: {} }], callback); -* transaction.delete([key], callback); -* transaction.rollback(callback); -* transaction.commit(callback); +See [the API documentation](https://googlecloudplatform.github.io/module-datastore.html) for how to interact with the Datastore. ### Google Cloud Storage @@ -271,117 +59,7 @@ Google Cloud Storage allows you to store data on Google infrastructure. Read [Go You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on [Google Cloud Storage docs](https://developers.google.com/storage/) to create a bucket. -#### Configuration - -If you're running this client on Google Compute Engine, you need to initiate a bucket object with your bucket's name. - -~~~~ js -var gcloud = require('gcloud'), - bucket = new gcloud.storage.Bucket({ bucketName: YOUR_BUCKET_NAME }); -~~~~ - -Elsewhere, initiate with bucket's name and private key downloaded from Developer's Console. - -~~~~ js -var gcloud = require('gcloud'), - bucket = new gcloud.storage.Bucket({ - bucketName: YOUR_BUCKET_NAME, - keyFilename: '/path/to/the/key.json' - }); -~~~~ - -#### Listing Files - -~~~~ js -bucket.list(function(err, files, nextQuery) { - // nextQuery is not null if there are more results. - if (nextQuery) { - bucket.list(nextQuery, callback); - } -}); -~~~~ - -You can also provide a query. The following call will limit the number of -results to 5. - -~~~~ js -bucket.list({ maxResults: 5 }, function(err, files, nextQuery) {}); -~~~~ - -#### Stat Files - -You can retrieve file metadata by stating the file. - -~~~~ js -bucket.stat(filename, function(err, metadata) {}); -~~~~ - -#### Read File Contents - -Buckets provive a read stream to the file contents. You can pipe it to a write -stream, or listening 'data' events to read a file's contents. The following -example will create a readable stream to the file identified by filename, -and write the file contents to `/path/to/file`. - -~~~~ js -// Pipe a bucket file's contents to a writable stream. In this case, a local -// file "local-file-path" will be created. -bucket.createReadStream('remote-file-name') - .pipe(fs.createWriteStream('local-file-path')) - .on('error', function(err) {}) - .on('finish', function() {}); -~~~~ - -#### Write File Contents and Metadata - -A bucket object allows you to write a readable stream, a file and a buffer -as file contents. - -~~~~ js -// Uploads file.pdf. -fs.createReadStream('file.pdf') - .pipe(bucket.createWriteStream('MyPDFFile', {/* optional metadata. */})) - .on('error', function(err) {}) - .on('complete', function(fileObject) {}); -~~~~ - -You can also call `bucket.write` to send String or Buffer objects, along with -metadata. - -~~~~ js -var data; - -// The message can be any string or Buffer. -data = 'Hello World'; -bucket.write('HelloMessageFile', data, function(err, fileObject) {}); - -// To pass along metadata, embed the body of your message in a `data` property. -data = { - data: 'Hello World', - metadata: { - // ... - } -}; -bucket.write('HelloMessageFile', data, function(err, fileObject) {}); -~~~~ - -#### Copy Files - -You can copy an existing file. If no bucket name is provided for the destination -file, the current bucket name will be used. - -~~~~ js -bucket.copy('HelloMessageFile', { - bucket: 'other-bucket', - name: 'NewHelloMessageFileName' -}, function(err) {}); -~~~~ - -#### Remove Files - -~~~~ js -bucket.remove('HelloMessageFile', function(err) {}); -~~~~ +See [the API documentation](https://googlecloudplatform.github.io/module-storage.html) for how to connect to the Storage API. ### Google Cloud Pub/Sub (experimental) @@ -400,108 +78,124 @@ whitelisted to use it by filling the [Limited Preview application form](https:// If you're running this client on Google Compute Engine, you need to construct a pubsub Connection with your Google Developers Console project ID. -~~~~ js -var gcloud = require('gcloud'), - conn = new gcloud.pubsub.Connection({ projectId: YOUR_PROJECT_ID }); -~~~~ +```js +var gcloud = require('gcloud'); +var conn = new gcloud.pubsub.Connection({ + projectId: YOUR_PROJECT_ID +}); +``` -Elsewhere, construct with project ID, service account's email -and private key downloaded from Developer's Console. +Elsewhere, construct with a project ID, service account's email, and private key downloaded from Developer's Console. -~~~~ js -var gcloud = require('gcloud'), - conn = new gcloud.pubsub.Connection({ - projectId: YOUR_PROJECT_ID, - keyFilename: '/path/to/the/key.json' - }); -~~~~ +```js +var gcloud = require('gcloud'); +var conn = new gcloud.pubsub.Connection({ + projectId: YOUR_PROJECT_ID, + keyFilename: '/path/to/the/key.json' +}); +``` #### Topics and Subscriptions List, get, create and delete topics. -~~~ js -// lists topics. -conn.listTopics({ maxResults: 5 }, function(err, topics, nextQuery) { - // if more results, nextQuery will be non-null. +```js +// Lists topics. +conn.listTopics({ + maxResults: 5 +}, function(err, topics, nextQuery) { + // If there are more results, nextQuery will be non-null. }); -// retrieves an existing topic by name. +// Retrieve an existing topic by name. conn.getTopic('topic1', function(err, topic) { - // deletes this topic. + // Delete this topic. topic.del(callback); }); -// creates a new topic named topic2. +// Creates a new topic named topic2. conn.createTopic('topic2', callback); -~~~ +``` List, get, create and delete subscriptions. -~~~ js +```js var query = { maxResults: 5, filterByTopicName: 'topic1' }; -// list 5 subscriptions that are subscribed to topic1. + +// List 5 subscriptions that are subscribed to topic1. conn.listSubscriptions(query, function(err, subs, nextQuery) { // if there are more results, nextQuery will be non-null. }); -// get subscription named sub1 +// Get a subscription named sub1. conn.getSubscription('sub1', function(err, sub) { // delete this subscription. sub.del(callback); }); -// create a new subsription named sub2, listens to topic1. +// Create a new subsription named sub2 which listens to topic1. conn.createSubscription({ topic: 'topic1', name: 'sub2', ackDeadlineSeconds: 60 }, callback); -~~~ +``` #### Publishing a message -You need to retrieve or create a topic to publish a message. -You can either publish simple string messages or a raw Pub/Sub -message object. +You need to retrieve or create a topic to publish a message. You can either +publish simple string messages or a raw Pub/Sub message object. -~~~ js +```js conn.getTopic('topic1', function(err, topic) { - // publishes "hello world" to to topic1 subscribers. + // Publish "hello world" to topic1's subscribers. topic.publish('hello world', callback); topic.publishMessage({ data: 'Some text here...', label: [ - { key: 'priority', numValue: 0 }, - { key: 'foo', stringValue: 'bar' } + { + key: 'priority', + numValue: 0 + }, + { + key: 'foo', + stringValue: 'bar' + } ] }, callback); }); -~~~ +``` #### Listening for messages -You can either pull messages one by one via a subscription, or -let the client to open a long-lived request to poll them. +You can either pull messages one by one via a subscription, or let the client +open a long-lived request to poll them. + +```js +// Allow client to poll messages from sub1. +// `autoAck` automatically acknowledges the messages. (default: false) +var sub = conn.subscribe('sub1', { + autoAck: true +}); -~~~ js -// allow client to poll messages from sub1 -// autoAck automatically acknowledges the messages. by default, false. -var sub = conn.subscribe('sub1', { autoAck: true }); sub.on('ready', function() { - console.log('listening messages...'); + console.log('Listening for messages...'); }); + sub.on('message', function(msg) { - console.log('message retrieved:', msg); + console.log('Message retrieved:', msg); }); + sub.on('error', function(err) { - console.log('error occured:', err); + console.log('An error occurred:', err); }); -sub.close(); // closes the connection, stops listening for messages. -~~~ + +// Closes the connection and stop listening for messages. +sub.close(); +``` ## Contributing diff --git a/docs/dataset.html b/docs/dataset.html new file mode 100644 index 00000000000..d5369c319d0 --- /dev/null +++ b/docs/dataset.html @@ -0,0 +1,1696 @@ + + + + + JSDoc: Module: datastore/dataset + + + + + + + + + + +
+ +

Module: datastore/dataset

+ + + + + +
+ +
+

+ datastore/dataset +

+ +
+ +
+
+ + +
+

new (require("datastore/dataset"))(optionsopt)

+ + +
+
+ + +
+

Intract with a dataset from the +Google Cloud Datastore.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
options + + +object + + + + + + <optional>
+ + + + + + 		+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
projectId + + +string + + + +

Dataset ID. This is your project ID from + the Google Developers Console.

keyFilename + + +string + + + +

Full path to the JSON key downloaded + from the Google Developers Console.

namespace + + +string + + + +

Namespace to isolate transactions to.

+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
var dataset = new datastore.Dataset({
+  projectId: 'my-project',
+  keyFilename: '/path/to/keyfile.json'
+});
+ + +
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + + + +

Methods

+ +
+ +
+

allocateIds(incompleteKey, n, callback)

+ + +
+
+ + +
+

Generate IDs without creating entities.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
incompleteKey + + +Key + + + +

The key object to complete.

n + + +number + + + +

How many IDs to generate.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
// The following call will create 100 new IDs from the Company kind, which
+// exists under the default namespace.
+var incompleteKey = datastore.key('Company', null);
+dataset.allocateIds(incompleteKey, 100, function(err, keys) {});
+
+// You may prefer to create IDs from a non-default namespace by providing an
+// incomplete key with a namespace. Similar to the previous example, the call
+// below will create 100 new IDs, but from the Company kind that exists under
+// the "ns-test" namespace.
+var incompleteKey = datastore.key('ns-test', 'Company', null);
+dataset.allocateIds(incompleteKey, 100, function(err, keys) {});
+ + +
+ + + +
+

createQuery(namespaceopt, kinds) → {module:datastore/query}

+ + +
+
+ + +
+

Create a query from the current dataset to query the specified kinds, scoped +to the namespace provided at the initialization of the dataset.

+

Dataset query reference: http://goo.gl/Cag0r6

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
namespace + + +string + + + + + + <optional>
+ + + + + +

Optional namespace.

kinds + + +string +| + +array + + + + + + + + + +

Kinds to query.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
+ + + +
+

delete(key, callback)

+ + +
+
+ + +
+

Delete all entities identified with the specified key(s) in the current +transaction.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
key + + +Key +| + +Array.<Key> + + + +

Datastore key object(s).

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
// Delete a single entity.
+dataset.delete(datastore.key('Company', 123), function(err) {});
+
+// Delete multiple entities at once.
+dataset.delete([
+  datastore.key('Company', 123),
+  datastore.key('Product', 'Computer')
+], function(err) {});
+ + +
+ + + +
+

get(key, callback)

+ + +
+
+ + +
+

Retrieve the entities identified with the specified key(s) in the current +transaction. Get operations require a valid key to retrieve the +key-identified entity from Datastore.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
key + + +module:datastore/entity~Key +| + +Array.<module:datastore/entity~Key> + + + +

Datastore key object(s).

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
dataset.get([
+  datastore.key('Company', 123),
+  datastore.key('Product', 'Computer')
+], function(err, entities) {});
+ + +
+ + + +
+

key()

+ + +
+
+ + +
+

Helper to create a Key object, scoped to the dataset's namespace by default.

+

You may also specify a configuration object to define a namespace and path.

+
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
var key;
+
+// Create a key from the dataset's namespace.
+key = dataset.key('Company', 123);
+
+// Create a key from a provided namespace and path.
+key = dataset.key({
+  namespace: 'My-NS',
+  path: ['Company', 123]
+});
+ + +
+ + + +
+

runInTransaction(fn, callback)

+ + +
+
+ + +
+

Run a function in the context of a new transaction. Transactions allow you to +perform multiple operations, committing your changes atomically.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
fn + + +function + + + +

The function to run in the context of a transaction.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
dataset.transaction(function(transaction, done) {
+  // From the `transaction` object, execute dataset methods as usual.
+  // Call `done` when you're ready to commit all of the changes.
+  transaction.get(datastore.key('Company', 123), function(err, entity) {
+    if (err) {
+      transaction.rollback(done);
+      return;
+    }
+
+    done();
+  });
+}, function(err) {});
+ + +
+ + + +
+

runQuery(query, callback)

+ + +
+
+ + +
+

Datastore allows you to query entities by kind, filter them by property +filters, and sort them by a property name. Projection and pagination are also +supported. If more results are available, a query to retrieve the next page +is provided to the callback function.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
query + + +module:datastore/query + + + +

Query object.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
// Retrieve 5 companies.
+dataset.runQuery(queryObject, function(err, entities, nextQuery) {
+  // `nextQuery` is not null if there are more results.
+  if (nextQuery) {
+    dataset.runQuery(nextQuery, function(err, entities, nextQuery) {});
+  }
+});
+ + +
+ + + +
+

save(entities, callback)

+ + +
+
+ + +
+

Insert or update the specified object(s) in the current transaction. If a +key is incomplete, its associated object is inserted and its generated +identifier is returned to the callback.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
entities + + +object +| + +Array.<object> + + + +

Datastore key object(s).

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
key + + +Key + + + +

Datastore key object.

data + + +object + + + +

Data to save with the provided key.

+
callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
// Save a single entity.
+dataset.save({
+  key: datastore.key('Company', null),
+  data: {
+    rating: '10'
+  }
+}, function(err, key) {
+  // Because we gave an incomplete key as an argument, `key` will be
+  // populated with the complete, generated key.
+});
+
+// Save multiple entities at once.
+dataset.save([
+  {
+    key: datastore.key('Company', 123),
+    data: {
+      HQ: 'Dallas, TX'
+    }
+  },
+  {
+    key: datastore.key('Product', 'Computer'),
+    data: {
+      vendor: 'Dell'
+    }
+  }
+], function(err, keys) {});
+ + +
+ +
+ + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/dataset.js.html b/docs/dataset.js.html new file mode 100644 index 00000000000..089ef142f65 --- /dev/null +++ b/docs/dataset.js.html @@ -0,0 +1,398 @@ + + + + + JSDoc: Source: datastore/dataset.js + + + + + + + + + + +
+ +

Source: datastore/dataset.js

+ + + + + +
+
+ 
/**
+ * Copyright 2014 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.
+ */
+
+/**
+ * @module datastore/dataset
+ */
+
+'use strict';
+
+/**
+ * @private
+ * @type module:common/connection
+ */
+var conn = require('../common/connection.js');
+
+/**
+ * @private
+ * @type module:datastore/entity
+ */
+var entity = require('./entity.js');
+
+/**
+ * @private
+ * @type module:datastore/pb
+ */
+var pb = require('./pb.js');
+
+/**
+ * @private
+ * @type module:datastore/query
+ */
+var Query = require('./query.js');
+
+/**
+ * @private
+ * @type module:datastore/transaction
+ */
+var Transaction = require('./transaction.js');
+
+/**
+ * @private
+ * @type module:common/util
+ */
+var util = require('../common/util.js');
+
+/**
+ * Scopes for Google Datastore access.
+ * @private
+ * @const {array} SCOPES
+ */
+var SCOPES = [
+  'https://www.googleapis.com/auth/datastore',
+  'https://www.googleapis.com/auth/userinfo.email'
+];
+
+/**
+ * Intract with a dataset from the
+ * [Google Cloud Datastore]{@link https://developers.google.com/datastore/}.
+ *
+ * @constructor
+ * @alias module:datastore/dataset
+ *
+ * @param {object=} options
+ * @param {string} options.projectId - Dataset ID. This is your project ID from
+ *     the Google Developers Console.
+ * @param {string} options.keyFilename - Full path to the JSON key downloaded
+ *     from the Google Developers Console.
+ * @param {string} options.namespace - Namespace to isolate transactions to.
+ *
+ * @example
+ * var dataset = new datastore.Dataset({
+ *   projectId: 'my-project',
+ *   keyFilename: '/path/to/keyfile.json'
+ * });
+ */
+function Dataset(options) {
+  options = options || {};
+
+  this.connection = new conn.Connection({
+    keyFilename: options.keyFilename,
+    scopes: SCOPES
+  });
+  this.id = options.projectId;
+  this.namespace = options.namespace;
+  this.transaction = this.createTransaction_();
+}
+
+/**
+ * Helper to create a Key object, scoped to the dataset's namespace by default.
+ *
+ * You may also specify a configuration object to define a namespace and path.
+ *
+ * @example
+ * var key;
+ *
+ * // Create a key from the dataset's namespace.
+ * key = dataset.key('Company', 123);
+ *
+ * // Create a key from a provided namespace and path.
+ * key = dataset.key({
+ *   namespace: 'My-NS',
+ *   path: ['Company', 123]
+ * });
+ */
+Dataset.prototype.key = function(keyConfig) {
+  if (!util.is(keyConfig, 'object')) {
+    keyConfig = {
+      namespace: this.namespace,
+      path: util.toArray(arguments)
+    };
+  }
+  return new entity.Key(keyConfig);
+};
+
+
+/**
+ * Create a query from the current dataset to query the specified kinds, scoped
+ * to the namespace provided at the initialization of the dataset.
+ *
+ * *Dataset query reference: {@link http://goo.gl/Cag0r6}*
+ *
+ * @borrows {module:datastore/query} as createQuery
+ * @see {module:datastore/query}
+ *
+ * @param {string=} namespace - Optional namespace.
+ * @param {string|array} kinds - Kinds to query.
+ * @return {module:datastore/query}
+ */
+Dataset.prototype.createQuery = function(namespace, kinds) {
+  if (arguments.length === 1) {
+    kinds = util.arrayize(namespace);
+    namespace = this.namespace;
+  }
+  return new Query(namespace, util.arrayize(kinds));
+};
+
+/**
+ * Retrieve the entities identified with the specified key(s) in the current
+ * transaction. Get operations require a valid key to retrieve the
+ * key-identified entity from Datastore.
+ *
+ * @borrows {module:datastore/transaction#get} as get
+ *
+ * @param {module:datastore/entity~Key|module:datastore/entity~Key[]} key -
+ *     Datastore key object(s).
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * dataset.get([
+ *   datastore.key('Company', 123),
+ *   datastore.key('Product', 'Computer')
+ * ], function(err, entities) {});
+ */
+Dataset.prototype.get = function(key, callback) {
+  this.transaction.get(key, callback);
+};
+
+/**
+ * Insert or update the specified object(s) in the current transaction. If a
+ * key is incomplete, its associated object is inserted and its generated
+ * identifier is returned to the callback.
+ *
+ * @borrows {module:datastore/transaction#save} as save
+ *
+ * @param {object|object[]} entities - Datastore key object(s).
+ * @param {Key} entities.key - Datastore key object.
+ * @param {object} entities.data - Data to save with the provided key.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Save a single entity.
+ * dataset.save({
+ *   key: datastore.key('Company', null),
+ *   data: {
+ *     rating: '10'
+ *   }
+ * }, function(err, key) {
+ *   // Because we gave an incomplete key as an argument, `key` will be
+ *   // populated with the complete, generated key.
+ * });
+ *
+ * // Save multiple entities at once.
+ * dataset.save([
+ *   {
+ *     key: datastore.key('Company', 123),
+ *     data: {
+ *       HQ: 'Dallas, TX'
+ *     }
+ *   },
+ *   {
+ *     key: datastore.key('Product', 'Computer'),
+ *     data: {
+ *       vendor: 'Dell'
+ *     }
+ *   }
+ * ], function(err, keys) {});
+ */
+Dataset.prototype.save = function(key, obj, callback) {
+  this.transaction.save(key, obj, callback);
+};
+
+/**
+ * Delete all entities identified with the specified key(s) in the current
+ * transaction.
+ *
+ * @param {Key|Key[]} key - Datastore key object(s).
+ * @param {function} callback - The callback function.
+ *
+ * @borrows {module:datastore/transaction#delete} as delete
+ *
+ * @example
+ * // Delete a single entity.
+ * dataset.delete(datastore.key('Company', 123), function(err) {});
+ *
+ * // Delete multiple entities at once.
+ * dataset.delete([
+ *   datastore.key('Company', 123),
+ *   datastore.key('Product', 'Computer')
+ * ], function(err) {});
+ */
+Dataset.prototype.delete = function(key, callback) {
+  this.transaction.delete(key, callback);
+};
+
+/**
+ * Datastore allows you to query entities by kind, filter them by property
+ * filters, and sort them by a property name. Projection and pagination are also
+ * supported. If more results are available, a query to retrieve the next page
+ * is provided to the callback function.
+ *
+ * @borrows {module:datastore/transaction#runQuery} as runQuery
+ *
+ * @param {module:datastore/query} query - Query object.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Retrieve 5 companies.
+ * dataset.runQuery(queryObject, function(err, entities, nextQuery) {
+ *   // `nextQuery` is not null if there are more results.
+ *   if (nextQuery) {
+ *     dataset.runQuery(nextQuery, function(err, entities, nextQuery) {});
+ *   }
+ * });
+ */
+Dataset.prototype.runQuery = function(q, callback) {
+  this.transaction.runQuery(q, callback);
+};
+
+/**
+ * Run a function in the context of a new transaction. Transactions allow you to
+ * perform multiple operations, committing your changes atomically.
+ *
+ * @borrows {module:datastore/transaction#begin} as runInTransaction
+ *
+ * @param {function} fn - The function to run in the context of a transaction.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * dataset.transaction(function(transaction, done) {
+ *   // From the `transaction` object, execute dataset methods as usual.
+ *   // Call `done` when you're ready to commit all of the changes.
+ *   transaction.get(datastore.key('Company', 123), function(err, entity) {
+ *     if (err) {
+ *       transaction.rollback(done);
+ *       return;
+ *     }
+ *
+ *     done();
+ *   });
+ * }, function(err) {});
+ */
+Dataset.prototype.runInTransaction = function(fn, callback) {
+  var newTransaction = this.createTransaction_();
+  newTransaction.begin(function(err) {
+    if (err) {
+      return callback(err);
+    }
+    fn(newTransaction, newTransaction.finalize.bind(newTransaction, callback));
+  });
+};
+
+/**
+ * Generate IDs without creating entities.
+ *
+ * @param {Key} incompleteKey - The key object to complete.
+ * @param {number} n - How many IDs to generate.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // The following call will create 100 new IDs from the Company kind, which
+ * // exists under the default namespace.
+ * var incompleteKey = datastore.key('Company', null);
+ * dataset.allocateIds(incompleteKey, 100, function(err, keys) {});
+ *
+ * // You may prefer to create IDs from a non-default namespace by providing an
+ * // incomplete key with a namespace. Similar to the previous example, the call
+ * // below will create 100 new IDs, but from the Company kind that exists under
+ * // the "ns-test" namespace.
+ * var incompleteKey = datastore.key('ns-test', 'Company', null);
+ * dataset.allocateIds(incompleteKey, 100, function(err, keys) {});
+ */
+Dataset.prototype.allocateIds = function(incompleteKey, n, callback) {
+  if (entity.isKeyComplete(incompleteKey)) {
+    throw new Error('An incomplete key should be provided.');
+  }
+  var incompleteKeys = [];
+  for (var i = 0; i < n; i++) {
+    incompleteKeys.push(entity.keyToKeyProto(incompleteKey));
+  }
+  this.transaction.makeReq(
+      'allocateIds',
+      new pb.AllocateIdsRequest({ key: incompleteKeys }),
+      pb.AllocateIdsResponse, function(err, resp) {
+    if (err) {
+      return callback(err);
+    }
+    var keys = [];
+    (resp.key || []).forEach(function(k) {
+      keys.push(entity.keyFromKeyProto(k));
+    });
+    callback(null ,keys);
+  });
+};
+
+/**
+ * Create a new Transaction object using the existing connection and dataset.
+ *
+ * @private
+ * @return {module:datastore/transaction}
+ */
+Dataset.prototype.createTransaction_ = function() {
+  return new Transaction(this.connection, this.id);
+};
+
+module.exports = Dataset;
+
+
+
+ + + + +
+ + + +
+ + + + + + + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000000..a8a94255763 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,391 @@ + + + + + JSDoc: Module: gcloud + + + + + + + + + + +
+ +

Module: gcloud

+ + + + + +
+ +
+

+ gcloud +

+ +
+ +
+
+ + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + +

Members

+ +
+ +
+

(static) datastore :module:datastore

+ + +
+
+ +
+

Google Cloud Datastore is a +fully managed, schemaless database for storing non-relational data. Use this +object to create a Dataset to interact with your data, an "Int", and a +"Double" representation.

+
+ + + +
Type:
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var datastore = gcloud.datastore;
+
+// datastore:
+// {
+//   Dataset: function() {},
+//   double: function() {},
+//   int: function() {}
+// }
+ + +
+ + + +
+

(static) pubsub :module:pubsub

+ + +
+
+ +
+

Experimental

+

Google Cloud Pub/Sub +is a reliable, many-to-many, asynchronous messaging service from Google Cloud +Platform.

+

Note: Google Cloud Pub/Sub API is available as a Limited Preview and the +client library we provide is currently experimental. The API and/or the +client might be changed in backward-incompatible ways. This API is not +subject to any SLA or deprecation policy. Request to be whitelisted to use it +by filling the +Limited Preview application form.

+
+ + + +
Type:
+
    +
  • + +module:pubsub + + +
    • +
+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var pubsub = gcloud.pubsub;
+
+var conn = new pubsub.Connection({
+  projectId: YOUR_PROJECT_ID,
+  keyFilename: '/path/to/the/key.json'
+});
+ + +
+ + + +
+

(static) storage :module:storage

+ + +
+
+ +
+

Google Cloud Storage allows you to store data on Google infrastructure. Read +Google Cloud Storage API docs +for more information.

+

You need to create a Google Cloud Storage bucket to use this client library. +Follow the steps on +Google Cloud Storage docs to +create a bucket.

+
+ + + +
Type:
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var storage = gcloud.storage;
+
+// storage:
+// {
+//   Bucket: function() {}
+// }
+ + +
+ +
+ + + + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/index.js.html b/docs/index.js.html new file mode 100644 index 00000000000..233c7915aa2 --- /dev/null +++ b/docs/index.js.html @@ -0,0 +1,120 @@ + + + + + JSDoc: Source: datastore/index.js + + + + + + + + + + +
+ +

Source: datastore/index.js

+ + + + + +
+
+ 
/**
+ * Copyright 2014 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.
+ */
+
+/**
+ * @module datastore
+ */
+
+'use strict';
+
+/**
+ * @private
+ * @type module:datastore/entity
+ */
+var entity = require('./entity');
+
+/** @alias module:datastore */
+var datastore = {};
+
+/**
+ * @see {module:datastore/dataset}
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var datastore = gcloud.datastore;
+ *
+ * // Create a Dataset object.
+ * var dataset = new datastore.Dataset();
+ */
+datastore.Dataset = require('./dataset');
+
+/**
+ * Helper function to get a Datastore Integer object.
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ *
+ * // Create an Integer.
+ * var sevenInteger = gcloud.datastore.int(7);
+ */
+datastore.int = function(value) {
+  return new entity.Int(value);
+};
+
+/**
+ * Helper function to get a Datastore Double object.
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ *
+ * // Create a Double.
+ * var threeDouble = gcloud.datastore.double(3.0);
+ */
+datastore.double = function(value) {
+  return new entity.Double(value);
+};
+
+module.exports = datastore;
+
+
+
+ + + + +
+ + + +
+ + + + + + + diff --git a/docs/index.js_.html b/docs/index.js_.html new file mode 100644 index 00000000000..48ef2a469f3 --- /dev/null +++ b/docs/index.js_.html @@ -0,0 +1,155 @@ + + + + + JSDoc: Source: index.js + + + + + + + + + + +
+ +

Source: index.js

+ + + + + +
+
+ 
/**
+ * Copyright 2014 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.
+ */
+
+/**
+ * @module gcloud
+ */
+
+'use strict';
+
+/** @alias module:gcloud */
+var gcloud = {};
+
+/**
+ * [Google Cloud Datastore]{@link https://developers.google.com/datastore/} is a
+ * fully managed, schemaless database for storing non-relational data. Use this
+ * object to create a Dataset to interact with your data, an "Int", and a
+ * "Double" representation.
+ *
+ * @type {module:datastore}
+ * @see {module:datastore}
+ *
+ * @return {object}
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var datastore = gcloud.datastore;
+ *
+ * // datastore:
+ * // {
+ * //   Dataset: function() {},
+ * //   double: function() {},
+ * //   int: function() {}
+ * // }
+ */
+gcloud.datastore = require('./datastore');
+
+/**
+ * **Experimental**
+ *
+ * [Google Cloud Pub/Sub]{@link https://developers.google.com/pubsub/overview}
+ * is a reliable, many-to-many, asynchronous messaging service from Google Cloud
+ * Platform.
+ *
+ * Note: Google Cloud Pub/Sub API is available as a Limited Preview and the
+ * client library we provide is currently experimental. The API and/or the
+ * client might be changed in backward-incompatible ways. This API is not
+ * subject to any SLA or deprecation policy. Request to be whitelisted to use it
+ * by filling the
+ * [Limited Preview application form]{@link http://goo.gl/sO0wTu}.
+ *
+ * @type {module:pubsub}
+ *
+ * @return {object}
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var pubsub = gcloud.pubsub;
+ *
+ * var conn = new pubsub.Connection({
+ *   projectId: YOUR_PROJECT_ID,
+ *   keyFilename: '/path/to/the/key.json'
+ * });
+ */
+gcloud.pubsub = require('./pubsub');
+
+/**
+ * Google Cloud Storage allows you to store data on Google infrastructure. Read
+ * [Google Cloud Storage API docs]{@link https://developers.google.com/storage/}
+ * for more information.
+ *
+ * You need to create a Google Cloud Storage bucket to use this client library.
+ * Follow the steps on
+ * [Google Cloud Storage docs]{@link https://developers.google.com/storage/} to
+ * create a bucket.
+
+ * @type {module:storage}
+ * @see {module:storage}
+ *
+ * @return {object}
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var storage = gcloud.storage;
+ *
+ * // storage:
+ * // {
+ * //   Bucket: function() {}
+ * // }
+ */
+gcloud.storage = require('./storage');
+
+module.exports = gcloud;
+
+
+
+ + + + +
+ + + +
+ + + + + + + diff --git a/docs/index.js__.html b/docs/index.js__.html new file mode 100644 index 00000000000..79aeea6d313 --- /dev/null +++ b/docs/index.js__.html @@ -0,0 +1,471 @@ + + + + + JSDoc: Source: storage/index.js + + + + + + + + + + +
+ +

Source: storage/index.js

+ + + + + +
+
+ 
/**
+ * Copyright 2014 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.
+ */
+
+/**
+ * @module storage
+ */
+
+'use strict';
+
+var duplexify = require('duplexify');
+var nodeutil = require('util');
+var stream = require('stream');
+var uuid = require('node-uuid');
+
+/**
+ * @private
+ * @type module:common/connection
+ */
+var conn = require('../common/connection.js');
+
+/**
+ * @private
+ * @type module:common/util
+ */
+var util = require('../common/util.js');
+
+/**
+ * Required scopes for Google Cloud Storage API.
+ * @private
+ * @const {array}
+ */
+var SCOPES = ['https://www.googleapis.com/auth/devstorage.full_control'];
+
+/**
+ * @private
+ * @const {string}
+ */
+var STORAGE_BASE_URL = 'https://www.googleapis.com/storage/v1/b';
+
+/**
+ * @private
+ * @const {string}
+ */
+var STORAGE_UPLOAD_BASE_URL = 'https://www.googleapis.com/upload/storage/v1/b';
+
+/**
+ * Readable stream implementation to stream the given buffer.
+ *
+ * @private
+ *
+ * @constructor
+ *
+ * @param {buffer} buffer - The buffer to stream.
+ */
+function BufferStream(buffer) {
+  stream.Readable.call(this);
+  this.data = buffer;
+}
+
+nodeutil.inherits(BufferStream, stream.Readable);
+
+/**
+ * Push the provided buffer to the stream.
+ */
+BufferStream.prototype._read = function() {
+  this.push(this.data);
+  this.push(null);
+};
+
+/**
+ * Google Cloud Storage allows you to store data on Google infrastructure. See
+ * the guide on {@link https://developers.google.com/storage} to create a
+ * bucket.
+ *
+ * @alias module:storage
+
+ * @throws if a bucket name isn't provided.
+ *
+ * @param {object} options - Configuration options.
+ * @param {string} options.bucketName - Name of the bucket.
+ * @param {string} options.keyFilename - Full path to the JSON key downloaded
+ *     from the Google Developers Console.
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var storage = gcloud.storage;
+ * var bucket;
+ *
+ * // From Google Compute Engine
+ * bucket = new storage.Bucket({
+ *   bucketName: YOUR_BUCKET_NAME
+ * });
+ *
+ * // From elsewhere
+ * bucket = new storage.Bucket({
+ *   bucketName: YOUR_BUCKET_NAME,
+ *   keyFilename: '/path/to/the/key.json'
+ * });
+ */
+function Bucket(options) {
+  if (!options.bucketName) {
+    throw Error('A bucket name is needed to use Google Cloud Storage');
+  }
+  this.bucketName = options.bucketName;
+  this.conn = new conn.Connection({
+    keyFilename: options.keyFilename,
+    scopes: SCOPES
+  });
+}
+
+/**
+ * List files from the current bucket.
+ *
+ * @param {object=} query - Query object.
+ * @param {string} query.delimeter - Results will contain only objects whose
+ *     names, aside from the prefix, do not contain delimiter. Objects whose
+ *     names, aside from the prefix, contain delimiter will have their name
+ *     truncated after the delimiter, returned in prefixes. Duplicate prefixes
+ *     are omitted.
+ * @param {string} query.prefix - Filters results to objects whose names begin
+ *     with this prefix.
+ * @param {number} query.maxResults - Maximum number of items plus prefixes to
+ *     return.
+ * @param {string} query.pageToken - A previously-returned page token
+ *     representing part of the larger set of results to view.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * bucket.list(function(err, files, nextQuery) {
+ *   if (nextQuery) {
+ *     // nextQuery will be non-null if there are more results.
+ *     bucket.list(nextQuery, function(err, files, nextQuery) {});
+ *   }
+ * });
+ *
+ * // Fetch using a query.
+ * bucket.list({ maxResults: 5 }, function(err, files, nextQuery) {});
+ */
+Bucket.prototype.list = function(query, callback) {
+  if (arguments.length === 1) {
+    callback = query;
+    query = {};
+  }
+  this.makeReq('GET', 'o', query, true, function(err, resp) {
+    if (err) {
+      return callback(err);
+    }
+    var nextQuery = null;
+    if (resp.nextPageToken) {
+      nextQuery = util.extend({}, query);
+      nextQuery.pageToken = resp.nextPageToken;
+    }
+    callback(null, resp.items, nextQuery);
+  });
+};
+
+/**
+ * Stat a file.
+ *
+ * @param {string} name - Name of the remote file.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * bucket.stat('filename', function(err, metadata){});
+ */
+Bucket.prototype.stat = function(name, callback) {
+  var path = util.format('o/{name}', { name: name });
+  this.makeReq('GET', path, null, true, callback);
+};
+
+/**
+ * Copy an existing file. If no bucket name is provided for the destination
+ * file, the current bucket name will be used.
+ *
+ * @throws if the destination filename is not provided.
+ *
+ * @param {string} name - Name of the existing file.
+ * @param {object} metadata - Destination file metadata object.
+ * @param {string} metadata.name - Name of the destination file.
+ * @param {string=} metadata.bucket - Destination bucket for the file. If none
+ *     is provided, the source's bucket name is used.
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * bucket.copy('filename', {
+ *    bucket: 'destination-bucket',
+ *    name: 'destination-filename'
+ * }, function(err) {});
+ */
+Bucket.prototype.copy = function(name, metadata, callback) {
+  callback = callback || util.noop;
+  if (!metadata.name) {
+    throw new Error('Destination file should have a name.');
+  }
+  if (!metadata.bucket) {
+    metadata.bucket = this.bucketName;
+  }
+  var path = util.format('o/{srcName}/copyTo/b/{destBucket}/o/{destName}', {
+    srcName: name,
+    destBucket: metadata.bucket,
+    destName: metadata.name
+  });
+  delete metadata.name;
+  delete metadata.bucket;
+  this.makeReq('POST', path, null, metadata, callback);
+};
+
+/**
+ * Remove a file.
+ *
+ * @param {string} name - Name of the file to remove.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * bucket.remove('filename', function(err) {});
+ */
+Bucket.prototype.remove = function(name, callback) {
+  var path = util.format('o/{name}', { name: name });
+  this.makeReq('DELETE', path, null, true, callback);
+};
+
+/**
+ * Create a readable stream to read contents of the provided remote file. It
+ * can be piped to a write stream, or listened to for 'data' events to read a
+ * file's contents.
+ *
+ * @param {string} name - Name of the remote file.
+ * @return {ReadStream}
+ *
+ * @example
+ * // Create a readable stream and write the file contents to "local-file-path".
+ * var fs = require('fs');
+ *
+ * bucket.createReadStream('remote-file-name')
+ *    .pipe(fs.createWriteStream('local-file-path'))
+ *    .on('error', function(err) {});
+ */
+Bucket.prototype.createReadStream = function(name) {
+  var that = this;
+  var dup = duplexify();
+  this.stat(name, function(err, metadata) {
+    if (err) {
+      dup.emit('error', err);
+      return;
+    }
+    that.conn.createAuthorizedReq(
+        { uri: metadata.mediaLink }, function(err, req) {
+      if (err) {
+        dup.emit('error', err);
+        return;
+      }
+      dup.setReadable(that.conn.requester(req));
+    });
+  });
+  return dup;
+};
+
+/**
+ * Create a Duplex to handle the upload of a file.
+ *
+ * @param {string} name - Name of the remote file to create.
+ * @param {object=} metadata - Optional metadata.
+ * @return {stream}
+ *
+ * @example
+ * // Read from a local file and pipe to your bucket.
+ * var fs = require('fs');
+ *
+ * fs.createReadStream('local-file-path')
+ *     .pipe(bucket.createWriteStream('remote-file-name'))
+ *     .on('error', function(err) {})
+ *     .on('complete', function(fileObject) {});
+ */
+Bucket.prototype.createWriteStream = function(name, metadata) {
+  var dup = duplexify();
+  this.getWritableStream_(name, (metadata || {}), function(err, writable) {
+    if (err) {
+      dup.emit('error', err);
+      return;
+    }
+    writable.on('complete', function(res) {
+      util.handleResp(null, res, res.body, function(err, data) {
+        if (err) {
+          dup.emit('error', err);
+          return;
+        }
+        dup.emit('complete', data);
+      });
+    });
+    dup.setWritable(writable);
+    dup.pipe(writable);
+  });
+  return dup;
+};
+
+/**
+ * Write the provided data to the destination with optional metadata.
+ *
+ * @param {string} name - Name of the remote file toc reate.
+ * @param {object|string|buffer} options - Configuration object or data.
+ * @param {object=} options.metadata - Optional metadata.
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * // Upload "Hello World" as file contents. `data` can be any string or buffer.
+ * bucket.write('filename', {
+ *   data: 'Hello World'
+ * }, function(err) {});
+ *
+ * // A shorthand for the above.
+ * bucket.write('filename', 'Hello World', function(err) {});
+ */
+Bucket.prototype.write = function(name, options, callback) {
+  callback = callback || util.noop;
+  var data = typeof options === 'object' ? options.data : options;
+  var metadata = options.metadata || {};
+
+  if (typeof data === 'undefined') {
+    // metadata only write
+    this.makeReq('PATCH', 'o/' + name, null, metadata, callback);
+    return;
+  }
+
+  if (typeof data === 'string' || data instanceof Buffer) {
+    new BufferStream(data).pipe(this.createWriteStream(name, metadata))
+        .on('error', callback)
+        .on('complete', callback.bind(null, null));
+  }
+};
+
+/**
+ * Get a remote stream to begin piping a readable stream to.
+ *
+ * @private
+ *
+ * @param {string} name - The desired name of the file.
+ * @param {object} metadata - File descriptive metadata.
+ * @param {function} callback - The callback function.
+ */
+Bucket.prototype.getWritableStream_ = function(name, metadata, callback) {
+  var boundary = uuid.v4();
+  var that = this;
+  metadata.contentType = metadata.contentType || 'text/plain';
+  this.conn.createAuthorizedReq({
+    method: 'POST',
+    uri: util.format('{base}/{bucket}/o', {
+      base: STORAGE_UPLOAD_BASE_URL,
+      bucket: this.bucketName
+    }),
+    qs: {
+      name: name,
+      uploadType: 'multipart'
+    },
+    headers: {
+      'Content-Type': 'multipart/related; boundary="' + boundary + '"'
+    }
+  }, function(err, req) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    var remoteStream = that.conn.requester(req);
+    remoteStream.callback = util.noop;
+    remoteStream.write('--' + boundary + '\n');
+    remoteStream.write('Content-Type: application/json\n\n');
+    remoteStream.write(JSON.stringify(metadata));
+    remoteStream.write('\n\n');
+    remoteStream.write('--' + boundary + '\n');
+    remoteStream.write('Content-Type: ' + metadata.contentType + '\n\n');
+    var oldEndFn = remoteStream.end;
+    remoteStream.end = function(data, encoding, callback) {
+      data = (data || '') + '\n--' + boundary + '--\n';
+      remoteStream.write(data, encoding, callback);
+      oldEndFn.apply(this);
+    };
+    callback(null, remoteStream);
+  });
+};
+
+/**
+ * Make a new request object from the provided arguments and wrap the callback
+ * to intercept non-successful responses.
+ *
+ * @param {string} method - Action.
+ * @param {string} path - Request path.
+ * @param {*} query - Request query object.
+ * @param {*} body - Request body contents.
+ * @param {function} callback - The callback function.
+ */
+Bucket.prototype.makeReq = function(method, path, query, body, callback) {
+  var reqOpts = {
+    method: method,
+    qs: query,
+    uri: util.format('{base}/{bucket}/{path}', {
+      base: STORAGE_BASE_URL,
+      bucket: this.bucketName,
+      path: path
+    })
+  };
+  if (body) {
+    reqOpts.json = body;
+  }
+  this.conn.req(reqOpts, function(err, res, body) {
+    util.handleResp(err, res, body, callback);
+  });
+};
+
+module.exports.Bucket = Bucket;
+
+
+
+ + + + +
+ + + +
+ + + + + + + diff --git a/docs/module-datastore.html b/docs/module-datastore.html new file mode 100644 index 00000000000..3cfbb74e55f --- /dev/null +++ b/docs/module-datastore.html @@ -0,0 +1,356 @@ + + + + + JSDoc: Module: datastore + + + + + + + + + + +
+ +

Module: datastore

+ + + + + +
+ +
+

+ datastore +

+ +
+ +
+
+ + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + +

Members

+ +
+ +
+

(static) Dataset

+ + +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var datastore = gcloud.datastore;
+
+// Create a Dataset object.
+var dataset = new datastore.Dataset();
+ + +
+ +
+ + + +

Methods

+ +
+ +
+

(static) double()

+ + +
+
+ + +
+

Helper function to get a Datastore Double object.

+
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
var gcloud = require('gcloud');
+
+// Create a Double.
+var threeDouble = gcloud.datastore.double(3.0);
+ + +
+ + + +
+

(static) int()

+ + +
+
+ + +
+

Helper function to get a Datastore Integer object.

+
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
var gcloud = require('gcloud');
+
+// Create an Integer.
+var sevenInteger = gcloud.datastore.int(7);
+ + +
+ +
+ + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/module-gcloud.html b/docs/module-gcloud.html new file mode 100644 index 00000000000..a8a94255763 --- /dev/null +++ b/docs/module-gcloud.html @@ -0,0 +1,391 @@ + + + + + JSDoc: Module: gcloud + + + + + + + + + + +
+ +

Module: gcloud

+ + + + + +
+ +
+

+ gcloud +

+ +
+ +
+
+ + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + +

Members

+ +
+ +
+

(static) datastore :module:datastore

+ + +
+
+ +
+

Google Cloud Datastore is a +fully managed, schemaless database for storing non-relational data. Use this +object to create a Dataset to interact with your data, an "Int", and a +"Double" representation.

+
+ + + +
Type:
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var datastore = gcloud.datastore;
+
+// datastore:
+// {
+//   Dataset: function() {},
+//   double: function() {},
+//   int: function() {}
+// }
+ + +
+ + + +
+

(static) pubsub :module:pubsub

+ + +
+
+ +
+

Experimental

+

Google Cloud Pub/Sub +is a reliable, many-to-many, asynchronous messaging service from Google Cloud +Platform.

+

Note: Google Cloud Pub/Sub API is available as a Limited Preview and the +client library we provide is currently experimental. The API and/or the +client might be changed in backward-incompatible ways. This API is not +subject to any SLA or deprecation policy. Request to be whitelisted to use it +by filling the +Limited Preview application form.

+
+ + + +
Type:
+
    +
  • + +module:pubsub + + +
    • +
+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var pubsub = gcloud.pubsub;
+
+var conn = new pubsub.Connection({
+  projectId: YOUR_PROJECT_ID,
+  keyFilename: '/path/to/the/key.json'
+});
+ + +
+ + + +
+

(static) storage :module:storage

+ + +
+
+ +
+

Google Cloud Storage allows you to store data on Google infrastructure. Read +Google Cloud Storage API docs +for more information.

+

You need to create a Google Cloud Storage bucket to use this client library. +Follow the steps on +Google Cloud Storage docs to +create a bucket.

+
+ + + +
Type:
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + +
See:
+
+ +
+ + + +
+ + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var storage = gcloud.storage;
+
+// storage:
+// {
+//   Bucket: function() {}
+// }
+ + +
+ +
+ + + + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/module-storage.html b/docs/module-storage.html new file mode 100644 index 00000000000..20b9743fc01 --- /dev/null +++ b/docs/module-storage.html @@ -0,0 +1,2070 @@ + + + + + JSDoc: Module: storage + + + + + + + + + + +
+ +

Module: storage

+ + + + + +
+ +
+

+ storage +

+ +
+ +
+
+ + +
+

(require("storage"))(options)

+ + +
+
+ + +
+

Google Cloud Storage allows you to store data on Google infrastructure. See +the guide on https://developers.google.com/storage to create a +bucket.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
options + + +object + + + +

Configuration options.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
bucketName + + +string + + + +

Name of the bucket.

keyFilename + + +string + + + +

Full path to the JSON key downloaded + from the Google Developers Console.

+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + +
Throws:
+ + + +
+ + if a bucket name isn't provided. + +
+ + + + + + + +
Example
+ + 
var gcloud = require('gcloud');
+var storage = gcloud.storage;
+var bucket;
+
+// From Google Compute Engine
+bucket = new storage.Bucket({
+  bucketName: YOUR_BUCKET_NAME
+});
+
+// From elsewhere
+bucket = new storage.Bucket({
+  bucketName: YOUR_BUCKET_NAME,
+  keyFilename: '/path/to/the/key.json'
+});
+ + +
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + + + +

Methods

+ +
+ +
+

copy(name, metadata, callbackopt)

+ + +
+
+ + +
+

Copy an existing file. If no bucket name is provided for the destination +file, the current bucket name will be used.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
name + + +string + + + + + + + + + +

Name of the existing file.

metadata + + +object + + + + + + + + + +

Destination file metadata object.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
name + + +string + + + + + + + + + +

Name of the destination file.

bucket + + +string + + + + + + <optional>
+ + + + + +

Destination bucket for the file. If none + is provided, the source's bucket name is used.

+
callback + + +function + + + + + + <optional>
+ + + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + +
Throws:
+ + + +
+ + if the destination filename is not provided. + +
+ + + + + + + +
Example
+ + 
bucket.copy('filename', {
+   bucket: 'destination-bucket',
+   name: 'destination-filename'
+}, function(err) {});
+ + +
+ + + +
+

createReadStream(name) → {ReadStream}

+ + +
+
+ + +
+

Create a readable stream to read contents of the provided remote file. It +can be piped to a write stream, or listened to for 'data' events to read a +file's contents.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
name + + +string + + + +

Name of the remote file.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +ReadStream + + +
+
+ + + + +
Example
+ + 
// Create a readable stream and write the file contents to "local-file-path".
+var fs = require('fs');
+
+bucket.createReadStream('remote-file-name')
+   .pipe(fs.createWriteStream('local-file-path'))
+   .on('error', function(err) {});
+ + +
+ + + +
+

createWriteStream(name, metadataopt) → {stream}

+ + +
+
+ + +
+

Create a Duplex to handle the upload of a file.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
name + + +string + + + + + + + + + +

Name of the remote file to create.

metadata + + +object + + + + + + <optional>
+ + + + + +

Optional metadata.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +stream + + +
+
+ + + + +
Example
+ + 
// Read from a local file and pipe to your bucket.
+var fs = require('fs');
+
+fs.createReadStream('local-file-path')
+    .pipe(bucket.createWriteStream('remote-file-name'))
+    .on('error', function(err) {})
+    .on('complete', function(fileObject) {});
+ + +
+ + + +
+

list(queryopt, callback)

+ + +
+
+ + +
+

List files from the current bucket.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
query + + +object + + + + + + <optional>
+ + + + + +

Query object.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
delimeter + + +string + + + +

Results will contain only objects whose + names, aside from the prefix, do not contain delimiter. Objects whose + names, aside from the prefix, contain delimiter will have their name + truncated after the delimiter, returned in prefixes. Duplicate prefixes + are omitted.

prefix + + +string + + + +

Filters results to objects whose names begin + with this prefix.

maxResults + + +number + + + +

Maximum number of items plus prefixes to + return.

pageToken + + +string + + + +

A previously-returned page token + representing part of the larger set of results to view.

+
callback + + +function + + + + + + + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
bucket.list(function(err, files, nextQuery) {
+  if (nextQuery) {
+    // nextQuery will be non-null if there are more results.
+    bucket.list(nextQuery, function(err, files, nextQuery) {});
+  }
+});
+
+// Fetch using a query.
+bucket.list({ maxResults: 5 }, function(err, files, nextQuery) {});
+ + +
+ + + +
+

makeReq(method, path, query, body, callback)

+ + +
+
+ + +
+

Make a new request object from the provided arguments and wrap the callback +to intercept non-successful responses.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
method + + +string + + + +

Action.

path + + +string + + + +

Request path.

query + + +* + + + +

Request query object.

body + + +* + + + +

Request body contents.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
+ + + +
+

remove(name, callback)

+ + +
+
+ + +
+

Remove a file.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
name + + +string + + + +

Name of the file to remove.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
bucket.remove('filename', function(err) {});
+ + +
+ + + +
+

stat(name, callback)

+ + +
+
+ + +
+

Stat a file.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
name + + +string + + + +

Name of the remote file.

callback + + +function + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
bucket.stat('filename', function(err, metadata){});
+ + +
+ + + +
+

write(name, options, callbackopt)

+ + +
+
+ + +
+

Write the provided data to the destination with optional metadata.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
name + + +string + + + + + + + + + +

Name of the remote file toc reate.

options + + +object +| + +string +| + +buffer + + + + + + + + + +

Configuration object or data.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
metadata + + +object + + + + + + <optional>
+ + + + + +

Optional metadata.

+
callback + + +function + + + + + + <optional>
+ + + + + +

The callback function.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
// Upload "Hello World" as file contents. `data` can be any string or buffer.
+bucket.write('filename', {
+  data: 'Hello World'
+}, function(err) {});
+
+// A shorthand for the above.
+bucket.write('filename', 'Hello World', function(err) {});
+ + +
+ +
+ + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/query.html b/docs/query.html new file mode 100644 index 00000000000..1546f978e50 --- /dev/null +++ b/docs/query.html @@ -0,0 +1,1640 @@ + + + + + JSDoc: Module: datastore/query + + + + + + + + + + +
+ +

Module: datastore/query

+ + + + + +
+ +
+

+ datastore/query +

+ +
+ +
+
+ + +
+

new (require("datastore/query"))(namespaceopt, kinds)

+ + +
+
+ + +
+

Build a Query object.

+

Queries should be built with +module:datastore/dataset#createQuery and run via +module:datastore/dataset#runQuery.

+

Reference: http://goo.gl/Cag0r6

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
namespace + + +string + + + + + + <optional>
+ + + + + +

Namespace to query entities from.

kinds + + +Array.<string> + + + + + + + + + +

Kinds to query.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Example
+ + 
var query;
+
+// If your dataset was scoped to a namespace at initialization, your query
+// will likewise be scoped to that namespace.
+query = dataset.createQuery(['Lion', 'Chimp']);
+
+// However, you may override the namespace per query.
+query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']);
+
+// You may also remove the namespace altogether.
+query = dataset.createQuery(null, ['Lion', 'Chimp']);
+ + +
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + +
+ + + + + + + + + + + + + + + + +

Methods

+ +
+ +
+

end(cursorToken) → {module:datastore/query}

+ + +
+
+ + +
+

Set an ending cursor to a query.

+

Reference: http://goo.gl/WuTGRI

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
cursorToken + + +string + + + +

The ending cursor token.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
var cursorToken = 'X';
+
+// Retrieve results limited to the extent of cursorToken.
+var endQuery = companyQuery.end(cursorToken);
+ + +
+ + + +
+

filter(filter, value) → {module:datastore/query}

+ + +
+
+ + +
+

Datastore allows querying on properties. Supported comparison operators +are =, <, >, <=, and >=. "Not equal" and IN operators are +currently not supported.

+

To filter by ancestors, see module:datastore/query#hasAncestor.

+

Reference: http://goo.gl/ENCx7e

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
filter + + +string + + + +

Property + Operator (=, <, >, <=, >=).

value + + +* + + + +

Value to compare property to.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
// List all companies named Google that have less than 400 employees.
+var companyQuery = query
+  .filter('name =', 'Google');
+  .filter('size <', 400);
+
+// To filter by key, use `__key__` for the property name. Filter on keys
+// stored as properties is not currently supported.
+var keyQuery = query.filter('__key__ =', datastore.key('Company', 'Google'));
+ + +
+ + + +
+

groupBy(properties) → {module:datastore/query}

+ + +
+
+ + +
+

Group query results by a list of properties.

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
properties + + +array + + + +

Properties to group by.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
var groupedQuery = companyQuery.groupBy(['name', 'size']);
+ + +
+ + + +
+

hasAncestor(key) → {module:datastore/query}

+ + +
+
+ + +
+

Filter a query by ancestors.

+

Reference: http://goo.gl/1qfpkZ

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
key + + +datastore/entity~Key + + + +

Key object to filter by.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
var ancestoryQuery = query.hasAncestor(datastore.key('Parent', 123));
+ + +
+ + + +
+

limit(n) → {module:datastore/query}

+ + +
+
+ + +
+

Set a limit on a query.

+

Reference: http://goo.gl/f0VZ0n

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
n + + +number + + + +

The number of results to limit the query to.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
// Limit the results to 10 entities.
+var limitQuery = companyQuery.limit(10);
+ + +
+ + + +
+

offset(n) → {module:datastore/query}

+ + +
+
+ + +
+

Set an offset on a query.

+

Reference: http://goo.gl/f0VZ0n

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
n + + +number + + + +

The offset to start from after the start cursor.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
// Start from the 101st result.
+var offsetQuery = companyQuery.offset(100);
+ + +
+ + + +
+

order(property) → {module:datastore/query}

+ + +
+
+ + +
+

Sort the results by a property name ascendingly or descendingly. By default, +an ascending sort order will be used.

+

Reference: http://goo.gl/mfegFR

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
property + + +string + + + +

Optional operator (+, -) and property to order by.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
// Sort by size ascendingly.
+var companiesAscending = companyQuery.order('size');
+
+// Sort by size descendingly.
+var companiesDescending = companyQuery.order('-size');
+ + +
+ + + +
+

select(fieldNames) → {module:datastore/query}

+ + +
+
+ + +
+

Retrieve only select properties from the matched entities.

+

Reference: Projection Queries

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
fieldNames + + +array + + + +

Properties to return from the matched entities.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
// Only retrieve the name and size properties.
+var selectQuery = companyQuery.select(['name', 'size']);
+ + +
+ + + +
+

start(cursorToken) → {module:datastore/query}

+ + +
+
+ + +
+

Set a starting cursor to a query.

+

Reference: http://goo.gl/WuTGRI

+
+ + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
cursorToken + + +string + + + +

The starting cursor token.

+ + + +
+ + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Returns:
+ + + + +
+
+ Type +
+
+ +module:datastore/query + + +
+
+ + + + +
Example
+ + 
var cursorToken = 'X';
+
+// Retrieve results starting from cursorToken.
+var startQuery = companyQuery.start(cursorToken);
+ + +
+ +
+ + + + + +
+ +
+ + + + +
+ + + +
+ + + + + + + \ No newline at end of file diff --git a/docs/query.js.html b/docs/query.js.html new file mode 100644 index 00000000000..31bc107f481 --- /dev/null +++ b/docs/query.js.html @@ -0,0 +1,313 @@ + + + + + JSDoc: Source: datastore/query.js + + + + + + + + + + +
+ +

Source: datastore/query.js

+ + + + + +
+
+ 
/**
+ * Copyright 2014 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.
+ */
+
+/**
+ * @module datastore/query
+ */
+
+'use strict';
+
+var util = require('../common/util.js');
+
+/**
+ * Build a Query object.
+ *
+ * **Queries should be built with
+ * {@linkcode module:datastore/dataset#createQuery} and run via
+ * {@linkcode module:datastore/dataset#runQuery}.**
+ *
+ * *Reference: {@link http://goo.gl/Cag0r6}*
+ *
+ * @constructor
+ * @alias module:datastore/query
+ *
+ * @param {string=} namespace - Namespace to query entities from.
+ * @param {string[]} kinds - Kinds to query.
+ *
+ * @example
+ * var query;
+ *
+ * // If your dataset was scoped to a namespace at initialization, your query
+ * // will likewise be scoped to that namespace.
+ * query = dataset.createQuery(['Lion', 'Chimp']);
+ *
+ * // However, you may override the namespace per query.
+ * query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']);
+ *
+ * // You may also remove the namespace altogether.
+ * query = dataset.createQuery(null, ['Lion', 'Chimp']);
+ */
+function Query(namespace, kinds) {
+  if (!kinds) {
+    kinds = namespace;
+    namespace = null;
+  }
+
+  this.namespace = namespace || null;
+  this.kinds = kinds;
+
+  this.filters = [];
+  this.orders = [];
+  this.groupByVal = [];
+  this.selectVal = [];
+
+  // pagination
+  this.startVal = null;
+  this.endVal = null;
+  this.limitVal = -1;
+  this.offsetVal = -1;
+}
+
+/**
+ * Datastore allows querying on properties. Supported comparison operators
+ * are `=`, `<`, `>`, `<=`, and `>=`. "Not equal" and `IN` operators are
+ * currently not supported.
+ *
+ * *To filter by ancestors, see {@linkcode module:datastore/query#hasAncestor}.*
+ *
+ * *Reference: {@link http://goo.gl/ENCx7e}*
+ *
+ * @param {string} filter - Property + Operator (=, <, >, <=, >=).
+ * @param {*} value - Value to compare property to.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * // List all companies named Google that have less than 400 employees.
+ * var companyQuery = query
+ *   .filter('name =', 'Google');
+ *   .filter('size <', 400);
+ *
+ * // To filter by key, use `__key__` for the property name. Filter on keys
+ * // stored as properties is not currently supported.
+ * var keyQuery = query.filter('__key__ =', datastore.key('Company', 'Google'));
+ */
+Query.prototype.filter = function(filter, value) {
+  // TODO: Add filter validation.
+  var q = util.extend(this, new Query());
+  filter = filter.trim();
+  var fieldName = filter.replace(/[>|<|=|>=|<=]*$/, '').trim();
+  var op = filter.substr(fieldName.length, filter.length).trim();
+  q.filters = q.filters || [];
+  q.filters.push({ name: fieldName, op: op, val: value });
+  return q;
+};
+
+/**
+ * Filter a query by ancestors.
+ *
+ * *Reference: {@link http://goo.gl/1qfpkZ}*
+ *
+ * @param {datastore/entity~Key} key - Key object to filter by.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * var ancestoryQuery = query.hasAncestor(datastore.key('Parent', 123));
+ */
+Query.prototype.hasAncestor = function(key) {
+  var q = util.extend(this, new Query());
+  this.filters.push({ name: '__key__', op: 'HAS_ANCESTOR', val: key });
+  return q;
+};
+
+/**
+ * Sort the results by a property name ascendingly or descendingly. By default,
+ * an ascending sort order will be used.
+ *
+ * *Reference: {@link http://goo.gl/mfegFR}*
+ *
+ * @param {string} property - Optional operator (+, -) and property to order by.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * // Sort by size ascendingly.
+ * var companiesAscending = companyQuery.order('size');
+ *
+ * // Sort by size descendingly.
+ * var companiesDescending = companyQuery.order('-size');
+ */
+Query.prototype.order = function(property) {
+  var q = util.extend(this, new Query());
+  var sign = '+';
+  if (property[0] === '-' || property[0] === '+') {
+    sign = property[0];
+    property = property.substr(1);
+  }
+  q.orders = q.orders || [];
+  q.orders.push({ name: property, sign: sign });
+  return q;
+};
+
+/**
+ * Group query results by a list of properties.
+ *
+ * @param {array} properties - Properties to group by.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * var groupedQuery = companyQuery.groupBy(['name', 'size']);
+ */
+Query.prototype.groupBy = function(fieldNames) {
+  var fields = util.arrayize(fieldNames);
+  var q = util.extend(this, new Query());
+  q.groupByVal = fields;
+  return q;
+};
+
+/**
+ * Retrieve only select properties from the matched entities.
+ *
+ * *Reference: [Projection Queries]{@link http://goo.gl/EfsrJl}*
+ *
+ * @param {array} fieldNames - Properties to return from the matched entities.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * // Only retrieve the name and size properties.
+ * var selectQuery = companyQuery.select(['name', 'size']);
+ */
+Query.prototype.select = function(fieldNames) {
+  var q = util.extend(this, new Query());
+  q.selectVal = fieldNames;
+  return q;
+};
+
+/**
+ * Set a starting cursor to a query.
+ *
+ * *Reference: {@link http://goo.gl/WuTGRI}*
+ *
+ * @param {string} cursorToken - The starting cursor token.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * var cursorToken = 'X';
+ *
+ * // Retrieve results starting from cursorToken.
+ * var startQuery = companyQuery.start(cursorToken);
+ */
+Query.prototype.start = function(start) {
+  var q = util.extend(this, new Query());
+  q.startVal = start;
+  return q;
+};
+
+/**
+ * Set an ending cursor to a query.
+ *
+ * *Reference: {@link http://goo.gl/WuTGRI}*
+ *
+ * @param {string} cursorToken - The ending cursor token.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * var cursorToken = 'X';
+ *
+ * // Retrieve results limited to the extent of cursorToken.
+ * var endQuery = companyQuery.end(cursorToken);
+ */
+Query.prototype.end = function(end) {
+  var q = util.extend(this, new Query());
+  q.endVal = end;
+  return q;
+};
+
+/**
+ * Set a limit on a query.
+ *
+ * *Reference: {@link http://goo.gl/f0VZ0n}*
+ *
+ * @param {number} n - The number of results to limit the query to.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * // Limit the results to 10 entities.
+ * var limitQuery = companyQuery.limit(10);
+ */
+Query.prototype.limit = function(n) {
+  var q = util.extend(this, new Query());
+  q.limitVal = n;
+  return q;
+};
+
+/**
+ * Set an offset on a query.
+ *
+ * *Reference: {@link http://goo.gl/f0VZ0n}*
+ *
+ * @param {number} n - The offset to start from after the start cursor.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * // Start from the 101st result.
+ * var offsetQuery = companyQuery.offset(100);
+ */
+Query.prototype.offset = function(n) {
+  var q = util.extend(this, new Query());
+  q.offsetVal = n;
+  return q;
+};
+
+module.exports = Query;
+
+
+
+ + + + +
+ + + +
+ + + + + + + diff --git a/docs/scripts/linenumber.js b/docs/scripts/linenumber.js new file mode 100644 index 00000000000..8d52f7eafdb --- /dev/null +++ b/docs/scripts/linenumber.js @@ -0,0 +1,25 @@ +/*global document */ +(function() { + var source = document.getElementsByClassName('prettyprint source linenums'); + var i = 0; + var lineNumber = 0; + var lineId; + var lines; + var totalLines; + var anchorHash; + + if (source && source[0]) { + anchorHash = document.location.hash.substring(1); + lines = source[0].getElementsByTagName('li'); + totalLines = lines.length; + + for (; i < totalLines; i++) { + lineNumber++; + lineId = 'line' + lineNumber; + lines[i].id = lineId; + if (lineId === anchorHash) { + lines[i].className += ' selected'; + } + } + } +})(); diff --git a/docs/scripts/prettify/Apache-License-2.0.txt b/docs/scripts/prettify/Apache-License-2.0.txt new file mode 100644 index 00000000000..d6456956733 --- /dev/null +++ b/docs/scripts/prettify/Apache-License-2.0.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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. diff --git a/docs/scripts/prettify/lang-css.js b/docs/scripts/prettify/lang-css.js new file mode 100644 index 00000000000..041e1f59067 --- /dev/null +++ b/docs/scripts/prettify/lang-css.js @@ -0,0 +1,2 @@ +PR.registerLangHandler(PR.createSimpleLexer([["pln",/^[\t\n\f\r ]+/,null," \t\r\n "]],[["str",/^"(?:[^\n\f\r"\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*"/,null],["str",/^'(?:[^\n\f\r'\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*'/,null],["lang-css-str",/^url\(([^"')]*)\)/i],["kwd",/^(?:url|rgb|!important|@import|@page|@media|@charset|inherit)(?=[^\w-]|$)/i,null],["lang-css-kw",/^(-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*)\s*:/i],["com",/^\/\*[^*]*\*+(?:[^*/][^*]*\*+)*\//],["com", +/^(?:<\!--|--\>)/],["lit",/^(?:\d+|\d*\.\d+)(?:%|[a-z]+)?/i],["lit",/^#[\da-f]{3,6}/i],["pln",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i],["pun",/^[^\s\w"']+/]]),["css"]);PR.registerLangHandler(PR.createSimpleLexer([],[["kwd",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i]]),["css-kw"]);PR.registerLangHandler(PR.createSimpleLexer([],[["str",/^[^"')]+/]]),["css-str"]); diff --git a/docs/scripts/prettify/prettify.js b/docs/scripts/prettify/prettify.js new file mode 100644 index 00000000000..eef5ad7e6a0 --- /dev/null +++ b/docs/scripts/prettify/prettify.js @@ -0,0 +1,28 @@ +var q=null;window.PR_SHOULD_USE_CONTINUATION=!0; +(function(){function L(a){function m(a){var f=a.charCodeAt(0);if(f!==92)return f;var b=a.charAt(1);return(f=r[b])?f:"0"<=b&&b<="7"?parseInt(a.substring(1),8):b==="u"||b==="x"?parseInt(a.substring(2),16):a.charCodeAt(1)}function e(a){if(a<32)return(a<16?"\\x0":"\\x")+a.toString(16);a=String.fromCharCode(a);if(a==="\\"||a==="-"||a==="["||a==="]")a="\\"+a;return a}function h(a){for(var f=a.substring(1,a.length-1).match(/\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\[0-3][0-7]{0,2}|\\[0-7]{1,2}|\\[\S\s]|[^\\]/g),a= +[],b=[],o=f[0]==="^",c=o?1:0,i=f.length;c122||(d<65||j>90||b.push([Math.max(65,j)|32,Math.min(d,90)|32]),d<97||j>122||b.push([Math.max(97,j)&-33,Math.min(d,122)&-33]))}}b.sort(function(a,f){return a[0]-f[0]||f[1]-a[1]});f=[];j=[NaN,NaN];for(c=0;ci[0]&&(i[1]+1>i[0]&&b.push("-"),b.push(e(i[1])));b.push("]");return b.join("")}function y(a){for(var f=a.source.match(/\[(?:[^\\\]]|\\[\S\s])*]|\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\\d+|\\[^\dux]|\(\?[!:=]|[()^]|[^()[\\^]+/g),b=f.length,d=[],c=0,i=0;c=2&&a==="["?f[c]=h(j):a!=="\\"&&(f[c]=j.replace(/[A-Za-z]/g,function(a){a=a.charCodeAt(0);return"["+String.fromCharCode(a&-33,a|32)+"]"}));return f.join("")}for(var t=0,s=!1,l=!1,p=0,d=a.length;p=5&&"lang-"===b.substring(0,5))&&!(o&&typeof o[1]==="string"))c=!1,b="src";c||(r[f]=b)}i=d;d+=f.length;if(c){c=o[1];var j=f.indexOf(c),k=j+c.length;o[2]&&(k=f.length-o[2].length,j=k-c.length);b=b.substring(5);B(l+i,f.substring(0,j),e,p);B(l+i+j,c,C(b,c),p);B(l+i+k,f.substring(k),e,p)}else p.push(l+i,b)}a.e=p}var h={},y;(function(){for(var e=a.concat(m), +l=[],p={},d=0,g=e.length;d=0;)h[n.charAt(k)]=r;r=r[1];n=""+r;p.hasOwnProperty(n)||(l.push(r),p[n]=q)}l.push(/[\S\s]/);y=L(l)})();var t=m.length;return e}function u(a){var m=[],e=[];a.tripleQuotedStrings?m.push(["str",/^(?:'''(?:[^'\\]|\\[\S\s]|''?(?=[^']))*(?:'''|$)|"""(?:[^"\\]|\\[\S\s]|""?(?=[^"]))*(?:"""|$)|'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$))/,q,"'\""]):a.multiLineStrings?m.push(["str",/^(?:'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$)|`(?:[^\\`]|\\[\S\s])*(?:`|$))/, +q,"'\"`"]):m.push(["str",/^(?:'(?:[^\n\r'\\]|\\.)*(?:'|$)|"(?:[^\n\r"\\]|\\.)*(?:"|$))/,q,"\"'"]);a.verbatimStrings&&e.push(["str",/^@"(?:[^"]|"")*(?:"|$)/,q]);var h=a.hashComments;h&&(a.cStyleComments?(h>1?m.push(["com",/^#(?:##(?:[^#]|#(?!##))*(?:###|$)|.*)/,q,"#"]):m.push(["com",/^#(?:(?:define|elif|else|endif|error|ifdef|include|ifndef|line|pragma|undef|warning)\b|[^\n\r]*)/,q,"#"]),e.push(["str",/^<(?:(?:(?:\.\.\/)*|\/?)(?:[\w-]+(?:\/[\w-]+)+)?[\w-]+\.h|[a-z]\w*)>/,q])):m.push(["com",/^#[^\n\r]*/, +q,"#"]));a.cStyleComments&&(e.push(["com",/^\/\/[^\n\r]*/,q]),e.push(["com",/^\/\*[\S\s]*?(?:\*\/|$)/,q]));a.regexLiterals&&e.push(["lang-regex",/^(?:^^\.?|[!+-]|!=|!==|#|%|%=|&|&&|&&=|&=|\(|\*|\*=|\+=|,|-=|->|\/|\/=|:|::|;|<|<<|<<=|<=|=|==|===|>|>=|>>|>>=|>>>|>>>=|[?@[^]|\^=|\^\^|\^\^=|{|\||\|=|\|\||\|\|=|~|break|case|continue|delete|do|else|finally|instanceof|return|throw|try|typeof)\s*(\/(?=[^*/])(?:[^/[\\]|\\[\S\s]|\[(?:[^\\\]]|\\[\S\s])*(?:]|$))+\/)/]);(h=a.types)&&e.push(["typ",h]);a=(""+a.keywords).replace(/^ | $/g, +"");a.length&&e.push(["kwd",RegExp("^(?:"+a.replace(/[\s,]+/g,"|")+")\\b"),q]);m.push(["pln",/^\s+/,q," \r\n\t\xa0"]);e.push(["lit",/^@[$_a-z][\w$@]*/i,q],["typ",/^(?:[@_]?[A-Z]+[a-z][\w$@]*|\w+_t\b)/,q],["pln",/^[$_a-z][\w$@]*/i,q],["lit",/^(?:0x[\da-f]+|(?:\d(?:_\d+)*\d*(?:\.\d*)?|\.\d\+)(?:e[+-]?\d+)?)[a-z]*/i,q,"0123456789"],["pln",/^\\[\S\s]?/,q],["pun",/^.[^\s\w"-$'./@\\`]*/,q]);return x(m,e)}function D(a,m){function e(a){switch(a.nodeType){case 1:if(k.test(a.className))break;if("BR"===a.nodeName)h(a), +a.parentNode&&a.parentNode.removeChild(a);else for(a=a.firstChild;a;a=a.nextSibling)e(a);break;case 3:case 4:if(p){var b=a.nodeValue,d=b.match(t);if(d){var c=b.substring(0,d.index);a.nodeValue=c;(b=b.substring(d.index+d[0].length))&&a.parentNode.insertBefore(s.createTextNode(b),a.nextSibling);h(a);c||a.parentNode.removeChild(a)}}}}function h(a){function b(a,d){var e=d?a.cloneNode(!1):a,f=a.parentNode;if(f){var f=b(f,1),g=a.nextSibling;f.appendChild(e);for(var h=g;h;h=g)g=h.nextSibling,f.appendChild(h)}return e} +for(;!a.nextSibling;)if(a=a.parentNode,!a)return;for(var a=b(a.nextSibling,0),e;(e=a.parentNode)&&e.nodeType===1;)a=e;d.push(a)}var k=/(?:^|\s)nocode(?:\s|$)/,t=/\r\n?|\n/,s=a.ownerDocument,l;a.currentStyle?l=a.currentStyle.whiteSpace:window.getComputedStyle&&(l=s.defaultView.getComputedStyle(a,q).getPropertyValue("white-space"));var p=l&&"pre"===l.substring(0,3);for(l=s.createElement("LI");a.firstChild;)l.appendChild(a.firstChild);for(var d=[l],g=0;g=0;){var h=m[e];A.hasOwnProperty(h)?window.console&&console.warn("cannot override language handler %s",h):A[h]=a}}function C(a,m){if(!a||!A.hasOwnProperty(a))a=/^\s*=o&&(h+=2);e>=c&&(a+=2)}}catch(w){"console"in window&&console.log(w&&w.stack?w.stack:w)}}var v=["break,continue,do,else,for,if,return,while"],w=[[v,"auto,case,char,const,default,double,enum,extern,float,goto,int,long,register,short,signed,sizeof,static,struct,switch,typedef,union,unsigned,void,volatile"], +"catch,class,delete,false,import,new,operator,private,protected,public,this,throw,true,try,typeof"],F=[w,"alignof,align_union,asm,axiom,bool,concept,concept_map,const_cast,constexpr,decltype,dynamic_cast,explicit,export,friend,inline,late_check,mutable,namespace,nullptr,reinterpret_cast,static_assert,static_cast,template,typeid,typename,using,virtual,where"],G=[w,"abstract,boolean,byte,extends,final,finally,implements,import,instanceof,null,native,package,strictfp,super,synchronized,throws,transient"], +H=[G,"as,base,by,checked,decimal,delegate,descending,dynamic,event,fixed,foreach,from,group,implicit,in,interface,internal,into,is,lock,object,out,override,orderby,params,partial,readonly,ref,sbyte,sealed,stackalloc,string,select,uint,ulong,unchecked,unsafe,ushort,var"],w=[w,"debugger,eval,export,function,get,null,set,undefined,var,with,Infinity,NaN"],I=[v,"and,as,assert,class,def,del,elif,except,exec,finally,from,global,import,in,is,lambda,nonlocal,not,or,pass,print,raise,try,with,yield,False,True,None"], +J=[v,"alias,and,begin,case,class,def,defined,elsif,end,ensure,false,in,module,next,nil,not,or,redo,rescue,retry,self,super,then,true,undef,unless,until,when,yield,BEGIN,END"],v=[v,"case,done,elif,esac,eval,fi,function,in,local,set,then,until"],K=/^(DIR|FILE|vector|(de|priority_)?queue|list|stack|(const_)?iterator|(multi)?(set|map)|bitset|u?(int|float)\d*)/,N=/\S/,O=u({keywords:[F,H,w,"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END"+ +I,J,v],hashComments:!0,cStyleComments:!0,multiLineStrings:!0,regexLiterals:!0}),A={};k(O,["default-code"]);k(x([],[["pln",/^[^]*(?:>|$)/],["com",/^<\!--[\S\s]*?(?:--\>|$)/],["lang-",/^<\?([\S\s]+?)(?:\?>|$)/],["lang-",/^<%([\S\s]+?)(?:%>|$)/],["pun",/^(?:<[%?]|[%?]>)/],["lang-",/^]*>([\S\s]+?)<\/xmp\b[^>]*>/i],["lang-js",/^]*>([\S\s]*?)(<\/script\b[^>]*>)/i],["lang-css",/^]*>([\S\s]*?)(<\/style\b[^>]*>)/i],["lang-in.tag",/^(<\/?[a-z][^<>]*>)/i]]), +["default-markup","htm","html","mxml","xhtml","xml","xsl"]);k(x([["pln",/^\s+/,q," \t\r\n"],["atv",/^(?:"[^"]*"?|'[^']*'?)/,q,"\"'"]],[["tag",/^^<\/?[a-z](?:[\w-.:]*\w)?|\/?>$/i],["atn",/^(?!style[\s=]|on)[a-z](?:[\w:-]*\w)?/i],["lang-uq.val",/^=\s*([^\s"'>]*(?:[^\s"'/>]|\/(?=\s)))/],["pun",/^[/<->]+/],["lang-js",/^on\w+\s*=\s*"([^"]+)"/i],["lang-js",/^on\w+\s*=\s*'([^']+)'/i],["lang-js",/^on\w+\s*=\s*([^\s"'>]+)/i],["lang-css",/^style\s*=\s*"([^"]+)"/i],["lang-css",/^style\s*=\s*'([^']+)'/i],["lang-css", +/^style\s*=\s*([^\s"'>]+)/i]]),["in.tag"]);k(x([],[["atv",/^[\S\s]+/]]),["uq.val"]);k(u({keywords:F,hashComments:!0,cStyleComments:!0,types:K}),["c","cc","cpp","cxx","cyc","m"]);k(u({keywords:"null,true,false"}),["json"]);k(u({keywords:H,hashComments:!0,cStyleComments:!0,verbatimStrings:!0,types:K}),["cs"]);k(u({keywords:G,cStyleComments:!0}),["java"]);k(u({keywords:v,hashComments:!0,multiLineStrings:!0}),["bsh","csh","sh"]);k(u({keywords:I,hashComments:!0,multiLineStrings:!0,tripleQuotedStrings:!0}), +["cv","py"]);k(u({keywords:"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END",hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["perl","pl","pm"]);k(u({keywords:J,hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["rb"]);k(u({keywords:w,cStyleComments:!0,regexLiterals:!0}),["js"]);k(u({keywords:"all,and,by,catch,class,else,extends,false,finally,for,if,in,is,isnt,loop,new,no,not,null,of,off,on,or,return,super,then,true,try,unless,until,when,while,yes", +hashComments:3,cStyleComments:!0,multilineStrings:!0,tripleQuotedStrings:!0,regexLiterals:!0}),["coffee"]);k(x([],[["str",/^[\S\s]+/]]),["regex"]);window.prettyPrintOne=function(a,m,e){var h=document.createElement("PRE");h.innerHTML=a;e&&D(h,e);E({g:m,i:e,h:h});return h.innerHTML};window.prettyPrint=function(a){function m(){for(var e=window.PR_SHOULD_USE_CONTINUATION?l.now()+250:Infinity;p=0){var k=k.match(g),f,b;if(b= +!k){b=n;for(var o=void 0,c=b.firstChild;c;c=c.nextSibling)var i=c.nodeType,o=i===1?o?b:c:i===3?N.test(c.nodeValue)?b:o:o;b=(f=o===b?void 0:o)&&"CODE"===f.tagName}b&&(k=f.className.match(g));k&&(k=k[1]);b=!1;for(o=n.parentNode;o;o=o.parentNode)if((o.tagName==="pre"||o.tagName==="code"||o.tagName==="xmp")&&o.className&&o.className.indexOf("prettyprint")>=0){b=!0;break}b||((b=(b=n.className.match(/\blinenums\b(?::(\d+))?/))?b[1]&&b[1].length?+b[1]:!0:!1)&&D(n,b),d={g:k,h:n,i:b},E(d))}}p p:first-child +{ + margin-top: 0; + padding-top: 0; +} + +.params td.description > p:last-child +{ + margin-bottom: 0; + padding-bottom: 0; +} + +.disabled { + color: #454545; +} diff --git a/docs/styles/prettify-jsdoc.css b/docs/styles/prettify-jsdoc.css new file mode 100644 index 00000000000..5a2526e3748 --- /dev/null +++ b/docs/styles/prettify-jsdoc.css @@ -0,0 +1,111 @@ +/* JSDoc prettify.js theme */ + +/* plain text */ +.pln { + color: #000000; + font-weight: normal; + font-style: normal; +} + +/* string content */ +.str { + color: #006400; + font-weight: normal; + font-style: normal; +} + +/* a keyword */ +.kwd { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* a comment */ +.com { + font-weight: normal; + font-style: italic; +} + +/* a type name */ +.typ { + color: #000000; + font-weight: normal; + font-style: normal; +} + +/* a literal value */ +.lit { + color: #006400; + font-weight: normal; + font-style: normal; +} + +/* punctuation */ +.pun { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* lisp open bracket */ +.opn { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* lisp close bracket */ +.clo { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* a markup tag name */ +.tag { + color: #006400; + font-weight: normal; + font-style: normal; +} + +/* a markup attribute name */ +.atn { + color: #006400; + font-weight: normal; + font-style: normal; +} + +/* a markup attribute value */ +.atv { + color: #006400; + font-weight: normal; + font-style: normal; +} + +/* a declaration */ +.dec { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* a variable name */ +.var { + color: #000000; + font-weight: normal; + font-style: normal; +} + +/* a function name */ +.fun { + color: #000000; + font-weight: bold; + font-style: normal; +} + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { + margin-top: 0; + margin-bottom: 0; +} diff --git a/docs/styles/prettify-tomorrow.css b/docs/styles/prettify-tomorrow.css new file mode 100644 index 00000000000..aa2908c251e --- /dev/null +++ b/docs/styles/prettify-tomorrow.css @@ -0,0 +1,132 @@ +/* Tomorrow Theme */ +/* Original theme - https://github.com/chriskempson/tomorrow-theme */ +/* Pretty printing styles. Used with prettify.js. */ +/* SPAN elements with the classes below are added by prettyprint. */ +/* plain text */ +.pln { + color: #4d4d4c; } + +@media screen { + /* string content */ + .str { + color: #718c00; } + + /* a keyword */ + .kwd { + color: #8959a8; } + + /* a comment */ + .com { + color: #8e908c; } + + /* a type name */ + .typ { + color: #4271ae; } + + /* a literal value */ + .lit { + color: #f5871f; } + + /* punctuation */ + .pun { + color: #4d4d4c; } + + /* lisp open bracket */ + .opn { + color: #4d4d4c; } + + /* lisp close bracket */ + .clo { + color: #4d4d4c; } + + /* a markup tag name */ + .tag { + color: #c82829; } + + /* a markup attribute name */ + .atn { + color: #f5871f; } + + /* a markup attribute value */ + .atv { + color: #3e999f; } + + /* a declaration */ + .dec { + color: #f5871f; } + + /* a variable name */ + .var { + color: #c82829; } + + /* a function name */ + .fun { + color: #4271ae; } } +/* Use higher contrast and text-weight for printable form. */ +@media print, projection { + .str { + color: #060; } + + .kwd { + color: #006; + font-weight: bold; } + + .com { + color: #600; + font-style: italic; } + + .typ { + color: #404; + font-weight: bold; } + + .lit { + color: #044; } + + .pun, .opn, .clo { + color: #440; } + + .tag { + color: #006; + font-weight: bold; } + + .atn { + color: #404; } + + .atv { + color: #060; } } +/* Style */ +/* +pre.prettyprint { + background: white; + font-family: Menlo, Monaco, Consolas, monospace; + font-size: 12px; + line-height: 1.5; + border: 1px solid #ccc; + padding: 10px; } +*/ + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { + margin-top: 0; + margin-bottom: 0; } + +/* IE indents via margin-left */ +li.L0, +li.L1, +li.L2, +li.L3, +li.L4, +li.L5, +li.L6, +li.L7, +li.L8, +li.L9 { + /* */ } + +/* Alternate shading for lines */ +li.L1, +li.L3, +li.L5, +li.L7, +li.L9 { + /* */ } diff --git a/lib/common/connection.js b/lib/common/connection.js index ce229a323e4..53680871532 100644 --- a/lib/common/connection.js +++ b/lib/common/connection.js @@ -15,6 +15,7 @@ */ /** + * @private * @module common/connection */ @@ -46,9 +47,7 @@ var USER_AGENT = 'gcloud-node/' + PKG.version; * @param {date} expiry - Expiration datetime. * * @example - * ```js * var token = new Token(ACCESS_TOKEN, EXPIRY); - * ``` */ function Token(accessToken, expiry) { this.accessToken = accessToken; @@ -61,9 +60,7 @@ function Token(accessToken, expiry) { * @return {boolean} * * @example - * ```js * token.isExpired(); - * ``` */ Token.prototype.isExpired = function() { if (!this.accessToken || !this.expiry) { @@ -81,13 +78,11 @@ module.exports.Token = Token; * @param {array} opts.scopes - Scopes required for access. * * @example - * ```js * var SCOPES = [ * 'https://www.googleapis.com/auth/datastore', * 'https://www.googleapis.com/auth/userinfo.email' * ]; * var conn = new Connection({ scopes: SCOPES }); - * ``` */ function Connection(opts) { this.opts = opts || {}; @@ -109,9 +104,7 @@ function Connection(opts) { * @param {function} callback - The callback function. * * @example - * ```js * conn.connect(function(err) {}); - * ``` */ Connection.prototype.connect = function(callback) { var that = this; @@ -132,9 +125,7 @@ Connection.prototype.connect = function(callback) { * @param {function} callback - The callback function. * * @example - * ```js * conn.fetchToken(function(err) {}); - * ``` */ Connection.prototype.fetchToken = function(callback) { var that = this; @@ -174,14 +165,10 @@ Connection.prototype.fetchToken = function(callback) { /** * Fetch a service account token. * - * @private - * * @param {function} callback - The callback function. * * @example - * ```js * conn.fetchServiceAccountToken_(function(err) {}); - * ``` */ Connection.prototype.fetchServiceAccountToken_ = function(callback) { var gapi = new GAPIToken({ @@ -210,9 +197,7 @@ Connection.prototype.fetchServiceAccountToken_ = function(callback) { * @param {function=} callback - The callback function. * * @example - * ```js * conn.req({}, function(err) {}); - * ``` */ Connection.prototype.req = function(requestOptions, callback) { var that = this; @@ -233,9 +218,7 @@ Connection.prototype.req = function(requestOptions, callback) { * @param {function} callback - The callback function. * * @example - * ```js * conn.createAuthorizedReq({}, function(err) {}); - * ``` */ Connection.prototype.createAuthorizedReq = function(reqOpts, callback) { var that = this; @@ -287,9 +270,7 @@ Connection.prototype.requester = req; * @return {boolean} * * @example - * ```js * conn.isConnected(); - * ``` */ Connection.prototype.isConnected = function() { return this.token && !this.token.isExpired(); diff --git a/lib/common/util.js b/lib/common/util.js index 4dd479bacde..994aae3bf92 100644 --- a/lib/common/util.js +++ b/lib/common/util.js @@ -17,6 +17,7 @@ /*jshint strict:false, noarg:false */ /** + * @private * @module common/util */ @@ -58,13 +59,11 @@ module.exports.extend = extend; * @return {array} * * @example - * ```js * arrayize(2); * // [ 2 ] * * arrayize(['Hi']); * // [ 'Hi' ] - * ``` */ function arrayize(input) { if (!Array.isArray(input)) { @@ -83,13 +82,11 @@ module.exports.arrayize = arrayize; * @return {string} * * @example - * ```js * format('This is a {language} ({abbr}) codebase.', { * language: 'JavaScript', * abbr: 'JS' * }); * // 'This is a JavaScript (JS) codebase.' - * ``` */ function format(template, args) { return template.replace(/{([^}]*)}/g, function(match, key) { @@ -103,11 +100,9 @@ module.exports.format = format; * No op. * * @example - * ```js * function doSomething(callback) { * callback = callback || noop; * } - * ``` */ function noop() {} @@ -118,8 +113,6 @@ module.exports.noop = noop; * * @constructor * - * @private - * * @param {object} errorBody - Error object. */ function ApiError(errorBody) { @@ -167,8 +160,6 @@ module.exports.handleResp = handleResp; /** * Get the type of a value. * - * @private - * * @return {string} */ function getType(value) { @@ -183,10 +174,8 @@ function getType(value) { * @return {boolean} * * @example - * ```js * is([1, 2, 3], 'array'); * // true - * ``` */ function is(value, type) { return getType(value).toLowerCase() === type.toLowerCase(); @@ -201,14 +190,12 @@ module.exports.is = is; * @return {array} * * @example - * ```js * function aFunction() { * return toArray(arguments); * } * * aFunction(1, 2, 3); * // [1, 2, 3] - * ``` */ function toArray(object) { return [].slice.call(object); diff --git a/lib/datastore/dataset.js b/lib/datastore/dataset.js index 926fd95ed0f..b53ea8122e8 100644 --- a/lib/datastore/dataset.js +++ b/lib/datastore/dataset.js @@ -20,26 +20,45 @@ 'use strict'; -/** @type module:common/connection */ +/** + * @private + * @type module:common/connection + */ var conn = require('../common/connection.js'); -/** @type module:datastore/entity */ +/** + * @private + * @type module:datastore/entity + */ var entity = require('./entity.js'); -/** @type module:datastore/pb */ +/** + * @private + * @type module:datastore/pb + */ var pb = require('./pb.js'); -/** @type module:datastore/query */ +/** + * @private + * @type module:datastore/query + */ var Query = require('./query.js'); -/** @type module:datastore/transaction */ +/** + * @private + * @type module:datastore/transaction + */ var Transaction = require('./transaction.js'); -/** @type module:common/util */ +/** + * @private + * @type module:common/util + */ var util = require('../common/util.js'); /** * Scopes for Google Datastore access. + * @private * @const {array} SCOPES */ var SCOPES = [ @@ -57,17 +76,15 @@ var SCOPES = [ * @param {object=} options * @param {string} options.projectId - Dataset ID. This is your project ID from * the Google Developers Console. - * @param {string} options.keyFileName - Full path to the JSON key downloaded + * @param {string} options.keyFilename - Full path to the JSON key downloaded * from the Google Developers Console. * @param {string} options.namespace - Namespace to isolate transactions to. * * @example - * ```js - * var dataset = new Dataset({ + * var dataset = new datastore.Dataset({ * projectId: 'my-project', - * keyFileName: '/path/to/keyfile.json' + * keyFilename: '/path/to/keyfile.json' * }); - * ``` */ function Dataset(options) { options = options || {}; @@ -87,7 +104,6 @@ function Dataset(options) { * You may also specify a configuration object to define a namespace and path. * * @example - * ```js * var key; * * // Create a key from the dataset's namespace. @@ -98,7 +114,6 @@ function Dataset(options) { * namespace: 'My-NS', * path: ['Company', 123] * }); - * ``` */ Dataset.prototype.key = function(keyConfig) { if (!util.is(keyConfig, 'object')) { @@ -115,25 +130,13 @@ Dataset.prototype.key = function(keyConfig) { * Create a query from the current dataset to query the specified kinds, scoped * to the namespace provided at the initialization of the dataset. * + * *Dataset query reference: {@link http://goo.gl/Cag0r6}* + * * @borrows {module:datastore/query} as createQuery + * @see {module:datastore/query} * * @param {string=} namespace - Optional namespace. * @param {string|array} kinds - Kinds to query. - * - * @example - * ```js - * var query; - * - * // If your dataset was scoped to a namespace at initialization, your query - * // will likewise be scoped to that namespace. - * query = dataset.createQuery(['Lion', 'Chimp']); - * - * // However, you may override the namespace per query. - * query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']); - * - * // You may also remove the namespace altogether. - * query = dataset.createQuery(null, ['Lion', 'Chimp']); - * ``` * @return {module:datastore/query} */ Dataset.prototype.createQuery = function(namespace, kinds) { @@ -145,25 +148,39 @@ Dataset.prototype.createQuery = function(namespace, kinds) { }; /** + * Retrieve the entities identified with the specified key(s) in the current + * transaction. Get operations require a valid key to retrieve the + * key-identified entity from Datastore. + * * @borrows {module:datastore/transaction#get} as get * + * @param {module:datastore/entity~Key|module:datastore/entity~Key[]} key - + * Datastore key object(s). + * @param {function} callback - The callback function. + * * @example - * ```js * dataset.get([ * datastore.key('Company', 123), * datastore.key('Product', 'Computer') * ], function(err, entities) {}); - * ``` */ Dataset.prototype.get = function(key, callback) { this.transaction.get(key, callback); }; /** + * Insert or update the specified object(s) in the current transaction. If a + * key is incomplete, its associated object is inserted and its generated + * identifier is returned to the callback. + * * @borrows {module:datastore/transaction#save} as save * + * @param {object|object[]} entities - Datastore key object(s). + * @param {Key} entities.key - Datastore key object. + * @param {object} entities.data - Data to save with the provided key. + * @param {function} callback - The callback function. + * * @example - * ```js * // Save a single entity. * dataset.save({ * key: datastore.key('Company', null), @@ -190,17 +207,21 @@ Dataset.prototype.get = function(key, callback) { * } * } * ], function(err, keys) {}); - * ``` */ Dataset.prototype.save = function(key, obj, callback) { this.transaction.save(key, obj, callback); }; /** + * Delete all entities identified with the specified key(s) in the current + * transaction. + * + * @param {Key|Key[]} key - Datastore key object(s). + * @param {function} callback - The callback function. + * * @borrows {module:datastore/transaction#delete} as delete * * @example - * ```js * // Delete a single entity. * dataset.delete(datastore.key('Company', 123), function(err) {}); * @@ -209,17 +230,23 @@ Dataset.prototype.save = function(key, obj, callback) { * datastore.key('Company', 123), * datastore.key('Product', 'Computer') * ], function(err) {}); - * ``` */ Dataset.prototype.delete = function(key, callback) { this.transaction.delete(key, callback); }; /** + * Datastore allows you to query entities by kind, filter them by property + * filters, and sort them by a property name. Projection and pagination are also + * supported. If more results are available, a query to retrieve the next page + * is provided to the callback function. + * * @borrows {module:datastore/transaction#runQuery} as runQuery * + * @param {module:datastore/query} query - Query object. + * @param {function} callback - The callback function. + * * @example - * ```js * // Retrieve 5 companies. * dataset.runQuery(queryObject, function(err, entities, nextQuery) { * // `nextQuery` is not null if there are more results. @@ -227,7 +254,6 @@ Dataset.prototype.delete = function(key, callback) { * dataset.runQuery(nextQuery, function(err, entities, nextQuery) {}); * } * }); - * ``` */ Dataset.prototype.runQuery = function(q, callback) { this.transaction.runQuery(q, callback); @@ -243,7 +269,6 @@ Dataset.prototype.runQuery = function(q, callback) { * @param {function} callback - The callback function. * * @example - * ```js * dataset.transaction(function(transaction, done) { * // From the `transaction` object, execute dataset methods as usual. * // Call `done` when you're ready to commit all of the changes. @@ -256,7 +281,6 @@ Dataset.prototype.runQuery = function(q, callback) { * done(); * }); * }, function(err) {}); - * ``` */ Dataset.prototype.runInTransaction = function(fn, callback) { var newTransaction = this.createTransaction_(); @@ -276,7 +300,6 @@ Dataset.prototype.runInTransaction = function(fn, callback) { * @param {function} callback - The callback function. * * @example - * ```js * // The following call will create 100 new IDs from the Company kind, which * // exists under the default namespace. * var incompleteKey = datastore.key('Company', null); @@ -288,7 +311,6 @@ Dataset.prototype.runInTransaction = function(fn, callback) { * // the "ns-test" namespace. * var incompleteKey = datastore.key('ns-test', 'Company', null); * dataset.allocateIds(incompleteKey, 100, function(err, keys) {}); - * ``` */ Dataset.prototype.allocateIds = function(incompleteKey, n, callback) { if (entity.isKeyComplete(incompleteKey)) { @@ -323,8 +345,4 @@ Dataset.prototype.createTransaction_ = function() { return new Transaction(this.connection, this.id); }; -/** - * Exports Dataset. - * @type {Dataset} - */ module.exports = Dataset; diff --git a/lib/datastore/entity.js b/lib/datastore/entity.js index adffa39fb5b..844c31f7859 100644 --- a/lib/datastore/entity.js +++ b/lib/datastore/entity.js @@ -15,6 +15,7 @@ */ /** + * @private * @module datastore/entity */ @@ -22,36 +23,19 @@ /** * @type {object} - * @private */ var entityMeta = {}; -/** - * Regular expression to verify a field name. - * @private - * @const {regexp} - */ +/** @const {regexp} Regular expression to verify a field name. */ var FIELD_NAME_REGEX = /^[A-Za-z]*$/; -/** - * Regular expression to verify a Kind. - * @private - * @const {regexp} - */ +/** @const {regexp} Regular expression to verify a Kind. */ var KIND_REGEX = /^[A-Za-z]*$/; -/** - * Regular Expression to verify a namespace. - * @private - * @const {regexp} - */ +/** @const {regexp} Regular Expression to verify a namespace. */ var NAMESPACE_REGEX = /^[A-Za-z]*$/; -/** - * Conversion map for query operation -> operation protocol value. - * @private - * @const {object} - */ +/** @const {object} Map for query operation -> operation protocol value. */ var OP_TO_OPERATOR = { '=': 'EQUAL', '>': 'GREATER_THAN', @@ -61,11 +45,7 @@ var OP_TO_OPERATOR = { 'HAS_ANCESTOR': 'HAS_ANCESTOR' }; -/** - * A list of native objects. - * @private - * @const {array} - */ +/** @const {array} A list of native objects. */ var PRIMITIVE_KINDS = [ Object, Boolean, @@ -75,11 +55,7 @@ var PRIMITIVE_KINDS = [ Buffer ]; -/** - * Conversion map for query sign -> order protocol value. - * @private - * @const {object} - */ +/** @const {object} Conversion map for query sign -> order protocol value. */ var SIGN_TO_ORDER = { '-': 'DESCENDING', '+': 'ASCENDING' @@ -94,9 +70,7 @@ var SIGN_TO_ORDER = { * @param {string=} options.namespace - Optional namespace. * * @example - * ```js * var key = new Key('Company', 123); - * ``` */ function Key(options) { this.namespace_ = options.namespace; @@ -112,9 +86,7 @@ module.exports.Key = Key; * @param {number} val - The integer value. * * @example - * ```js * var anInt = new Int(7); - * ``` */ function Int(val) { this.val_ = val; @@ -138,9 +110,7 @@ module.exports.Int = Int; * @param {number} val - The double value. * * @example - * ```js * var aDouble = new Double(7); - * ``` */ function Double(val) { this.val_ = val; @@ -162,13 +132,10 @@ module.exports.Double = Double; * * @todo Use registered metadata if provided. * - * @private - * * @param {object} proto - The protocol entity object to convert. * @return {object} * * @example - * ```js * var entity = entityFromEntityProto({ * properties: { * name: { @@ -181,7 +148,6 @@ module.exports.Double = Double; * // { * // name: 'Burcu Dogan' * // } - * ``` */ function entityFromEntityProto(proto) { var properties = proto.property || []; @@ -197,13 +163,10 @@ module.exports.entityFromEntityProto = entityFromEntityProto; /** * Convert a key protocol object to a Key object. * - * @private - * * @param {object} proto - The key protocol object to convert. * @return {module:datastore/entity~Key} * * @example - * ```js * var key = keyFromKeyProto({ * partitionId: { * datasetId: 'project-id', @@ -216,7 +179,6 @@ module.exports.entityFromEntityProto = entityFromEntityProto; * } * ] * }); - * ``` */ function keyFromKeyProto(proto) { var keyOptions = { @@ -237,13 +199,10 @@ module.exports.keyFromKeyProto = keyFromKeyProto; /** * Convert a Key object to a key protocol object. * - * @private - * * @param {module:datastore/entity~Key} key - The Key object to convert. * @return {object} * * @example - * ```js * var keyProto = keyToKeyProto(new Key('Company', 1)); * * // keyProto: @@ -255,7 +214,6 @@ module.exports.keyFromKeyProto = keyFromKeyProto; * // } * // ] * // } - * ``` */ function keyToKeyProto(key) { var keyPath = key.path_; @@ -292,15 +250,12 @@ module.exports.keyToKeyProto = keyToKeyProto; /** * Convert an API response array to a qualified Key and data object. * - * @private - * * @param {object[]} results - The response array. * @param {object} results.entity - An entity object. * @param {object} results.entity.key - The entity's key. * @return {object[]} * * @example - * ```js * makeReq('runQuery', {}, function(err, response) { * var entityObjects = formatArray(response.batch.entityResults); * @@ -313,7 +268,6 @@ module.exports.keyToKeyProto = keyToKeyProto; * // } * // * }); - * ``` */ function formatArray(results) { return results.map(function(result) { @@ -329,16 +283,12 @@ module.exports.formatArray = formatArray; /** * Check if a key is complete. * - * @private - * * @param {module:datastore/entity~Key} key - The Key object. * @return {boolean} * * @example - * ```js * isKeyComplete(new Key('Company', 'Google')); // true * isKeyComplete(new Key('Company', null)); // false - * ``` */ module.exports.isKeyComplete = function(key) { var proto = keyToKeyProto(key); @@ -358,13 +308,10 @@ module.exports.isKeyComplete = function(key) { * * @todo Do we need uint64s and keep Long.js support? * - * @private - * * @param {object} property - The property object to convert. * @return {*} * * @example - * ```js * propertyToValue({ * booleanValue: false * }); @@ -379,7 +326,6 @@ module.exports.isKeyComplete = function(key) { * blobValue: 'aGVsbG8=' * }); * // - * ``` */ function propertyToValue(property) { if (exists(property.integer_value)) { @@ -420,18 +366,14 @@ function propertyToValue(property) { /** * Convert any native value to a property object. * - * @private - * * @param {*} v - Original value. * @return {object} * * @example - * ```js * valueToProperty('Hi'); * // { * // stringValue: 'Hi' * // } - * ``` */ function valueToProperty(v) { var p = {}; @@ -495,13 +437,10 @@ function valueToProperty(v) { /** * Convert an entity object to an entity protocol object. * - * @private - * * @param {object} entity - The entity object to convert. * @return {object} * * @example - * ```js * entityToEntityProto({ * { * name: 'Burcu', @@ -519,7 +458,6 @@ function valueToProperty(v) { * // } * // } * // } - * ``` */ function entityToEntityProto(entity) { return { @@ -544,7 +482,6 @@ module.exports.entityToEntityProto = entityToEntityProto; * @return {object} * * @example - * ```js * queryToQueryProto({ * namespace: '', * kinds: [ @@ -569,7 +506,6 @@ module.exports.entityToEntityProto = entityToEntityProto; * // order: [], * // groupBy: [] * // } - * ``` */ function queryToQueryProto(q) { var query = {}; @@ -639,7 +575,6 @@ module.exports.queryToQueryProto = queryToQueryProto; * @param {object} fieldMeta - Metadata information about the fields. * * @example - * ```js * registerKind('namespace', 'Author', { * name: { kind: String, indexed: false }, * tags: { kind: String, multi: true }, // an array of string elements. @@ -651,7 +586,6 @@ module.exports.queryToQueryProto = queryToQueryProto; * } * } * }); - * ``` */ function registerKind(namespace, kind, fieldMeta) { // validate the input and put it to the dictionary @@ -693,8 +627,6 @@ module.exports.getKind = getKind; /** * Validate a field. * - * @private - * * @throws Throws an Error if the field doesn't validate. * * @param {string} name - Field name. @@ -703,12 +635,10 @@ module.exports.getKind = getKind; * @param {*} field.kind - Field Kind. * * @example - * ```js * validateField('title', { * kind: String * }); * // undefined (no errors thrown.) - * ``` */ function validateField(name, field) { if (!FIELD_NAME_REGEX.test(name)) { @@ -734,8 +664,6 @@ function validateField(name, field) { * @todo If protobufjs had hasFieldname support, we wouldn't need a utility. * Later address it on Protobuf.js. * - * @private - * * @param {*} value - Value. * @return {boolean} */ diff --git a/lib/datastore/index.js b/lib/datastore/index.js index d69c9e3d6bd..2fb207a0a19 100644 --- a/lib/datastore/index.js +++ b/lib/datastore/index.js @@ -20,29 +20,35 @@ 'use strict'; -/** @type module:datastore/entity */ +/** + * @private + * @type module:datastore/entity + */ var entity = require('./entity'); /** @alias module:datastore */ var datastore = {}; /** - * @borrows {module:datastore/dataset} as Dataset + * @see {module:datastore/dataset} * * @example - * ```js + * var gcloud = require('gcloud'); + * var datastore = gcloud.datastore; + * + * // Create a Dataset object. * var dataset = new datastore.Dataset(); - * ``` */ datastore.Dataset = require('./dataset'); /** - * @borrows {module:datastore/entity~Int} as int + * Helper function to get a Datastore Integer object. * * @example - * ```js - * var anInteger = dataset.int(7); - * ``` + * var gcloud = require('gcloud'); + * + * // Create an Integer. + * var sevenInteger = gcloud.datastore.int(7); */ datastore.int = function(value) { return new entity.Int(value); @@ -51,12 +57,11 @@ datastore.int = function(value) { /** * Helper function to get a Datastore Double object. * - * @borrows {module:datastore/entity~Double} as double - * * @example - * ```js - * var aDouble = dataset.double(7); - * ``` + * var gcloud = require('gcloud'); + * + * // Create a Double. + * var threeDouble = gcloud.datastore.double(3.0); */ datastore.double = function(value) { return new entity.Double(value); diff --git a/lib/datastore/pb.js b/lib/datastore/pb.js index d5c9c9d3ebb..68ae909f868 100644 --- a/lib/datastore/pb.js +++ b/lib/datastore/pb.js @@ -15,6 +15,7 @@ */ /** + * @private * @module datastore/pb */ diff --git a/lib/datastore/query.js b/lib/datastore/query.js index 35f0168c0c0..42684ea5368 100644 --- a/lib/datastore/query.js +++ b/lib/datastore/query.js @@ -23,9 +23,11 @@ var util = require('../common/util.js'); /** - * Build a Query object. Queries will generally be built with - * {@linkcode module:datastore/dataset#createQuery} and ran via - * {@linkcode module:datastore/dataset#runQuery}. + * Build a Query object. + * + * **Queries should be built with + * {@linkcode module:datastore/dataset#createQuery} and run via + * {@linkcode module:datastore/dataset#runQuery}.** * * *Reference: {@link http://goo.gl/Cag0r6}* * @@ -36,10 +38,17 @@ var util = require('../common/util.js'); * @param {string[]} kinds - Kinds to query. * * @example - * ```js - * var query = new Query(['Lion', 'Chimp']); - * var zooQuery = new Query('zoo', ['Lion', 'Chimp']); - * ``` + * var query; + * + * // If your dataset was scoped to a namespace at initialization, your query + * // will likewise be scoped to that namespace. + * query = dataset.createQuery(['Lion', 'Chimp']); + * + * // However, you may override the namespace per query. + * query = dataset.createQuery('AnimalNamespace', ['Lion', 'Chimp']); + * + * // You may also remove the namespace altogether. + * query = dataset.createQuery(null, ['Lion', 'Chimp']); */ function Query(namespace, kinds) { if (!kinds) { @@ -71,14 +80,11 @@ function Query(namespace, kinds) { * * *Reference: {@link http://goo.gl/ENCx7e}* * - * @todo Add filter validation. - * * @param {string} filter - Property + Operator (=, <, >, <=, >=). * @param {*} value - Value to compare property to. * @return {module:datastore/query} * * @example - * ```js * // List all companies named Google that have less than 400 employees. * var companyQuery = query * .filter('name =', 'Google'); @@ -87,9 +93,9 @@ function Query(namespace, kinds) { * // To filter by key, use `__key__` for the property name. Filter on keys * // stored as properties is not currently supported. * var keyQuery = query.filter('__key__ =', datastore.key('Company', 'Google')); - * ``` */ Query.prototype.filter = function(filter, value) { + // TODO: Add filter validation. var q = util.extend(this, new Query()); filter = filter.trim(); var fieldName = filter.replace(/[>|<|=|>=|<=]*$/, '').trim(); @@ -108,9 +114,7 @@ Query.prototype.filter = function(filter, value) { * @return {module:datastore/query} * * @example - * ```js * var ancestoryQuery = query.hasAncestor(datastore.key('Parent', 123)); - * ``` */ Query.prototype.hasAncestor = function(key) { var q = util.extend(this, new Query()); @@ -128,13 +132,11 @@ Query.prototype.hasAncestor = function(key) { * @return {module:datastore/query} * * @example - * ```js * // Sort by size ascendingly. * var companiesAscending = companyQuery.order('size'); * * // Sort by size descendingly. * var companiesDescending = companyQuery.order('-size'); - * ``` */ Query.prototype.order = function(property) { var q = util.extend(this, new Query()); @@ -155,9 +157,7 @@ Query.prototype.order = function(property) { * @return {module:datastore/query} * * @example - * ```js * var groupedQuery = companyQuery.groupBy(['name', 'size']); - * ``` */ Query.prototype.groupBy = function(fieldNames) { var fields = util.arrayize(fieldNames); @@ -171,14 +171,12 @@ Query.prototype.groupBy = function(fieldNames) { * * *Reference: [Projection Queries]{@link http://goo.gl/EfsrJl}* * - * @param {array} fieldNames - Properties to return from the matched entities. + * @param {array} fieldNames - Properties to return from the matched entities. * @return {module:datastore/query} * * @example - * ```js * // Only retrieve the name and size properties. * var selectQuery = companyQuery.select(['name', 'size']); - * ``` */ Query.prototype.select = function(fieldNames) { var q = util.extend(this, new Query()); @@ -195,12 +193,10 @@ Query.prototype.select = function(fieldNames) { * @return {module:datastore/query} * * @example - * ```js * var cursorToken = 'X'; * * // Retrieve results starting from cursorToken. * var startQuery = companyQuery.start(cursorToken); - * ``` */ Query.prototype.start = function(start) { var q = util.extend(this, new Query()); @@ -217,12 +213,10 @@ Query.prototype.start = function(start) { * @return {module:datastore/query} * * @example - * ```js * var cursorToken = 'X'; * * // Retrieve results limited to the extent of cursorToken. * var endQuery = companyQuery.end(cursorToken); - * ``` */ Query.prototype.end = function(end) { var q = util.extend(this, new Query()); @@ -239,10 +233,8 @@ Query.prototype.end = function(end) { * @return {module:datastore/query} * * @example - * ```js * // Limit the results to 10 entities. * var limitQuery = companyQuery.limit(10); - * ``` */ Query.prototype.limit = function(n) { var q = util.extend(this, new Query()); @@ -259,10 +251,8 @@ Query.prototype.limit = function(n) { * @return {module:datastore/query} * * @example - * ```js * // Start from the 101st result. * var offsetQuery = companyQuery.offset(100); - * ``` */ Query.prototype.offset = function(n) { var q = util.extend(this, new Query()); diff --git a/lib/datastore/transaction.js b/lib/datastore/transaction.js index e88a2c1c4db..c5896d43340 100644 --- a/lib/datastore/transaction.js +++ b/lib/datastore/transaction.js @@ -15,6 +15,7 @@ */ /** + * @private * @module datastore/transaction */ @@ -56,11 +57,9 @@ var MODE_TRANSACTIONAL = 'TRANSACTIONAL'; * Google Developers Console. * * @example - * ```js * var Connection = require('lib/common/connection.js').Connection; * var myConnection = new Connection({}); * var transaction = new Transaction(myConnection, 'my-project-id'); - * ``` */ function Transaction(conn, datasetId) { this.conn = conn; @@ -79,7 +78,6 @@ function Transaction(conn, datasetId) { * a transaction. * * @example - * ```js * transaction.begin(function(err) { * // Perform Datastore operations as usual. * transaction.get(datastore.key('Company', 123), function(err, entity) { @@ -90,7 +88,6 @@ function Transaction(conn, datasetId) { * transaction.rollback(function(err) {}); * }); * }); - * ``` */ Transaction.prototype.begin = function(callback) { callback = callback || util.noop; @@ -111,7 +108,6 @@ Transaction.prototype.begin = function(callback) { * @param {function} callback - The callback function. * * @example - * ```js * transaction.begin(function(err) { * transaction.rollback(function(err) { * if (err) { @@ -119,7 +115,6 @@ Transaction.prototype.begin = function(callback) { * } * }); * }); - * ``` */ Transaction.prototype.rollback = function(callback) { callback = callback || util.noop; @@ -140,7 +135,6 @@ Transaction.prototype.rollback = function(callback) { * @param {function} callback - The callback function. * * @example - * ```js * transaction.begin(function(err) { * transaction.commit(function(err) { * if (err) { @@ -148,7 +142,6 @@ Transaction.prototype.rollback = function(callback) { * } * }); * }); - * ``` */ Transaction.prototype.commit = function(callback) { callback = callback || util.noop; @@ -169,7 +162,6 @@ Transaction.prototype.commit = function(callback) { * @param {function} callback - The callback function. * * @example - * ```js * transaction.begin(function(err) { * transaction.finalize(function(err) { * if (err) { @@ -177,7 +169,6 @@ Transaction.prototype.commit = function(callback) { * } * }); * }); - * ``` */ Transaction.prototype.finalize = function(callback) { if (!this.isFinalized) { @@ -196,7 +187,6 @@ Transaction.prototype.finalize = function(callback) { * @param {function} callback - The callback function. * * @example - * ```js * // These examples work with both a Transaction object and a Dataset object. * * // Get a single entity. @@ -207,7 +197,6 @@ Transaction.prototype.finalize = function(callback) { * datastore.key('Company', 123), * datastore.key('Product', 'Computer') * ], function(err, entities) {}); - * ``` */ Transaction.prototype.get = function(keys, callback) { var isMultipleRequest = Array.isArray(keys); @@ -240,7 +229,6 @@ Transaction.prototype.get = function(keys, callback) { * @param {function} callback - The callback function. * * @example - * ```js * // These examples work with both a Transaction object and a Dataset object. * * // Save a single entity. @@ -269,7 +257,6 @@ Transaction.prototype.get = function(keys, callback) { * } * } * ], function(err, keys) {}); - * ``` */ Transaction.prototype.save = function(entities, callback) { var isMultipleRequest = Array.isArray(entities); @@ -318,7 +305,6 @@ Transaction.prototype.save = function(entities, callback) { * @param {function} callback - The callback function. * * @example - * ```js * // These examples work with both a Transaction object and a Dataset object. * * // Delete a single entity. @@ -329,7 +315,6 @@ Transaction.prototype.save = function(entities, callback) { * datastore.key('Company', 123), * datastore.key('Product', 'Computer') * ], function(err) {}); - * ``` */ Transaction.prototype.delete = function(keys, callback) { var isMultipleRequest = Array.isArray(keys); @@ -361,7 +346,6 @@ Transaction.prototype.delete = function(keys, callback) { * @param {function} callback - The callback function. * * @example - * ```js * // Retrieve 5 companies. * transaction.runQuery(queryObject, function(err, entities, nextQuery) { * // `nextQuery` is not null if there are more results. @@ -369,7 +353,6 @@ Transaction.prototype.delete = function(keys, callback) { * transaction.runQuery(nextQuery, function(err, entities, nextQuery) {}); * } * }); - * ``` */ Transaction.prototype.runQuery = function(q, callback) { callback = callback || util.noop; @@ -413,14 +396,11 @@ Transaction.prototype.mapQuery = function() { /** * Make a request to the API endpoint. * - * @todo Handle non-HTTP 200 cases. - * * @param {string} method - Transaction action (allocateIds, commit, etc.). * @param {object} req - Request configuration object. * @param {function} callbcak - The callback function. * * @example - * ```js * var deleteRequest = { * MODE: 'NON_TRANSACTIONAL', * mutation: { @@ -428,9 +408,9 @@ Transaction.prototype.mapQuery = function() { * } * }; * transaction.makeReq('commit', deleteRequest, function(err) {}); - * ``` */ Transaction.prototype.makeReq = function(method, req, respType, callback) { + // TODO: Handle non-HTTP 200 cases. callback = callback || util.noop; this.conn.createAuthorizedReq({ method: 'POST', diff --git a/lib/index.js b/lib/index.js index 32783a9066b..26723947b97 100644 --- a/lib/index.js +++ b/lib/index.js @@ -14,10 +14,92 @@ * limitations under the License. */ +/** + * @module gcloud + */ + 'use strict'; -module.exports = { - datastore: require('./datastore'), - pubsub: require('./pubsub'), - storage: require('./storage') -}; +/** @alias module:gcloud */ +var gcloud = {}; + +/** + * [Google Cloud Datastore]{@link https://developers.google.com/datastore/} is a + * fully managed, schemaless database for storing non-relational data. Use this + * object to create a Dataset to interact with your data, an "Int", and a + * "Double" representation. + * + * @type {module:datastore} + * @see {module:datastore} + * + * @return {object} + * + * @example + * var gcloud = require('gcloud'); + * var datastore = gcloud.datastore; + * + * // datastore: + * // { + * // Dataset: function() {}, + * // double: function() {}, + * // int: function() {} + * // } + */ +gcloud.datastore = require('./datastore'); + +/** + * **Experimental** + * + * [Google Cloud Pub/Sub]{@link https://developers.google.com/pubsub/overview} + * is a reliable, many-to-many, asynchronous messaging service from Google Cloud + * Platform. + * + * Note: Google Cloud Pub/Sub API is available as a Limited Preview and the + * client library we provide is currently experimental. The API and/or the + * client might be changed in backward-incompatible ways. This API is not + * subject to any SLA or deprecation policy. Request to be whitelisted to use it + * by filling the + * [Limited Preview application form]{@link http://goo.gl/sO0wTu}. + * + * @type {module:pubsub} + * + * @return {object} + * + * @example + * var gcloud = require('gcloud'); + * var pubsub = gcloud.pubsub; + * + * var conn = new pubsub.Connection({ + * projectId: YOUR_PROJECT_ID, + * keyFilename: '/path/to/the/key.json' + * }); + */ +gcloud.pubsub = require('./pubsub'); + +/** + * Google Cloud Storage allows you to store data on Google infrastructure. Read + * [Google Cloud Storage API docs]{@link https://developers.google.com/storage/} + * for more information. + * + * You need to create a Google Cloud Storage bucket to use this client library. + * Follow the steps on + * [Google Cloud Storage docs]{@link https://developers.google.com/storage/} to + * create a bucket. + + * @type {module:storage} + * @see {module:storage} + * + * @return {object} + * + * @example + * var gcloud = require('gcloud'); + * var storage = gcloud.storage; + * + * // storage: + * // { + * // Bucket: function() {} + * // } + */ +gcloud.storage = require('./storage'); + +module.exports = gcloud; diff --git a/lib/pubsub/index.js b/lib/pubsub/index.js index 2df6d23329f..d977b690d7d 100644 --- a/lib/pubsub/index.js +++ b/lib/pubsub/index.js @@ -14,24 +14,25 @@ * limitations under the License. */ +/** + * @module pubsub + */ + 'use strict'; var events = require('events'); var nodeutil = require('util'); +/** @type {module:common/connection} */ var conn = require('../common/connection.js'); + +/** @type {module:common/util} */ var util = require('../common/util.js'); -/** - * Base URL for Pub/Sub API. - * @type {String} - */ +/** @private @const {string} Base URL for Pub/Sub API. */ var PUBSUB_BASE_URL = 'https://www.googleapis.com/pubsub/v1beta1'; -/** - * Required scopes for Pub/Sub API. - * @type {Array} - */ +/** @const {array} Required scopes for Pub/Sub API. */ var SCOPES = [ 'https://www.googleapis.com/auth/pubsub', 'https://www.googleapis.com/auth/cloud-platform' diff --git a/lib/storage/index.js b/lib/storage/index.js index e14574470ce..080832a0ba6 100644 --- a/lib/storage/index.js +++ b/lib/storage/index.js @@ -25,24 +25,33 @@ var nodeutil = require('util'); var stream = require('stream'); var uuid = require('node-uuid'); -/** @type {module:common/connection} */ +/** + * @private + * @type module:common/connection + */ var conn = require('../common/connection.js'); -/** @type {module:common/util} */ +/** + * @private + * @type module:common/util + */ var util = require('../common/util.js'); /** * Required scopes for Google Cloud Storage API. + * @private * @const {array} */ var SCOPES = ['https://www.googleapis.com/auth/devstorage.full_control']; /** + * @private * @const {string} */ var STORAGE_BASE_URL = 'https://www.googleapis.com/storage/v1/b'; /** + * @private * @const {string} */ var STORAGE_UPLOAD_BASE_URL = 'https://www.googleapis.com/upload/storage/v1/b'; @@ -76,29 +85,30 @@ BufferStream.prototype._read = function() { * the guide on {@link https://developers.google.com/storage} to create a * bucket. * + * @alias module:storage + * @throws if a bucket name isn't provided. * * @param {object} options - Configuration options. * @param {string} options.bucketName - Name of the bucket. - * @param {string} options.keyFileName - Full path to the JSON key downloaded + * @param {string} options.keyFilename - Full path to the JSON key downloaded * from the Google Developers Console. * * @example - * ```js * var gcloud = require('gcloud'); + * var storage = gcloud.storage; * var bucket; * * // From Google Compute Engine - * bucket = new gcloud.storage.Bucket({ + * bucket = new storage.Bucket({ * bucketName: YOUR_BUCKET_NAME * }); * * // From elsewhere - * bucket = new gcloud.storage.Bucket({ + * bucket = new storage.Bucket({ * bucketName: YOUR_BUCKET_NAME, * keyFilename: '/path/to/the/key.json' * }); - * ``` */ function Bucket(options) { if (!options.bucketName) { @@ -129,7 +139,6 @@ function Bucket(options) { * @param {function} callback - The callback function. * * @example - * ```js * bucket.list(function(err, files, nextQuery) { * if (nextQuery) { * // nextQuery will be non-null if there are more results. @@ -139,7 +148,6 @@ function Bucket(options) { * * // Fetch using a query. * bucket.list({ maxResults: 5 }, function(err, files, nextQuery) {}); - * ``` */ Bucket.prototype.list = function(query, callback) { if (arguments.length === 1) { @@ -166,9 +174,7 @@ Bucket.prototype.list = function(query, callback) { * @param {function} callback - The callback function. * * @example - * ```js * bucket.stat('filename', function(err, metadata){}); - * ``` */ Bucket.prototype.stat = function(name, callback) { var path = util.format('o/{name}', { name: name }); @@ -189,12 +195,10 @@ Bucket.prototype.stat = function(name, callback) { * @param {function=} callback - The callback function. * * @example - * ```js * bucket.copy('filename', { * bucket: 'destination-bucket', * name: 'destination-filename' * }, function(err) {}); - * ``` */ Bucket.prototype.copy = function(name, metadata, callback) { callback = callback || util.noop; @@ -221,9 +225,7 @@ Bucket.prototype.copy = function(name, metadata, callback) { * @param {function} callback - The callback function. * * @example - * ```js * bucket.remove('filename', function(err) {}); - * ``` */ Bucket.prototype.remove = function(name, callback) { var path = util.format('o/{name}', { name: name }); @@ -239,14 +241,12 @@ Bucket.prototype.remove = function(name, callback) { * @return {ReadStream} * * @example - * ```js * // Create a readable stream and write the file contents to "local-file-path". * var fs = require('fs'); * * bucket.createReadStream('remote-file-name') * .pipe(fs.createWriteStream('local-file-path')) * .on('error', function(err) {}); - * ``` */ Bucket.prototype.createReadStream = function(name) { var that = this; @@ -276,7 +276,6 @@ Bucket.prototype.createReadStream = function(name) { * @return {stream} * * @example - * ```js * // Read from a local file and pipe to your bucket. * var fs = require('fs'); * @@ -284,7 +283,6 @@ Bucket.prototype.createReadStream = function(name) { * .pipe(bucket.createWriteStream('remote-file-name')) * .on('error', function(err) {}) * .on('complete', function(fileObject) {}); - * ``` */ Bucket.prototype.createWriteStream = function(name, metadata) { var dup = duplexify(); @@ -317,7 +315,6 @@ Bucket.prototype.createWriteStream = function(name, metadata) { * @param {function=} callback - The callback function. * * @example - * ```js * // Upload "Hello World" as file contents. `data` can be any string or buffer. * bucket.write('filename', { * data: 'Hello World' @@ -325,7 +322,6 @@ Bucket.prototype.createWriteStream = function(name, metadata) { * * // A shorthand for the above. * bucket.write('filename', 'Hello World', function(err) {}); - * ``` */ Bucket.prototype.write = function(name, options, callback) { callback = callback || util.noop; @@ -348,6 +344,8 @@ Bucket.prototype.write = function(name, options, callback) { /** * Get a remote stream to begin piping a readable stream to. * + * @private + * * @param {string} name - The desired name of the file. * @param {object} metadata - File descriptive metadata. * @param {function} callback - The callback function. diff --git a/package.json b/package.json index ebfdf4c2583..cedbbe14349 100644 --- a/package.json +++ b/package.json @@ -43,14 +43,16 @@ "request": "^2.39.0" }, "devDependencies": { + "coveralls": "^2.11.1", "istanbul": "^0.3.0", + "jsdoc": "^3.3.0-alpha9", "jshint": "^2.5.2", "mocha": "^1.21.3", "sandboxed-module": "^1.0.1", - "tmp": "0.0.24", - "coveralls": "^2.11.1" + "tmp": "0.0.24" }, "scripts": { + "docs": "jsdoc -c .jsdoc.json && cp docs/module-gcloud.html docs/index.html", "lint": "jshint lib/ regression/ test/", "test": "mocha --recursive --reporter spec", "regression-test": "mocha regression/ --reporter spec --timeout 15000",