qooxdoo--Variant类(配置用)

概述：qx.core.Variant类为qooxdoo框架提供全局的配置，qooxdoo的已有的配置项有client：设置代码运行浏览器,debug：设置代码的运行模式,aspects：设置是否开启方面,dynlocale：动态区域? 。Variant为qooxdoo通过工具根据具体环境设置从一份代码中提取出不同的分支代码提供了基础。所谓具体环境设置就是Variant中的设置值。

Variant
--------------
define(key, allowedValues, defaultValue) 定义一个设置
get(key)
isSet(key, variants)
select(key, variantFunctionMap)
     第二个参数是一个形为{值A:对象B}的Map,如果值A与Variant中key（参数1）的值一致，返回对象B，否则返回variantFunctionMap[default];

/**
 * Manage variants of source code. May it be for different debug options,
 * browsers or other environment flags.
 * [源代码配置]管理。用于设定不同的调试选项、浏览器和其他环境标记。
 * 
 *
 * Variants enable the selection and removal of code from the build version.
 * A variant consists of a collection of states from which exactly one is active
 * at load time of the framework. The global map <code>qxvariants</code> can be
 * used to select a variant before the Framework is loades.
 * [源代码配置]使得从构建版本选定或者移除代码成为可能
 * 一个[源代码配置]由“确切对象：在框架载入时激活”的状态集合组成
 * 全局的map qxvariants用于在框架载入之前选择一个[源代码配置]
 *
 *
 * Depending on the selected variant a specific code
 * path can be choosen using the <code>select</code> method. The generator is
 * able to set a variant and remove all code paths which are
 * not selected by the variant.
 * 一份具体的代码依赖于选择的[源代码配置]
 * 路径可以用select方法选择，generator可以设置一个[源代码配置]和移除所有没有被[源代码配置]选择的代码
 *
 * Variants are used to implement browser optimized builds and to remove
 * debugging code from the build version. It is very similar to conditional
 * compilation in C/C++.
 * [源代码配置]用于实现浏览器最小化构建和从构建版本移除调试代码。它非常像C/C++的条件编绎。
 *
 * Here is a list of pre-defined variant names, the possible values they take,
 * and their system default:
 * 这里是一个清单，包含预定义的[源代码配置]名称、可供设置的值和系统默认值
 * <table>
 *  <tr>
 *  <th>Variant name</th><th>Possible values</th><th>System default</th>
 *  </tr><tr>
 *  <td>qx.client          <td>[ "gecko", "mshtml", "opera", "webkit" ]   <td>&lt;auto-detected&gt;
 *  </tr><tr>
 *  <td>qx.debug                   <td>[ "on", "off" ]                    <td>"on"
 *  </tr><tr>
 *  <td>qx.aspects                 <td>[ "on", "off" ]                    <td>"off"
 *  </tr><tr>
 *  <td>qx.dynlocale     <td>[ "on", "off" ]                    <td>"on"
 *  </tr>
 * </table>
 */
qx.Bootstrap.define("qx.core.Variant",
{
  statics :
  {
    /** {Map} stored variants */
    __variants : {},


    /** {Map} cached results */
    __cache : {},


    /**
     * Pseudo function as replacement for isSet() which will only be handled by the optimizer
     * 替代isSet的假冒方法，仅用于优化程序
     *
     * @return {Boolean}
     */
    compilerIsSet : function() {
      return true;
    },


    /**
     * Define a variant 定义一个[源代码配置]
     *
     * @param key {String} An Unique key for the variant. The key must be prefixed with a
     *   namespace identifier (e.g. <code>"qx.debug"</code>)
     * @param allowedValues {String[]} An array of all allowed values for this variant.
     * @param defaultValue {String} Default value for the variant. Must be one of the values
     *   defined in <code>defaultValues</code>.
     */
    define : function(key, allowedValues, defaultValue)
    {
      if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
      {
        if (!this.__isValidArray(allowedValues)) {
          throw new Error('Allowed values of variant "' + key + '" must be defined!');
        }

        if (defaultValue === undefined) {
          throw new Error('Default value of variant "' + key + '" must be defined!');
        }
      }

      if (!this.__variants[key])
      {
        this.__variants[key] = {};
      }
      else if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
      {
        if (this.__variants[key].defaultValue !== undefined) {
          throw new Error('Variant "' + key + '" is already defined!');
        }
      }

      this.__variants[key].allowedValues = allowedValues;
      this.__variants[key].defaultValue = defaultValue;
    },


    /**
     * Get the current value of a variant.
     * 获取[源代码配置]的当前值
     *
     * @param key {String} name of the variant
     * @return {String} current value of the variant

     */
    get : function(key)
    {
      var data = this.__variants[key];

      if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
      {
        if (data === undefined) {
          throw new Error('Variant "' + key + '" is not defined.');
        }
      }

      if (data.value !== undefined) {
        return data.value;
      }

      return data.defaultValue;
    },


    /**
     * Import settings from global qxvariants into current environment
     * 从全局的qxvariants导入设置到当前环境
     *
     * @return {void}
     */
    __init : function()
    {
      if (window.qxvariants)
      {
        for (var key in qxvariants)
        {
          if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
          {
            if ((key.split(".")).length < 2) {
              throw new Error('Malformed settings key "' + key + '". Must be following the schema "namespace.key".');
            }
          }

          if (!this.__variants[key]) {
            this.__variants[key] = {};
          }

          this.__variants[key].value = qxvariants[key];
        }

        window.qxvariants = undefined;

        try {
          delete window.qxvariants;
        } catch(ex) {};

        this.__loadUrlVariants(this.__variants);
      }
    },


    /**
     * Load variants from URL parameters if the setting <code>"qx.allowUrlSettings"</code>
     * is set to true.
     * 如果qx.allowUrlSettings设定为true,从URL参数载入[源代码配置]
     *
     *
     * The url scheme for variants is: <code>qxvariant:VARIANT_NAME:VARIANT_VALUE</code>.
     */
    __loadUrlVariants : function()
    {
      if (qx.core.Setting.get("qx.allowUrlVariants") != true) {
        return;
      }

      var urlVariants = document.location.search.slice(1).split("&");

      for (var i=0; i<urlVariants.length; i++)
      {
        var variant = urlVariants[i].split(":");
        if (variant.length != 3 || variant[0] != "qxvariant") {
          continue;
        }

        var key = variant[1];
        if (!this.__variants[key]) {
          this.__variants[key] = {};
        }

        this.__variants[key].value = decodeURIComponent(variant[2]);
      }
    },


    /**
     * Select a function depending on the value of the variant.
     * 依据[源代码设置]的值获取一个function
     *
     * Example:
     * 示例
     *
     * <pre class='javascript'>
     * var f = qx.Variant.select("qx.client", {
     *   "gecko": fucntion() { ... },
     *   "mshtml|opera": function() { ... },
     *   "default": function() { ... }
     * });
     * </pre>
     *
     * Depending on the value of the <code>"qx.client"</code> variant whit will select the
     * corresponding function. The first case is selected if the variant is "gecko", the second
     * is selected if the variant is "mshtml" or "opera" and the third function is selected if
     * none of the other keys match the variant. "default" is the default case.
     *
     * @param key {String} name of the variant. To enable the generator to optimize
     *   this selection, the key must be a string literal.
     * @param variantFunctionMap {Map} map with variant names as keys and functions as values.
     * @return {Function} The selected function from the map.
     */
    select : function(key, variantFunctionMap)
    {
      if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
      {
        // WARINING: all changes to this function must be duplicated in the generator!!
        // modules/variantoptimizer.py (processVariantSelect)
        if (!this.__isValidObject(this.__variants[key])) {
          throw new Error("Variant \"" + key + "\" is not defined");
        }

        if (!this.__isValidObject(variantFunctionMap)) {
          throw new Error("the second parameter must be a map!");
        }
      }

      for (var variant in variantFunctionMap)
      {
        if (this.isSet(key, variant)) {
          return variantFunctionMap[variant];
        }
      }

      if (variantFunctionMap["default"] !== undefined) {
        return variantFunctionMap["default"];
      }

      if (qx.core.Variant.compilerIsSet("qx.debug", "on"))
      {
        throw new Error('No match for variant "' + key +
          '" in variants [' + qx.lang.Object.getKeysAsString(variantFunctionMap) +
          '] found, and no default ("default") given');
      }
    },


    /**
     * Check whether a variant is set to a given value. To enable the generator to optimize
     * this selection, both parameters must be string literals.
     * 检查是否[源代码配置]设定为给定的值，使得generator可以优化这个选择，两个参数都必须为字面量
     *
     * This method is meant to be used in if statements to select code paths. If the condition of
     * an if statement is only this method, the generator is able to optimize the if
     * statement.
     * 此方法表达了它被用于if语句选择一个代码路径，如果if语句的条件仅仅是此方法，generator就可优化这个if语句
     *
     * Example:
     *
     * <pre class='javascript'>
     * if (qx.core.Variant.isSet("qx.client", "mshtml")) {
     *   // some Internet Explorer specific code
     * } else if(qx.core.Variant.isSet("qx.client", "opera")){
     *   // Opera specific code
     * } else {
     *   // common code for all other browsers
     * }
     * </pre>
     *
     * @param key {String} name of the variant
     * @param variants {String} value to check for. Several values can be "or"-combined by separating
     *   them with a "|" character. A value of "mshtml|opera" would for example check if the variant is
     *   set to "mshtml" or "opera"
     * @return {Boolean} whether the variant is set to the given value
     */
    isSet : function(key, variants)
    {
      var access = key + "$" + variants;
      if (this.__cache[access] !== undefined) {
        return this.__cache[access];
      }

      var retval = false;

      // fast path
      if (variants.indexOf("|") < 0)
      {
        retval = this.get(key) === variants;
      }
      else
      {
        var keyParts = variants.split("|");

        for (var i=0, l=keyParts.length; i<l; i++)
        {
          if (this.get(key) === keyParts[i])
          {
            retval = true;
            break;
          }
        }
      }

      this.__cache[access] = retval;
      return retval;
    },


    /**
     * Whether a value is a valid array. Valid arrays are:
     *
     * * type is object
     * * instance is Array
     *
     * @name __isValidArray
     * @param v {var} the value to validate.
     * @return {Boolean} whether the variable is valid
     */
    __isValidArray : function(v) {
      return typeof v === "object" && v !== null && v instanceof Array;
    },


    /**
     * Whether a value is a valid object. Valid object are:
     *
     * * type is object
     * * instance != Array
     *
     * @name __isValidObject
     * @param v {var} the value to validate.
     * @return {Boolean} whether the variable is valid
     */
    __isValidObject : function(v) {
      return typeof v === "object" && v !== null && !(v instanceof Array);
    },


    /**
     * Whether the array contains the given element
     *
     * @name __arrayContains
     * @param arr {Array} the array
     * @param obj {var} object to look for
     * @return {Boolean} whether the array contains the element
     */
    __arrayContains : function(arr, obj)
    {
      for (var i=0, l=arr.length; i<l; i++)
      {
        if (arr[i] == obj) {
          return true;
        }
      }

      return false;
    }
  },




  /*
  *****************************************************************************
     DEFER
  *****************************************************************************
  */

  defer : function(statics)
  {
    statics.define("qx.client", [ "gecko", "mshtml", "opera", "webkit" ], qx.bom.client.Engine.NAME);
    statics.define("qx.debug", [ "on", "off" ], "on");
    statics.define("qx.aspects", [ "on", "off" ], "off");
    statics.define("qx.dynlocale", [ "on", "off" ], "on");

    statics.__init();
  }
});