David Wheeler - HTTP.Query-0.03
Name
HTTP.Query - Easy GET query string management
Synopsis
JSAN.use('HTTP.Query');
var query = new HTTP.Query(location.search);
query.set('from', 'me@example.com');
query.add('to', 'you@example.com');
query.add('to', 'him@example.com');
location.search = query.toString();
Description
This class parses a GET query string, pulling out its argument keys and values and unescaping their encodings, and arranges them into an object. If a given query key is specified multiple times, then all of its values will be stored in an array for that key.
Constructor
var query = new HTTP.Query;
var query = new HTTP.Query(queryString);
Returns a new HTTP.Query
object that has parsed the queryString
passed as the single argument. If no query argument is passed and HTTP.Query
is running in a Web browser, window.document.location.search
will be used, instead. To initialize an empty HTTP.Query
object, pass a null
or empty string to the constructor.
get()
var value = query.get(key);
Gets the value stored for a given key in the table. If the key has multiple values, they will all be returned in an array object.
set()
query.set(key, value);
Sets the value for a key. Any previous value or values for that key will be discarded.
unset()
query.unset(key);
Takes a single key argument and deletes that key from the query object, so that none of its values will be in the object any longer.
clear()
query.clear();
Clears the query object of all values.
add()
query.add(key, value);
Adds a new value to the query object. This method is the best interface for adding mutiple values for a single key. Once a key has multiple values, those values will be returned from a call to get()
as an array.
act()
query.act(function (key, value) {
document.write(key + ' => ' + value);
return true;
});
Pass a function to this method to have it iterate over all of the key/value pairs in the query object. Keys with multiple values will trigger the execution of the function multiple times: once for each value. The function should expect two arguments: a key and a value. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every value in the query object.
toString()
alert(qry.toString());
location.search = query.toString('&');
alert(qry);
Overrides the default toString() method inherited from Object to return a properly-formatted and encoded GET query string. By default, it uses ";" as the query argument delimiter. Pass in "&" as the single argument to toString() for it to be used as the argument delimiter. Of course, when the HTTP.Query
object itself is used in a string context, thus implicitly calling toString() ";" will be the delimiter; call toString("&") explicitly to use "&" as the delimiter.
Author
David Wheeler <david@kineticode.com>
Copyright and License
Copyright 2005 by David Wheeler.
This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU GPL.
See http://www.perl.com/perl/misc/Artistic.html and http://www.gnu.org/copyleft/gpl.html.
// # $Id: Kinetic.pm 1493 2005-04-07 19:20:18Z theory $ // Set up namespace. if (typeof HTTP == 'undefined') HTTP = {}; HTTP.Query = function (qry) { this.query = []; // Do nothing with empty query strings. // Use the current browser document location search if there is no query. if (!arguments.length && typeof window != 'undefined') qry = window.document.location.search; if (qry == null || qry == '') return; var pairs = qry.substring(1).split(/[;&]/); for (var i = 0; i < pairs.length; i++) { var parts = pairs[i].split('='); if (parts[0] == null) continue; var key = unescape(parts[0]), val = unescape(parts[1]); if (this.query[key] == null) { this.query[key] = unescape(val); } else { if (typeof this.query[key] == 'string') { this.query[key] = [this.query[key], unescape(val)]; } else this.query[key].push(unescape(val)); } } }; HTTP.Query.VERSION = '0.03'; HTTP.Query.prototype = { get: function (key) { return this.query[key] }, set: function (key, val) { this.query[key] = val }, unset: function (key) { delete this.query[key] }, clear: function () { this.query = [] }, add: function (key, val) { if (this.query[key] != null) { if (typeof this.query[key] != 'string') this.query[key].push(val); else this.query[key] = [this.query[key], val]; } else { this.query[key] = val; } }, act: function (fn) { for (var k in this.query) { if (typeof this.query[k] == 'string') { if (!fn(k, this.query[k])) return; } else { // XXX What if someone has changed Array.prototype or // Object.prototype?? for (var i in this.query[k]) if (!fn(k, this.query[k][i])) return; } } }, toString: function (sep) { var ret = ''; if (sep == null) sep = ';'; this.act(function (k, v) { ret += sep + escape(k) + '=' + escape(v); return true; }); return ret.replace(/^[;&]/, '?'); } };