add queryString/setParam

doc/mdown/queryString.md

@@ -4,6 +4,25 @@ Utilities for query string manipulation.
 
 
 
+## contains(url, paramName):Boolen
+
+Checks if query string contains parameter.
+
+### Arguments:
+
+ 1. `url` (String)     : URL or query string.
+ 2. `paramName` (String) : Parameter name.
+
+### Example:
+
+```js
+var url = 'example.com/?lorem=ipsum';
+contains(url, 'lorem'); // true
+contains(url, 'foo');   //false
+```
+
+
+
 ## decode(queryStr[, shouldTypecast]):Object
 
 Parses query string and creates an object of keys => vals.
@@ -35,6 +54,8 @@ Get query parameter value.
 
 Will typecast value with [`string/typecast`](string.html#typecast) by default.
 
+See: [`setParam()`](#setParam)
+
 ### Arguments:
 
  1. `url` (String) : Url.
@@ -76,23 +97,18 @@ getQuery('example.com/?lorem=ipsum'); // "?lorem=ipsum"
 ```
 
 
-## contains(url, paramName):Boolen
-
-Checks if query string contains parameter.
-
-### Arguments:
+## setParam(url, paramName, value):String
 
- 1. `url` (String)     : URL or query string.
- 2. `paramName` (String) : Parameter name.
+Add new query string parameter to URL or update existing value.
 
-### Example:
+See: [`getParam()`](#getParam)
 
 ```js
-var url = 'example.com/?lorem=ipsum';
-contains(url, 'lorem'); // true
-contains(url, 'foo');   //false
+setParam('?foo=bar&lorem=0', 'lorem', 'ipsum'); // '?foo=bar&lorem=ipsum'
+setParam('?lorem=1', 'foo', 123); // '?lorem=1&foo=123'
 ```
 
+
 -------------------------------------------------------------------------------
 
 For more usage examples check specs inside `/tests` folder. Unit tests are the

src/queryString.js

@@ -8,7 +8,8 @@ return {
     'encode' : require('./queryString/encode'),
     'getParam' : require('./queryString/getParam'),
     'getQuery' : require('./queryString/getQuery'),
-    'parse' : require('./queryString/parse')
+    'parse' : require('./queryString/parse'),
+    'setParam' : require('./queryString/setParam')
 };
 
 });

src/queryString/setParam.js

@@ -0,0 +1,29 @@
+define(function () {
+
+    /**
+     * Set query string parameter value
+     * @version 0.1.0 (2012/10/11)
+     */
+    function setParam(url, paramName, value){
+        url = url || '';
+
+        var re = new RegExp('(\\?|&)'+ paramName +'=[^&]*' );
+        var param = paramName +'='+ encodeURIComponent( value );
+
+        if ( re.test(url) ) {
+            return url.replace(re, '$1'+ param);
+        } else {
+            if (url.indexOf('?') === -1) {
+                url += '?';
+            }
+            if (url.indexOf('=') !== -1) {
+                url += '&';
+            }
+            return url + param;
+        }
+
+    }
+
+    return setParam;
+
+});

tests/spec/queryString/spec-setParam.js

@@ -0,0 +1,32 @@
+define(['src/queryString/setParam'], function(setParam){
+
+    describe('queryString/setParam', function(){
+
+        it('should add value if it doesn\'t exist', function(){
+            expect( setParam('foo.com', 'bar', true) ).toBe( 'foo.com?bar=true' );
+            expect( setParam('foo.com?bar=1', 'ipsum', 'dolor') ).toBe( 'foo.com?bar=1&ipsum=dolor' );
+        });
+
+        it('should encode value', function () {
+            expect( setParam('foo.com?bar=1', 'ipsum', 'dólôr amèt') ).toBe( 'foo.com?bar=1&ipsum=d%C3%B3l%C3%B4r%20am%C3%A8t' );
+        });
+
+        it('should update value if it exists', function(){
+            expect( setParam('foo.com?bar=2', 'bar', false) ).toBe( 'foo.com?bar=false' );
+            expect( setParam('foo.com?bar=1&ipsum=dolor%20amet&maecennas=3', 'bar', 'amet') ).toBe( 'foo.com?bar=amet&ipsum=dolor%20amet&maecennas=3' );
+        });
+
+        it('should work with just the query string', function () {
+            expect( setParam('?dolor=amet', 'ipsum', 123) ).toEqual( '?dolor=amet&ipsum=123' );
+            expect( setParam('?dolor=amet&ipsum=5', 'ipsum', 123) ).toEqual( '?dolor=amet&ipsum=123' );
+            expect( setParam('?dolor=amet&ipsum=5&maecennas=ullamcor', 'ipsum', 123) ).toEqual( '?dolor=amet&ipsum=123&maecennas=ullamcor' );
+        });
+
+        it('should work with empty url', function () {
+            expect( setParam('', 'foo', 'bar') ).toEqual( '?foo=bar' );
+            expect( setParam('?', 'foo', 'bar') ).toEqual( '?foo=bar' );
+        });
+
+    });
+
+});

tests/spec/spec-queryString.js

@@ -6,7 +6,8 @@ define([
     'queryString/spec-encode',
     'queryString/spec-getParam',
     'queryString/spec-getQuery',
-    'queryString/spec-parse'
+    'queryString/spec-parse',
+    'queryString/spec-setParam'
 ], function(){
     //noop
 });