Debian Codegraph @

closure-library/closure/goog/fs/fs.js

raw
1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Wrappers for the HTML5 File API. These wrappers closely mirror
17 * the underlying APIs, but use Closure-style events and Deferred return values.
18 * Their existence also makes it possible to mock the FileSystem API for testing
19 * in browsers that don't support it natively.
20 *
21 * When adding public functions to anything under this namespace, be sure to add
22 * its mock counterpart to goog.testing.fs.
23 *
24 */
25
26 goog.provide('goog.fs');
27
28 goog.require('goog.array');
29 goog.require('goog.async.Deferred');
30 goog.require('goog.fs.Error');
31 goog.require('goog.fs.FileReader');
32 goog.require('goog.fs.FileSystemImpl');
33 goog.require('goog.fs.url');
34 goog.require('goog.userAgent');
35
36
37 /**
38 * Get a wrapped FileSystem object.
39 *
40 * @param {goog.fs.FileSystemType_} type The type of the filesystem to get.
41 * @param {number} size The size requested for the filesystem, in bytes.
42 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
43 * error occurs, the errback is called with a {@link goog.fs.Error}.
44 * @private
45 */
46 goog.fs.get_ = function(type, size) {
47 var requestFileSystem =
48 goog.global.requestFileSystem || goog.global.webkitRequestFileSystem;
49
50 if (!goog.isFunction(requestFileSystem)) {
51 return goog.async.Deferred.fail(new Error('File API unsupported'));
52 }
53
54 var d = new goog.async.Deferred();
55 requestFileSystem(
56 type, size, function(fs) { d.callback(new goog.fs.FileSystemImpl(fs)); },
57 function(err) {
58 d.errback(new goog.fs.Error(err, 'requesting filesystem'));
59 });
60 return d;
61 };
62
63
64 /**
65 * The two types of filesystem.
66 *
67 * @enum {number}
68 * @private
69 */
70 goog.fs.FileSystemType_ = {
71 /**
72 * A temporary filesystem may be deleted by the user agent at its discretion.
73 */
74 TEMPORARY: 0,
75 /**
76 * A persistent filesystem will never be deleted without the user's or
77 * application's authorization.
78 */
79 PERSISTENT: 1
80 };
81
82
83 /**
84 * Returns a temporary FileSystem object. A temporary filesystem may be deleted
85 * by the user agent at its discretion.
86 *
87 * @param {number} size The size requested for the filesystem, in bytes.
88 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
89 * error occurs, the errback is called with a {@link goog.fs.Error}.
90 */
91 goog.fs.getTemporary = function(size) {
92 return goog.fs.get_(goog.fs.FileSystemType_.TEMPORARY, size);
93 };
94
95
96 /**
97 * Returns a persistent FileSystem object. A persistent filesystem will never be
98 * deleted without the user's or application's authorization.
99 *
100 * @param {number} size The size requested for the filesystem, in bytes.
101 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
102 * error occurs, the errback is called with a {@link goog.fs.Error}.
103 */
104 goog.fs.getPersistent = function(size) {
105 return goog.fs.get_(goog.fs.FileSystemType_.PERSISTENT, size);
106 };
107
108
109 /**
110 * Creates a blob URL for a blob object.
111 * Throws an error if the browser does not support Object Urls.
112 *
113 * TODO(user): Update references to this method to use
114 * goog.fs.url.createObjectUrl instead.
115 *
116 * @param {!Blob} blob The object for which to create the URL.
117 * @return {string} The URL for the object.
118 */
119 goog.fs.createObjectUrl = function(blob) {
120 return goog.fs.url.createObjectUrl(blob);
121 };
122
123
124 /**
125 * Revokes a URL created by {@link goog.fs.createObjectUrl}.
126 * Throws an error if the browser does not support Object Urls.
127 *
128 * TODO(user): Update references to this method to use
129 * goog.fs.url.revokeObjectUrl instead.
130 *
131 * @param {string} url The URL to revoke.
132 */
133 goog.fs.revokeObjectUrl = function(url) {
134 goog.fs.url.revokeObjectUrl(url);
135 };
136
137
138 /**
139 * Checks whether this browser supports Object Urls. If not, calls to
140 * createObjectUrl and revokeObjectUrl will result in an error.
141 *
142 * TODO(user): Update references to this method to use
143 * goog.fs.url.browserSupportsObjectUrls instead.
144 *
145 * @return {boolean} True if this browser supports Object Urls.
146 */
147 goog.fs.browserSupportsObjectUrls = function() {
148 return goog.fs.url.browserSupportsObjectUrls();
149 };
150
151
152 /**
153 * Concatenates one or more values together and converts them to a Blob.
154 *
155 * @param {...(string|!Blob|!ArrayBuffer)} var_args The values that will make up
156 * the resulting blob.
157 * @return {!Blob} The blob.
158 */
159 goog.fs.getBlob = function(var_args) {
160 var BlobBuilder = goog.global.BlobBuilder || goog.global.WebKitBlobBuilder;
161
162 if (goog.isDef(BlobBuilder)) {
163 var bb = new BlobBuilder();
164 for (var i = 0; i < arguments.length; i++) {
165 bb.append(arguments[i]);
166 }
167 return bb.getBlob();
168 } else {
169 return goog.fs.getBlobWithProperties(goog.array.toArray(arguments));
170 }
171 };
172
173
174 /**
175 * Creates a blob with the given properties.
176 * See https://developer.mozilla.org/en-US/docs/Web/API/Blob for more details.
177 *
178 * @param {Array<string|!Blob>} parts The values that will make up the
179 * resulting blob.
180 * @param {string=} opt_type The MIME type of the Blob.
181 * @param {string=} opt_endings Specifies how strings containing newlines are to
182 * be written out.
183 * @return {!Blob} The blob.
184 */
185 goog.fs.getBlobWithProperties = function(parts, opt_type, opt_endings) {
186 var BlobBuilder = goog.global.BlobBuilder || goog.global.WebKitBlobBuilder;
187
188 if (goog.isDef(BlobBuilder)) {
189 var bb = new BlobBuilder();
190 for (var i = 0; i < parts.length; i++) {
191 bb.append(parts[i], opt_endings);
192 }
193 return bb.getBlob(opt_type);
194 } else if (goog.isDef(goog.global.Blob)) {
195 var properties = {};
196 if (opt_type) {
197 properties['type'] = opt_type;
198 }
199 if (opt_endings) {
200 properties['endings'] = opt_endings;
201 }
202 return new Blob(parts, properties);
203 } else {
204 throw new Error('This browser doesn\'t seem to support creating Blobs');
205 }
206 };
207
208
209 /**
210 * Converts a Blob or a File into a string. This should only be used when the
211 * blob is known to be small.
212 *
213 * @param {!Blob} blob The blob to convert.
214 * @param {string=} opt_encoding The name of the encoding to use.
215 * @return {!goog.async.Deferred} The deferred string. If an error occurrs, the
216 * errback is called with a {@link goog.fs.Error}.
217 * @deprecated Use {@link goog.fs.FileReader.readAsText} instead.
218 */
219 goog.fs.blobToString = function(blob, opt_encoding) {
220 return goog.fs.FileReader.readAsText(blob, opt_encoding);
221 };
222
223
224 /**
225 * Slices the blob. The returned blob contains data from the start byte
226 * (inclusive) till the end byte (exclusive). Negative indices can be used
227 * to count bytes from the end of the blob (-1 == blob.size - 1). Indices
228 * are always clamped to blob range. If end is omitted, all the data till
229 * the end of the blob is taken.
230 *
231 * @param {!Blob} blob The blob to be sliced.
232 * @param {number} start Index of the starting byte.
233 * @param {number=} opt_end Index of the ending byte.
234 * @return {Blob} The blob slice or null if not supported.
235 */
236 goog.fs.sliceBlob = function(blob, start, opt_end) {
237 if (!goog.isDef(opt_end)) {
238 opt_end = blob.size;
239 }
240 if (blob.webkitSlice) {
241 // Natively accepts negative indices, clamping to the blob range and
242 // range end is optional. See http://trac.webkit.org/changeset/83873
243 return blob.webkitSlice(start, opt_end);
244 } else if (blob.mozSlice) {
245 // Natively accepts negative indices, clamping to the blob range and
246 // range end is optional. See https://developer.mozilla.org/en/DOM/Blob
247 // and http://hg.mozilla.org/mozilla-central/rev/dae833f4d934
248 return blob.mozSlice(start, opt_end);
249 } else if (blob.slice) {
250 // Old versions of Firefox and Chrome use the original specification.
251 // Negative indices are not accepted, only range end is clamped and
252 // range end specification is obligatory.
253 // See http://www.w3.org/TR/2009/WD-FileAPI-20091117/
254 if ((goog.userAgent.GECKO && !goog.userAgent.isVersionOrHigher('13.0')) ||
255 (goog.userAgent.WEBKIT && !goog.userAgent.isVersionOrHigher('537.1'))) {
256 if (start < 0) {
257 start += blob.size;
258 }
259 if (start < 0) {
260 start = 0;
261 }
262 if (opt_end < 0) {
263 opt_end += blob.size;
264 }
265 if (opt_end < start) {
266 opt_end = start;
267 }
268 return blob.slice(start, opt_end - start);
269 }
270 // IE and the latest versions of Firefox and Chrome use the new
271 // specification. Natively accepts negative indices, clamping to the blob
272 // range and range end is optional.
273 // See http://dev.w3.org/2006/webapi/FileAPI/
274 return blob.slice(start, opt_end);
275 }
276 return null;
277 };