storage: api refactor.

README.md

@@ -83,25 +83,32 @@ If you don't have a bucket already, follow the steps of the [Creating a Bucket g
 See the [gcloud-node Storage API documentation][gcloud-storage-docs] to learn how to connect to Cloud Storage using this library.
 
 ```js
+var fs = require('fs');
 var gcloud = require('gcloud');
-var bucket;
+var storage;
 
 // From Google Compute Engine:
-bucket = gcloud.storage.bucket({
-  projectId: 'my-project',
-  bucketName: 'my-bucket'
+storage = gcloud.storage({
+  projectId: 'my-project'
 });
 
 // Or from elsewhere:
-bucket = gcloud.storage.bucket({
-  projectId: 'my-project',
+storage = gcloud.storage({
   keyFilename: '/path/to/keyfile.json',
-  bucketName: 'my-bucket'
+  projectId: 'my-project'
 });
 
-bucket.write('demo.txt', 'Hello World', function(err) {
-  console.log(err || 'Created demo.txt');
-});
+// Create a new bucket.
+storage.createBucket('my-new-bucket', function(err, bucket) {});
+
+// Reference an existing bucket.
+var bucket = storage.bucket('my-bucket');
+
+// Upload a local file to a new file to be created in your bucket.
+fs.createReadStream('/local/file.txt').pipe(bucket.file('file.txt'));
+
+// Download a remote file to a new local file.
+bucket.file('photo.jpg').pipe(fs.createWriteStream('/local/photo.jpg'));
 ```
 
 ## Google Cloud Pub/Sub (Alpha)

docs/components/docs/docs-values.js

@@ -74,9 +74,22 @@ angular.module('gcloud.docs')
       _url: '{baseUrl}/storage'
     },
 
+    storageWithFiles: {
+      title: 'Storage',
+      _url: '{baseUrl}/storage',
+      pages: [
+        {
+          title: 'Bucket',
+          url: '/bucket'
+        },
+        {
+          title: 'File',
+          url: '/file'
+        }
+      ]
+    },
+
     VERSIONS: {
-      // Give a version with/without a comparator, anything semver:
-      //   https://github.com/npm/node-semver#versions
       //
       // Multiple keys may be used to match a version.
       //
@@ -89,8 +102,18 @@ angular.module('gcloud.docs')
       //
       // To keep the documentation for the main module, `gcloud`, on top of the
       // link list, **make sure the title is `gcloud`**
-      '*': ['gcloud', 'storage'],
+      '*': ['gcloud'],
+
+      // deprecate old datastore api.
       '<0.8.0': ['datastore'],
-      '>=0.8.0': ['datastoreWithTransaction', 'pubsub']
+
+      // introduce datastore refactor + pubsub.
+      '>=0.8.0': ['datastoreWithTransaction', 'pubsub'],
+
+      // deprecate old storage api.
+      '<0.9.0': ['storage'],
+
+      // introduce new storage api.
+      '>=0.9.0': ['storageWithFiles']
     }
   });

docs/components/docs/docs.html

@@ -94,12 +94,10 @@ <h3>Pub/Sub Overview</h3>
       <article ng-if="isActiveDoc('storage')">
         <h3>Storage Overview</h3>
         <p>
-          The <code>gcloud.storage</code> object contains a <code>bucket</code> object, which is how you will interact with your Google Cloud Storage bucket. See the guide on <a href="https://developers.google.com/storage">Google Cloud Storage</a> to create a bucket.
+          The <code>gcloud.storage</code> object contains a <code>bucket</code> function, which is how you will interact with your Google Cloud Storage bucket. See the guide on <a href="https://developers.google.com/storage">Google Cloud Storage</a> to create a bucket.
         </p>
         <div hljs>
-var bucket = gcloud.storage.bucket({
-  bucketName: 'MyBucket'
-});</div>
+var bucket = gcloud.storage.bucket('my-bucket');</div>
         <p>
           See examples below for more on how to access your bucket to upload a file, read its files, create signed URLs, and more.
         </p>

docs/components/docs/docs.js

@@ -12,32 +12,37 @@ angular
             .replace(/`([^`]*)`/g, '<code>$1</code>');
       }
       function formatComments(str) {
-        var matched = 0;
         var paragraphComments = /\/\/-+((\n|\r|.)*?(\/\/-))/g;
-
         if (!paragraphComments.test(str)) {
-          return '<div hljs language="javascript">\n' + str + '</div>';
+          return wrapCode(str);
         }
-
-        str = str.replace(paragraphComments, function(match, block) {
-          return '' +
-              (++matched > 1 ? '</div>' : '') +
-              '<p>' +
-              formatHtml(detectLinks(detectModules(
-                block.trim()
-                  .replace(/\/\/-*\s*/g, '\n')
-                  .replace(/\n\n/g, '\n')
-                  .replace(/(\w)\n(\w)/g, '$1 $2')
-                  .replace(/\n\n/g, '</p><p>')
-              ))) +
-              '</p>' +
-              '<div hljs language="javascript">';
+        var matches = [];
+        var lastIndex = 0;
+        str.replace(paragraphComments, function(match, block, inner, close, offset) {
+          if (lastIndex !== offset) {
+            // Push the code missed between text blocks.
+            matches.push(wrapCode(str.substr(lastIndex, offset - lastIndex)));
+          }
+          lastIndex = offset + match.length;
+          matches.push('<p>');
+          matches.push(formatHtml(detectLinks(detectModules(
+            block.trim()
+              .replace(/\/\/-*\s*/g, '\n')
+              .replace(/\n\n/g, '\n')
+              .replace(/(\w)\n(\w)/g, '$1 $2')
+              .replace(/\n\n/g, '</p><p>')
+          ))));
+          matches.push('</p>');
         });
-
-        str = str.replace(/(<div[^>]*>)\n+/g, '$1\n');
-        str = str.replace(/\n<\/div>/g, '</div>');
-
-        return str;
+        if (lastIndex < str.length) {
+          matches.push(wrapCode(str.substr(lastIndex)));
+        }
+        return matches.join('')
+          .replace(/(<div[^>]*>)\n+/g, '$1\n')
+          .replace(/\n<\/div>/g, '</div>');
+        function wrapCode(code) {
+          return '<div hljs language="javascript">\n' + code + '</div>';
+        }
       }
       function detectLinks(str) {
         var regex = {
@@ -85,7 +90,8 @@ angular
         });
       }
       function reduceModules(acc, type, index, types) {
-        var CUSTOM_TYPES = ['query', 'dataset', 'transaction'];
+        var CUSTOM_TYPES = ['query', 'dataset', 'transaction', 'bucket', 'file'];
+        type = type.replace('=', '');
         if (CUSTOM_TYPES.indexOf(type.toLowerCase()) > -1) {
           if (types[index - 1]) {
             type = types[index - 1] + '/' + type;
@@ -98,7 +104,7 @@ angular
       return function(data) {
         return data.data
           .filter(function(obj) {
-            return obj.isPrivate === false && obj.ignore === false;
+            return obj.ctx && obj.isPrivate === false && obj.ignore === false;
           })
           .map(function(obj) {
             return {
@@ -120,7 +126,7 @@ angular
                       formatHtml(tag.description.replace(/^- /, '')));
                   tag.types = $sce.trustAsHtml(tag.types.reduceRight(
                       reduceModules, []).join(', '));
-                  tag.optional = tag.types.toString().substr(-1) === '=';
+                  tag.optional = tag.types.toString().indexOf('=') > -1;
                   return tag;
                 }),
               returns: obj.tags.filter(function(tag) {

lib/index.js

@@ -44,6 +44,12 @@ var PubSub = require('./pubsub');
  */
 var Storage = require('./storage');
 
+/**
+ * @type {module:common/util}
+ * @private
+ */
+var util = require('./common/util.js');
+
 /**
  * There are two key ways to use the `gcloud` module.
  *
@@ -91,7 +97,7 @@ var Storage = require('./storage');
  * //   });
  *
  * var bucket = gcloud.storage.bucket({
- *   bucketName: 'PhotosBucket',
+ *   name: 'PhotosBucket',
  *   // properties may be overridden:
  *   keyFilename: '/path/to/other/keyfile.json'
  * });
@@ -103,7 +109,10 @@ function gcloud(config) {
       options = options || {};
       return new PubSub(util.extendGlobalConfig(config, options));
     },
-    storage: new Storage(config)
+    storage: function(options) {
+      options = options || {};
+      return new Storage(util.extendGlobalConfig(config, options));
+    }
   };
 }