/**
 * This module is a REST client.
 * @module gallery-yql-rest-client
 */

(function (Y) {
    'use strict';
    
    var _lang = Y.Lang,
        
        _each = Y.each,
        _execute = Y.YQL.execute,
        _getResult = _execute.getResult,
        _isArray = _lang.isArray,
        _isObject = _lang.isObject,
        _quotedString,
        _stringify = Y.QueryString.stringify;
    
    /**
     * @class YQLRESTClient
     * @static
     */
    Y.YQLRESTClient = {
        /**
         * Sends a REST request.
         * @method request
         * @param {Object} params Request parameters object.
         * <dl>
         *     <dt>
         *         accept
         *     </dt>
         *     <dd>
         *         Specifies the type of content to send in the response using
         *         the Accept HTTP header.  This tells YQL what kind of data
         *         format you want returned, as well as how to parse it.
         *     </dd>
         *     <dt>
         *         content
         *     </dt>
         *     <dd>
         *         The body content of a POST or PUT request.  This can be an
         *         object or a string.  If an object is used, contentType is
         *         assumed to be application/x-www-form-urlencoded.
         *     </dd>
         *     <dt>
         *         contentType
         *     </dt>
         *     <dd>
         *         Specifies the content-type of the body content of a POST or
         *         PUT request.
         *     </dd>
         *     <dt>
         *         fallbackCharsets
         *     </dt>
         *     <dd>
         *         Overrides the list of fallback character sets, which is set
         *         to "utf-8, iso-8859-1" by default, for decoding the returned
         *         response. YQL attempts to decode the response using the
         *         character sets listed here when the response either does not
         *         specify the character set or specifies an incorrect character
         *         set that results in a failed decoding.  This value may be an
         *         array of strings or one string with comma separated values.
         *     </dd>
         *     <dt>
         *         forceCharset
         *     </dt>
         *     <dd>
         *         Forces YQL to use the character set specified. Using this
         *         overrides both the character set specified by the response
         *         and the fallback character sets. 
         *     </dd>
         *     <dt>
         *         headers
         *     </dt>
         *     <dd>
         *         Adds HTTP headers to the request.
         *     </dd>
         *     <dt>
         *         jsonCompat
         *     </dt>
         *     <dd>
         *         Set this value to 'new' to get "lossless" JSON when making a
         *         REST call to a Web service.  jsonCompat: 'new' must also be
         *         set in the yqlParams object.
         *     </dd>
         *     <dt>
         *         matrix
         *     </dt>
         *     <dd>
         *         Adds matrix parameters to the request. 
         *     </dd>
         *     <dt>
         *         method
         *     </dt>
         *     <dd>
         *         The HTTP method to use.  Must be one of 'DELETE', 'GET',
         *         'HEAD', 'POST' or 'PUT'.
         *     </dd>
         *     <dt>
         *         paths
         *     </dt>
         *     <dd>
         *         Array of paths to append to the url.
         *     </dd>
         *     <dt>
         *         query
         *     </dt>
         *     <dd>
         *         Query parameters to add to the request.
         *     </dd>
         *     <dt>
         *         timeout
         *     </dt>
         *     <dd>
         *         Specifies the request timeout in milliseconds. This is useful
         *         when you want to cancel requests that take longer than
         *         expected. 
         *     </dd>
         *     <dt>
         *         url
         *     </dt>
         *     <dd>
         *         Provides a URL endpoint to query.
         *     </dd>
         * </dl>
         * @param {Function} callbackFunction The response object is the only
         * parameter.
         * @param {Object} yqlParams (optional) Passes through to Y.YQL.
         * @param {Object} yqlOpts (optional) Passes through to Y.YQL.
         */
        request: function (params, callbackFunction, yqlParams, yqlOpts) {
            params = params || {};
            
            var accept = params.accept,
                code = [],
                content = params.content,
                contentType = params.contentType,
                fallbackCharsets = params.fallbackCharsets,
                forceCharset = params.forceCharset,
                headers = params.headers,
                jsonCompat = params.jsonCompat,
                matrix = params.matrix,
                method = params.method,
                paths = params.paths,
                query = params.query,
                timeout = params.timeout,
                url = params.url;
            
            if (!method || !url) {
                throw 'Request requires a url and a method.';
            }
            
            code.push('response.object = y.rest("' + _quotedString(params.url) + '")');
            
            if (accept) {
                code.push('accept("' + _quotedString(accept) + '")');
            }
            
            if (_isObject(content)) {
                content = _stringify(content);
                contentType = 'application/x-www-form-urlencoded';
            }
            
            if (contentType) {
                code.push('contentType("' + _quotedString(contentType) + '")');
            }
            
            if (fallbackCharsets) {
                code.push('fallbackCharset("' + _quotedString(_isArray(fallbackCharsets) ? fallbackCharsets.join(',') : fallbackCharsets) + '")');
            }
            
            if (forceCharset) {
                code.push('forceCharset("' + _quotedString(forceCharset) + '")');
            }
            
            if (headers) {
                _each(headers, function (value, key) {
                    code.push('header("' + _quotedString(key) + '", "' + _quotedString(value) + '")');
                });
            }
            
            if (jsonCompat) {
                code.push('jsonCompat("' + _quotedString(jsonCompat) + '")');
            }
            
            if (matrix) {
                _each(matrix, function (value, key) {
                    code.push('matrix("' + _quotedString(key) + '", "' + _quotedString(value) + '")');
                });
            }
            
            if (paths) {
                _each(paths, function (value) {
                    code.push('path("' + _quotedString(value) + '")');
                });
            }
            
            if (query) {
                _each(query, function (value, key) {
                    code.push('query("' + _quotedString(key) + '", "' + _quotedString(value) + '")');
                });
            }
            
            if (timeout) {
                code.push('timeout("' + _quotedString(timeout) + '")');
            }
            
            switch (method) {
                case 'delete':
                    method = 'del';
                    // fall through
                case 'get':
                case 'head':
                    code.push(method + '()');
                    break;
                case 'post':
                case 'put':
                    code.push(method + '("' + _quotedString(content) + '")');
                    break;
                default:
                    throw 'Unknown method.';
            }
            
            _execute(code.join('.') + ';', function (result) {
                callbackFunction(_getResult(result));
            }, yqlParams, yqlOpts);
        }
    };
    
    /**
     * Escapes " characters.
     * @method _quotedString
     * @param {String} string
     * @private
     * @returns {String}
     */
    _quotedString = function (string) {
        return String(string || '').replace(/"/g, '\\"');
    };
}(Y));