2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('querystring-parse', function(Y) {
11 * <p>The QueryString module adds support for serializing JavaScript objects into
12 * query strings and parsing JavaScript objects from query strings format.</p>
14 * <p>The QueryString namespace is added to your YUI instance including static methods
15 * Y.QueryString.parse(..) and Y.QueryString.stringify(..).</p>
17 * <p>The <code>querystring</code> module is a rollup of <code>querystring-parse</code> and
18 * <code>querystring-stringify</code>.</p>
20 * <p>As their names suggest, <code>querystring-parse</code> adds support for parsing
21 * Query String data (Y.QueryString.parse) and <code>querystring-stringify</code> for serializing
22 * JavaScript data into Query Strings (Y.QueryString.stringify). You may choose to
23 * include either of the submodules individually if you don't need the
24 * complementary functionality, or include the rollup for both.</p>
30 var QueryString = Y.namespace("QueryString"),
32 // Parse a key=val string.
33 // These can get pretty hairy
35 // parse(foo[bar][][bla]=baz)
36 // return parse(foo[bar][][bla],"baz")
37 // return parse(foo[bar][], {bla : "baz"})
38 // return parse(foo[bar], [{bla:"baz"}])
39 // return parse(foo, {bar:[{bla:"baz"}]})
40 // return {foo:{bar:[{bla:"baz"}]}}
41 pieceParser = function (eq) {
42 return function parsePiece (key, val) {
44 var sliced, numVal, head, tail, ret;
46 if (arguments.length !== 2) {
47 // key=val, called from the map/reduce
50 QueryString.unescape(key.shift()),
51 QueryString.unescape(key.join(eq))
54 key = key.replace(/^\s+|\s+$/g, '');
55 if (Y.Lang.isString(val)) {
56 val = val.replace(/^\s+|\s+$/g, '');
57 // convert numerals to numbers
60 if (val === numVal.toString(10)) {
65 sliced = /(.*)\[([^\]]*)\]$/.exec(key);
73 // ["foo[][bar][][baz]", "foo[][bar][]", "baz"]
79 return parsePiece(head, [val]);
82 // obj: key[subkey]=val
85 return parsePiece(head, ret);
89 // the reducer function that merges each query piece together into one set of params
90 mergeParams = function(params, addition) {
92 // if it's uncontested, then just return the addition.
94 // if the existing value is an array, then concat it.
95 : (Y.Lang.isArray(params)) ? params.concat(addition)
96 // if the existing value is not an array, and either are not objects, arrayify it.
97 : (!Y.Lang.isObject(params) || !Y.Lang.isObject(addition)) ? [params].concat(addition)
98 // else merge them as objects, which is a little more complex
99 : mergeObjects(params, addition)
103 // Merge two *objects* together. If this is called, we've already ruled
104 // out the simple cases, and need to do the for-in business.
105 mergeObjects = function(params, addition) {
106 for (var i in addition) {
107 if (i && addition.hasOwnProperty(i)) {
108 params[i] = mergeParams(params[i], addition[i]);
115 * Provides Y.QueryString.parse method to accept Query Strings and return native
116 * JavaScript objects.
118 * @module querystring
119 * @submodule querystring-parse
122 * @param qs {String} Querystring to be parsed into an object.
123 * @param sep {String} (optional) Character that should join param k=v pairs together. Default: "&"
124 * @param eq {String} (optional) Character that should join keys to their values. Default: "="
128 QueryString.parse = function (qs, sep, eq) {
129 // wouldn't Y.Array(qs.split()).map(pieceParser(eq)).reduce(mergeParams) be prettier?
130 return Y.Array.reduce(
132 qs.split(sep || "&"),
133 pieceParser(eq || "=")
141 * Provides Y.QueryString.unescape method to be able to override default decoding
142 * method. This is important in cases where non-standard delimiters are used, if
143 * the delimiters would not normally be handled properly by the builtin
144 * (en|de)codeURIComponent functions.
145 * Default: replace "+" with " ", and then decodeURIComponent behavior.
146 * @module querystring
147 * @submodule querystring-parse
150 * @param s {String} String to be decoded.
154 QueryString.unescape = function (s) {
155 return decodeURIComponent(s.replace(/\+/g, ' '));
162 }, '3.3.0' ,{requires:['collection']});
164 YUI.add('querystring-stringify', function(Y) {
167 * Provides Y.QueryString.stringify method for converting objects to Query Strings.
169 * @module querystring
170 * @submodule querystring-stringify
175 var QueryString = Y.namespace("QueryString"),
180 * Provides Y.QueryString.escape method to be able to override default encoding
181 * method. This is important in cases where non-standard delimiters are used, if
182 * the delimiters would not normally be handled properly by the builtin
183 * (en|de)codeURIComponent functions.
184 * Default: encodeURIComponent
185 * @module querystring
186 * @submodule querystring-stringify
190 QueryString.escape = encodeURIComponent;
193 * <p>Converts an arbitrary value to a Query String representation.</p>
195 * <p>Objects with cyclical references will trigger an exception.</p>
199 * @param obj {Variant} any arbitrary value to convert to query string
200 * @param cfg {Object} (optional) Configuration object. The three
201 * supported configurations are:
202 * <ul><li>sep: When defined, the value will be used as the key-value
203 * separator. The default value is "&".</li>
204 * <li>eq: When defined, the value will be used to join the key to
205 * the value. The default value is "=".</li>
206 * <li>arrayKey: When set to true, the key of an array will have the
207 * '[]' notation appended to the key. The default value is false.
209 * @param name {String} (optional) Name of the current key, for handling children recursively.
212 QueryString.stringify = function (obj, c, name) {
213 var begin, end, i, l, n, s,
214 sep = c && c.sep ? c.sep : "&",
215 eq = c && c.eq ? c.eq : "=",
216 aK = c && c.arrayKey ? c.arrayKey : false;
218 if (L.isNull(obj) || L.isUndefined(obj) || L.isFunction(obj)) {
219 return name ? QueryString.escape(name) + eq : '';
222 if (L.isBoolean(obj) || Object.prototype.toString.call(obj) === '[object Boolean]') {
226 if (L.isNumber(obj) || L.isString(obj)) {
227 return QueryString.escape(name) + eq + QueryString.escape(obj);
230 if (L.isArray(obj)) {
232 name = aK ? name + '[]' : name;
234 for (i = 0; i < l; i++) {
235 s.push( QueryString.stringify(obj[i], c, name) );
240 // now we know it's an object.
242 // Check for cyclical references in nested objects
243 for (i = stack.length - 1; i >= 0; --i) {
244 if (stack[i] === obj) {
245 throw new Error("QueryString.stringify. Cyclical reference");
251 begin = name ? name + '[' : '';
252 end = name ? ']' : '';
254 if (obj.hasOwnProperty(i)) {
256 s.push(QueryString.stringify(obj[i], c, n));
275 YUI.add('querystring', function(Y){}, '3.3.0' ,{use:['querystring-parse', 'querystring-stringify']});