v1.2.0: Add setUnescaped and pushUnescaped methods.

These methods will unescape HTML entities in the given value, if it's a string. This allows for easier bootstrapping of data in templates.

.travis.yml

@@ -0,0 +1,4 @@
+language: node_js
+node_js:
+   - "0.11"
+   - "0.10"

README.md

@@ -5,7 +5,11 @@ A simple front-end parameters manager for specifying global script parameters.
 
 ## Usage
 
-Include [`params.js`](https://github.com/droptype/params/releases/tag/v1.0.0) in the page and initialize a parameters object.
+Include [`params.js`](https://github.com/droptype/params/releases/tag/v1.2.0)
+in the page and initialize a Params object. Or, include the
+`params-1.2.0-min.html` HTML fragment, which initializes a Params instance
+under `window.params`. (It’s also slightly smaller, omitting features that
+are unnecessary if there‘s only one instance.)
 
 ```javascript
 params = new Params()
@@ -107,3 +111,18 @@ params = new Params()
     true
     ```
 
+*   Set and unescape a parameter:
+
+    ```javascript
+    > params.setUnescaped('title', 'Green Eggs & Ham')
+    > params.title
+    'Green Eggs & Ham'
+    ```
+
+*   Push and unescape a parameter:
+
+    ```javascript
+    > params.pushUnescaped('tags', '<br>').pushUnescaped('tags', '<p>')
+    > params.tags
+    ['<br>', '<p>']
+    ```

package.json

@@ -1,6 +1,6 @@
 {
     "name": "params",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "",
     "dependencies": {
     },

source/params.coffee

@@ -2,7 +2,23 @@
 Parameters manager - https://github.com/droptype/params
 ###
 
-INTERNAL = ['set', 'getAll', '_strict']
+INTERNAL = ['set', 'getAll', 'push', 'setUnescaped', 'pushUnescaped', '_strict']
+
+# Unescape helper, adapted from [Underscore](http://underscorejs.org).
+entities =
+  '&'   : '&'
+  '&lt;'    : '<'
+  '&gt;'    : '>'
+  '&quot;'  : '"'
+  '&#x27;'  : '\''
+exp = new RegExp('(&amp;|&lt;|&gt;|&quot;|&#x27;)', 'g')
+_unescapeHTML = (data_str) ->
+    unless data_str
+        return ''
+    return data_str.replace exp, (match) ->
+        return entities[match]
+
+
 
 class Params
 
@@ -18,13 +34,20 @@ class Params
     # value  - an arbitrary value to set
     # kwargs - an object of optional arguments
     #          push - a Boolean indicating the key is should be set to an Array
+    #          unescape - a Boolean indicating the value should have HTML
+    #            entities unescaped first.
     #
     # Returns self for chaining.
     set: (key, value, kwargs={}) =>
 
         if key in INTERNAL
             throw new Error("Cannot set the '#{ key }' param, silly.")
 
+        if kwargs.unescape
+            unless typeof value is 'string'
+                throw new Error('Cannot unescape non-string values')
+            value = _unescapeHTML(value)
+
         key_list = key.split('.')
         target_obj = this
         prev_key = null
@@ -61,8 +84,14 @@ class Params
 
         return this
 
+    # Public: shortcut for `set` with `unescape: true`.
+    # 
+    # Returns self for chaining.
+    setUnescaped: (key, value) =>
+        return @set(key, value, unescape: true)
 
-    # Public: push a parameter. If they key is not already set, it will be created.
+    # Public: push a parameter. If they key is not already set, it will be
+    #           created. Shortcut for `set` with `push: true`.
     #
     # key    - a String key to set. MAY use dot notation to specify sub parameters.
     # value  - an arbitrary value to set
@@ -71,6 +100,11 @@ class Params
     push: (key, value) =>
         return @set(key, value, push: true)
 
+    # Public: shortcut for `set` with `push: true, unescape: true`.
+    # 
+    # Returns self for chaining.
+    pushUnescaped: (key, value) =>
+        return @set(key, value, push: true, unescape: true)
 
     # Public: get all of the parameters. Used to avoid getting the internal
     # properties as well.

test/test.coffee

@@ -45,6 +45,9 @@ describe 'Params', ->
         params = new Params()
         (-> params.set('set', 1)).should.throw()
         (-> params.set('getAll', 1)).should.throw()
+        (-> params.set('push', 1)).should.throw()
+        (-> params.set('setUnescaped', 1)).should.throw()
+        (-> params.set('pushUnescaped', 1)).should.throw()
         (-> params.set('_strict', 1)).should.throw()
 
     it 'should push a parameter', ->
@@ -72,24 +75,32 @@ describe 'Params', ->
         (-> params.push('key.foo.bar', 1)).should.throw("Cannot push subparameter 'foo.bar'. 'foo' is not an Array.")
         params.key.foo.should.equal(1)
 
+    it 'should set parameters as escaped', ->
+        params = new Params()
+        params.set('key.subkey', '<')
+        params.key.subkey.should.equal('<')
 
-# params = new Params()
-
-# console.log params.getAll()
-
-# params.set('foo', 'a').set('Bar', 1234)
-
-# console.log params.getAll()
-
-# params.set('foo', 9)
-
-# console.log params.getAll()
+    it 'should unescape parameters when using setUnescaped', ->
+        params = new Params()
+        params.setUnescaped('key', '<')
+        params.key.should.equal('<')
 
+    it 'should push parameters as escaped', ->
+        params = new Params()
+        params.push('key.subkey', '&lt;')
+        params.key.subkey.should.eql(['&lt;'])
 
-# params.set('asdf.asdf.asdf', 9)
+    it 'should unescape parameters when using pushUnescaped', ->
+        params = new Params()
+        params.pushUnescaped('key', '&lt;')
+        params.key.should.eql(['<'])
 
-# console.log params.getAll()
+    it 'should allow for a mix of push and pushUnescaped', ->
+        params = new Params()
+        params.push('key', '&lt;script&gt;')
+        params.pushUnescaped('key', '&lt;script&gt;')
+        params.key.should.eql(['&lt;script&gt;', '<script>'])
 
-# params.set('foo.bar', 9)
-# console.log params.getAll()
-# console.log params.foo
+    it 'should not unescape a parameter if the value is not a string', ->
+        params = new Params()
+        (-> params.setUnescaped('key.foo', 1)).should.throw("Cannot unescape non-string values")