use options object + role constants

Author: stephenplusplus

docs/components/docs/docs.js

@@ -154,7 +154,7 @@ angular
                 })
                 .map(function(tag) {
                   tag.description = $sce.trustAsHtml(
-                      formatHtml(detectLinks(tag.description.replace(/^- /, ''))));
+                      formatHtml(detectLinks(detectModules(tag.description.replace(/^- /, '')))));
                   tag.types = $sce.trustAsHtml(tag.types.reduceRight(
                       reduceModules, []).join(', '));
                   tag.optional = tag.types.toString().indexOf('=') > -1;

lib/storage/acl.js

@@ -50,43 +50,44 @@ function Acl(options) {
 /**
  * Add access controls on a {module:storage/bucket} or {module:storage/file}.
  *
- * @param {string} scope - Whose permissions will be updated.
- * @param {string} role - Permissions allowed for the defined scope.
- * @param {object=} options - Configuration object.
- * @param {int} options.generation - **File Objects Only** If present, selects a
- *     specific revision of this object (as opposed to the latest version, the
- *     default).
+ * @param {object} options - Configuration object.
+ * @param {string} options.scope - Whose permissions will be added.
+ * @param {string} options.role - Permissions allowed for the defined scope. See
+ *     {module:storage#acl}.
+ * @param {int=} options.generation - **File Objects Only** Select a specific
+ *     revision of this file (as opposed to the latest version, the default).
  * @param {function} callback - The callback function.
  *
  * @example
- * var scope = 'user-useremail@example.com';
- * var role = 'owner';
- *
- * myBucket.acl.add(scope, role, function(err, aclObject) {});
+ * myBucket.acl.add({
+ *   scope: 'user-useremail@example.com',
+ *   role: storage.acl.OWNER_ROLE
+ * }, function(err, aclObject) {});
  *
  * //-
- * // For file ACL operations, an options object is also accepted.
+ * // For file ACL operations, you can also specify a `generation` property.
  * //-
- * var options = {
+ * myFile.acl.add({
+ *   scope: 'user-useremail@example.com',
+ *   role: storage.acl.OWNER_ROLE,
  *   generation: 1
- * };
- *
- * myFile.acl.add(scope, role, options, function(err, aclObject) {});
+ * }, function(err, aclObject) {});
  */
-Acl.prototype.add = function(scope, role, options, callback) {
+Acl.prototype.add = function(options, callback) {
   var that = this;
 
   var body = {
-    entity: scope,
-    role: role.toUpperCase()
+    entity: options.scope,
+    role: options.role.toUpperCase()
   };
 
-  if (util.is(options, 'function')) {
-    callback = options;
-    options = null;
-  }
+  var query = null;
 
-  var query = options || null;
+  if (options.generation) {
+    query = {
+      generation: options.generation
+    };
+  }
 
   this.makeReq_('POST', '', query, body, function(err, resp) {
     if (err) {
@@ -101,56 +102,54 @@ Acl.prototype.add = function(scope, role, options, callback) {
 /**
  * Delete access controls on a {module:storage/bucket} or {module:storage/file}.
  *
- * @param {string} scope - Whose permissions will be revoked.
  * @param {object=} options - Configuration object.
- * @param {int} options.generation - **File Objects Only** If present, selects a
- *     specific revision of this object (as opposed to the latest version, the
- *     default).
+ * @param {string} options.scope - Whose permissions will be revoked.
+ * @param {int=} options.generation - **File Objects Only** Select a specific
+ *     revision of this file (as opposed to the latest version, the default).
  * @param {function} callback - The callback function.
  *
  * @example
- * var scope = 'user-useremail@example.com';
- *
- * myBucket.acl.delete(scope, function(err) {});
+ * myBucket.acl.delete({
+ *   scope: 'user-useremail@example.com'
+ * }, function(err) {});
  *
  * //-
  * // For file ACL operations, an options object is also accepted.
  * //-
- * var options = {
+ * myFile.acl.delete({
+ *   scope: 'user-useremail@example.com',
  *   generation: 1
- * };
- *
- * myFile.acl.delete(scope, options, function(err) {});
+ * }, function(err) {});
  */
-Acl.prototype.delete = function(scope, options, callback) {
-  var path = '/' + encodeURIComponent(scope);
-
-  if (util.is(options, 'function')) {
-    callback = options;
-    options = null;
+Acl.prototype.delete = function(options, callback) {
+  var path = '/' + encodeURIComponent(options.scope);
+  var query = null;
+
+  if (options.generation) {
+    query = {
+      generation: options.generation
+    };
   }
 
-  var query = options || null;
-
   this.makeReq_('DELETE', path, query, null, callback);
 };
 
 /**
  * Get access controls on a {module:storage/bucket} or {module:storage/file}. If
- * an scope is omitted, you will receive an array of all applicable access
+ * a scope is omitted, you will receive an array of all applicable access
  * controls.
  *
- * @param {string=} scope - Whose permissions will be fetched.
- * @param {object=} options - Configuration object.
- * @param {int} options.generation - **File Objects Only** If present, selects a
- *     specific revision of this object (as opposed to the latest version, the
- *     default).
- * @param {function} callback - The callback function.
+ * @param {object|function} options - Configuration object. If you want to
+ *     receive a list of all access controls, pass the callback function as the
+ *     only argument.
+ * @param {string=} options.scope - Whose permissions will be fetched.
+ * @param {int=} options.generation - **File Objects Only** Select a specific
+ *     revision of this file (as opposed to the latest version, the default).
  *
  * @example
- * var scope = 'user-useremail@example.com';
- *
- * myBucket.acl.get(scope, function(err, aclObject) {});
+ * myBucket.acl.get({
+ *   scope: 'user-useremail@example.com'
+ * }, function(err, aclObject) {});
  *
  * //-
  * // Get all access controls.
@@ -167,35 +166,28 @@ Acl.prototype.delete = function(scope, options, callback) {
  * //-
  * // For file ACL operations, an options object is also accepted.
  * //-
- * var options = {
+ * myFile.acl.get({
+ *   scope: 'user-useremail@example.com',
  *   generation: 1
- * };
- *
- * myFile.acl.get(options, function(err, aclObjects) {});
- * myFile.acl.get(scope, options, function(err, aclObject) {});
+ * } function(err, aclObject) {});
  */
-Acl.prototype.get = function(scope, options, callback) {
+Acl.prototype.get = function(options, callback) {
   var that = this;
   var path = '';
-
-  switch (typeof scope) {
-    case 'function':
-      callback = scope;
-      break;
-    case 'string':
-      path = '/' + encodeURIComponent(scope);
-      break;
-    case 'object':
-      options = scope;
-      break;
-  }
+  var query = null;
 
   if (util.is(options, 'function')) {
     callback = options;
     options = null;
-  }
+  } else {
+    path = '/' + encodeURIComponent(options.scope);
 
-  var query = options || null;
+    if (options.generation) {
+      query = {
+        generation: options.generation
+      };
+    }
+  }
 
   this.makeReq_('GET', path, query, null, function(err, resp) {
     if (err) {
@@ -218,43 +210,45 @@ Acl.prototype.get = function(scope, options, callback) {
 /**
  * Update access controls on a {module:storage/bucket} or {module:storage/file}.
  *
- * @param {string} scope - Whose permissions will be updated.
- * @param {string} role - Permissions allowed for the defined scope.
  * @param {object=} options - Configuration object.
- * @param {int} options.generation - **File Objects Only** If present, selects a
- *     specific revision of this object (as opposed to the latest version, the
- *     default).
+ * @param {string} options.scope - Whose permissions will be added.
+ * @param {string} options.role - Permissions allowed for the defined scope. See
+ *     {module:storage#acl}.
+ * @param {int=} options.generation - **File Objects Only** Select a specific
+ *     revision of this file (as opposed to the latest version, the default).
  * @param {function} callback - The callback function.
  *
  * @example
- * var scope = 'user-useremail@example.com';
- * var role = 'writer';
+ * var storage = gcloud.storage();
  *
- * myBucket.acl.update(scope, role, function(err) {});
+ * myBucket.acl.update({
+ *   scope: 'user-useremail@example.com',
+ *   role: storage.acl.WRITER_ROLE
+ * }, function(err) {});
  *
  * //-
  * // For file ACL operations, an options object is also accepted.
  * //-
- * var options = {
+ * myFile.acl.update({
+ *   scope: 'user-useremail@example.com',
+ *   role: storage.acl.WRITER_ROLE,
  *   generation: 1
- * };
- *
- * myFile.acl.update(scope, role, options, function(err) {});
+ * }, function(err) {});
  */
-Acl.prototype.update = function(scope, role, options, callback) {
+Acl.prototype.update = function(options, callback) {
   var that = this;
-  var path = '/' + encodeURIComponent(scope);
+  var path = '/' + encodeURIComponent(options.scope);
+  var query = null;
 
-  var body = {
-    role: role.toUpperCase()
-  };
-
-  if (util.is(options, 'function')) {
-    callback = options;
-    options = null;
+  if (options.generation) {
+    query = {
+      generation: options.generation
+    };
   }
 
-  var query = options || null;
+  var body = {
+    role: options.role.toUpperCase()
+  };
 
   this.makeReq_('PUT', path, query, body, function(err, resp) {
     if (err) {
@@ -274,7 +268,7 @@ Acl.prototype.update = function(scope, role, options, callback) {
 Acl.prototype.makeAclObject_ = function(accessControlObject) {
   var obj = {
     scope: accessControlObject.scope,
-    role: accessControlObject.role.toLowerCase()
+    role: accessControlObject.role
   };
 
   if (accessControlObject.projectTeam) {

lib/storage/index.js

@@ -110,6 +110,40 @@ function Storage(config) {
   this.projectId = config.projectId;
 }
 
+/**
+ * Google Cloud Storage uses access control lists (ACLs) to manage object and
+ * bucket access. ACLs are the mechanism you use to share objects with other
+ * users and allow other users to access your buckets and objects.
+ *
+ * This object provides constants to refer to the three permission levels that
+ * can be granted to a scope:
+ *
+ *   - `Storage.acl.OWNER_ROLE` - ("OWNER")
+ *   - `Storage.acl.READER_ROLE` - ("READER")
+ *   - `Storage.acl.WRITER_ROLE` - ("WRITER")
+ *
+ * For more detailed information, see
+ * [About Access Control Lists](http://goo.gl/6qBBPO).
+ *
+ * @type {object}
+ *
+ * @example
+ * var storage = gcloud.storage();
+ * var albums = storage.bucket('albums');
+ *
+ * albums.acl.add({
+ *   scope: 'user-useremail@example.com',
+ *   permission: Storage.acl.OWNER_ROLE
+ * }, function(err, aclObject) {});
+ */
+Storage.acl = {
+  OWNER_ROLE: 'OWNER',
+  READER_ROLE: 'READER',
+  WRITER_ROLE: 'WRITER'
+};
+
+Storage.prototype.acl = Storage.acl;
+
 /**
  * Get a reference to a Google Cloud Storage bucket.
  *