add download() method

[nicolabortignon]

Hi,
I spent few hours looking into the code, but didn't find the solution.
What am i suppose to do in order to load the content of a file from a createReadStream into a variable ?
In the example there is only a read-to-pipe-to-write example.

I just want to do something like

var streamPointer = cloudstorage.createReadStream(myTextFile)
    streamPointer.on('complete', function(res) {
            myVar = res
        })

[stephenplusplus]

Sorry, it appears our docs are lacking on showing how to simply download a file. Here's the current way to get a file's contents:

var gcloud = require("gcloud")({ /* credentials. */ });
var cloudstorage = gcloud.storage();
var myTextFile = cloudstorage.file('your-file.txt');

var fileContents = new Buffer('');

myTextFile.createReadStream()
  .on('data', function(chunk) {
    fileContents = Buffer.concat([fileContents, chunk]);
  })
  .on('complete', function() {
    // `fileContents` is ready
  });

@ryanseys thoughts on adding Bucket#download to make this easier?

[ryanseys]

@stephenplusplus That sounds like a good idea. I had an idea for a similar thing that would immediately write to a given filename as well for those wanting to just download a bunch of files. Perhaps we could support both of these options either as separate methods or as an option?

[stephenplusplus]

Something like:

myBucket.download("my-file.txt", function (err, contents, file) {
  // contents === file's contents
  // file === myBucket.file("my-file.txt")
})

// and...

myBucket.download("my-file.txt", { destination: "/Users/stephen/Desktop/local-copy.txt" }, function (err, contents, file) {
  // contents === file's contents
  // file === myBucket.file("my-file.txt")
})

// and we can support a File object as a source:
myBucket.download(myBucket.file("my-file.txt"), //...

?

[nicolabortignon]

I would say both the .read and .download as wraps for the asynchronous readStream and Pipe, would add a really appreciated level of simplification.

Also, just as overall idea, would be nice to align the interface of the CreateReadStream to the standard (fs) one.
Thanks for the answer!

[ryanseys]

If we are downloading, wouldn't we just download from a Bucket#file instance? And if we just want to immediately write to a file without storing in memory, that'd be cool... I don't know if we should use two separate methods for that or if we can get away with just one like below:

myFile.download('./local/path/image.jpg', function(err, contents) {
  // don't consume memory
  // contents = null
});

myFile.download(function(err, contents) {
  // consume memory
  // contents = contents of file
});

[stephenplusplus]

PR sent: #381