home *** CD-ROM | disk | FTP | other *** search
/ Freelog 112 / FreelogNo112-NovembreDecembre2012.iso / Multimedia / Songbird / Songbird_2.0.0-2311_windows-i686-msvc8.exe / jsmodules / StringUtils.jsm < prev    next >
Text File  |  2012-06-08  |  22KB  |  667 lines
  1. /* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* vim: set sw=2 :miv */
  3. /*
  4. //
  5. // BEGIN SONGBIRD GPL
  6. //
  7. // This file is part of the Songbird web player.
  8. //
  9. // Copyright(c) 2005-2009 POTI, Inc.
  10. // http://songbirdnest.com
  11. //
  12. // This file may be licensed under the terms of of the
  13. // GNU General Public License Version 2 (the "GPL").
  14. //
  15. // Software distributed under the License is distributed
  16. // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
  17. // express or implied. See the GPL for the specific language
  18. // governing rights and limitations.
  19. //
  20. // You should have received a copy of the GPL along with this
  21. // program. If not, go to http://www.gnu.org/licenses/gpl.html
  22. // or write to the Free Software Foundation, Inc.,
  23. // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  24. //
  25. // END SONGBIRD GPL
  26. //
  27. */
  28.  
  29. /**
  30.  * \file  StringUtils.jsm
  31.  * \brief Javascript source for the string utility services.
  32.  */
  33.  
  34. //------------------------------------------------------------------------------
  35. //
  36. // String utility JSM configuration.
  37. //
  38. //------------------------------------------------------------------------------
  39.  
  40. EXPORTED_SYMBOLS = [ "SBString",
  41.                      "SBBrandedString",
  42.                      "SBFormattedString",
  43.                      "SBBrandedFormattedString",
  44.                      "SBFormattedCountString",
  45.                      "SBStringBrandShortName",
  46.                      "SBStringGetDefaultBundle",
  47.                      "SBStringGetBrandBundle",
  48.                      "SBStringBundle",
  49.                      "StringSet" ];
  50.  
  51.  
  52. //------------------------------------------------------------------------------
  53. //
  54. // String utility defs.
  55. //
  56. //------------------------------------------------------------------------------
  57.  
  58. const Cc = Components.classes;
  59. const Ci = Components.interfaces;
  60. const Cr = Components.results
  61.  
  62.  
  63. //------------------------------------------------------------------------------
  64. //
  65. // String utility globals.
  66. //
  67. //------------------------------------------------------------------------------
  68.  
  69. var gSBStringDefaultBundle = null;
  70. var gSBStringBrandBundle = null;
  71.  
  72.  
  73. //------------------------------------------------------------------------------
  74. //
  75. // String utility localization services.
  76. //
  77. //------------------------------------------------------------------------------
  78.  
  79. /**
  80.  *   Get and return the localized string with the key specified by aKey using
  81.  * the string bundle specified by aStringBundle.  If the string cannot be found,
  82.  * return the default string specified by aDefault; if aDefault is not
  83.  * specified or is null, return aKey.
  84.  *   If aStringBundle is not specified, use the main Songbird string bundle.
  85.  *
  86.  * \param aKey                  Localized string key.
  87.  * \param aDefault              Optional default string.
  88.  * \param aStringBundle         Optional string bundle.
  89.  *
  90.  * \return                      Localized string.
  91.  */
  92.  
  93. function SBString(aKey, aDefault, aStringBundle) {
  94.   // Use default Songbird string bundle utility object if no bundle specified.
  95.   if (!aStringBundle)
  96.     return SBStringGetDefaultBundle().get(aKey, aDefault);
  97.  
  98.   // Set the default value.
  99.   var value = aKey;
  100.   if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  101.     value = aDefault;
  102.  
  103.   // Try getting the string from the bundle.
  104.   try {
  105.     value = aStringBundle.GetStringFromName(aKey);
  106.   } catch(ex) {}
  107.  
  108.   return value;
  109. }
  110.  
  111.  
  112. /**
  113.  *   Get and return the localized, branded string with the bundle key specified
  114.  * by aKey using the string bundle specified by aStringBundle.  If the string
  115.  * cannot be found, return the string specified by aDefault; if aDefault is not
  116.  * specified, return aKey.
  117.  *   If aStringBundle is not specified, use the main Songbird string bundle.
  118.  *   The bundle string will be treated as a formatted string, and the first
  119.  * parameter will be set to the brand short name string.
  120.  *
  121.  * \param aKey                  String bundle key.
  122.  * \param aDefault              Default string value.
  123.  * \param aStringBundle         Optional string bundle.
  124.  *
  125.  * \return                      Localized string.
  126.  */
  127.  
  128. function SBBrandedString(aKey, aDefault, aStringBundle) {
  129.   return SBFormattedString(aKey,
  130.                            [ SBStringBrandShortName() ],
  131.                            aDefault,
  132.                            aStringBundle);
  133. }
  134.  
  135.  
  136. /**
  137.  *   Get the formatted localized string with the key specified by aKey using the
  138.  * format parameters specified by aParams and the string bundle specified by
  139.  * aStringBundle.  If the string cannot be found, return the default string
  140.  * specified by aDefault; if aDefault is not specified or is null, return aKey.
  141.  *   If no string bundle is specified, get the string from the Songbird bundle.
  142.  * If a string cannot be found, return aKey.
  143.  *
  144.  * \param aKey                  Localized string key.
  145.  * \param aParams               Format params array.
  146.  * \param aDefault              Optional default string.
  147.  * \param aStringBundle         Optional string bundle.
  148.  *
  149.  * \return                      Localized string.
  150.  */
  151.  
  152. function SBFormattedString(aKey, aParams, aDefault, aStringBundle) {
  153.   // Use default Songbird string bundle utility object if no bundle specified.
  154.   if (!aStringBundle)
  155.     return SBStringGetDefaultBundle().format(aKey, aParams, aDefault);
  156.  
  157.   // Set the default value.
  158.   var value = aKey;
  159.   if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  160.     value = aDefault;
  161.  
  162.   // Try formatting string from bundle.
  163.   try {
  164.     value = aStringBundle.formatStringFromName(aKey, aParams, aParams.length);
  165.   } catch(ex) {}
  166.  
  167.   return value;
  168. }
  169.  
  170.  
  171. /**
  172.  *   Get the branded, formatted localized string with the key specified by aKey
  173.  * using the format parameters specified by aParams and the string bundle
  174.  * specified by aStringBundle.  If the string cannot be found, return the
  175.  * default string specified by aDefault; if aDefault is not specified, return
  176.  * aKey.
  177.  *   If no string bundle is specified, get the string from the Songbird bundle.
  178.  * If a string cannot be found, return aKey.
  179.  *   The brand short name string will be appended to the formatted string
  180.  * parameter list.
  181.  *
  182.  * \param aKey                  Localized string key.
  183.  * \param aParams               Format params array.
  184.  * \param aStringBundle         Optional string bundle.
  185.  * \param aDefault              Optional default string.
  186.  *
  187.  * \return                      Localized string.
  188.  */
  189.  
  190. function SBBrandedFormattedString(aKey, aParams, aDefault, aStringBundle) {
  191.   return SBFormattedString(aKey,
  192.                            aParams.concat(SBStringBrandShortName()),
  193.                            aDefault,
  194.                            aStringBundle);
  195. }
  196.  
  197.  
  198. /**
  199.  *   Get and return the formatted localized count string with the key base
  200.  * specified by aKeyBase using the count specified by aCount.  If the count is
  201.  * one, get the string using the singular string key; otherwise, get the
  202.  * formatted string using the plural string key and count.
  203.  *   The singular string key is the key base with the suffix "_1".  The plural
  204.  * string key is the key base with the suffix "_n".
  205.  *   Use the format parameters specified by aParams.  If aParams is not
  206.  * specified, use the count as the single format parameter.
  207.  *   Use the string bundle specified by aStringBundle.  If the string bundle is
  208.  * not specified, use the main Songbird string bundle.
  209.  *   If the string cannot be found, return the default string specified by
  210.  * aDefault; if aDefault is not specified or is null, return aKeyBase.
  211.  *
  212.  * \param aKeyBase              Localized string key base.
  213.  * \param aCount                Count value for string.
  214.  * \param aParams               Format params array.
  215.  * \param aDefault              Optional default string.
  216.  * \param aStringBundle         Optional string bundle.
  217.  *
  218.  * \return                      Localized string.
  219.  */
  220.  
  221. function SBFormattedCountString(aKeyBase,
  222.                                 aCount,
  223.                                 aParams,
  224.                                 aDefault,
  225.                                 aStringBundle) {
  226.   // Use default Songbird string bundle utility object if no bundle specified.
  227.   if (!aStringBundle) {
  228.     return SBStringGetDefaultBundle().formatCountString(aKeyBase,
  229.                                                         aCount,
  230.                                                         aParams,
  231.                                                         aDefault);
  232.   }
  233.  
  234.   // Get the format parameters.
  235.   var params;
  236.   if (aParams)
  237.     params = aParams;
  238.   else
  239.     params = [ aCount ];
  240.  
  241.   // Produce the string key.
  242.   var key = aKeyBase;
  243.   if (aCount == 1)
  244.     key += "_1";
  245.   else
  246.     key += "_n";
  247.  
  248.   // Set the default value.
  249.   var value = aKeyBase;
  250.   if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  251.     value = aDefault;
  252.  
  253.   // Try formatting the string from the bundle.
  254.   try {
  255.     value = aStringBundle.formatStringFromName(key, params, params.length);
  256.   } catch(ex) {}
  257.  
  258.   return value;
  259. }
  260.  
  261.  
  262. /**
  263.  * Return the Songbird brand short name localized string.
  264.  *
  265.  * \return Songbird brand short name.
  266.  */
  267.  
  268. function SBStringBrandShortName() {
  269.   return SBString("brandShortName", "Songbird", SBStringGetBrandBundle());
  270. }
  271.  
  272.  
  273. //------------------------------------------------------------------------------
  274. //
  275. // Internal string utility services.
  276. //
  277. //------------------------------------------------------------------------------
  278.  
  279. /**
  280.  * Return the default Songbird string bundle utility object.
  281.  *
  282.  * \return Default Songbird string bundle utility object.
  283.  */
  284.  
  285. function SBStringGetDefaultBundle() {
  286.   if (!gSBStringDefaultBundle)
  287.     gSBStringDefaultBundle = new SBStringBundle();
  288.  
  289.   return gSBStringDefaultBundle;
  290. }
  291.  
  292.  
  293. /**
  294.  * Return the Songbird branding localized string bundle.
  295.  *
  296.  * \return Songbird branding localized string bundle.
  297.  */
  298.  
  299. function SBStringGetBrandBundle() {
  300.   if (!gSBStringBrandBundle) {
  301.     gSBStringBrandBundle =
  302.       Cc["@mozilla.org/intl/stringbundle;1"]
  303.         .getService(Ci.nsIStringBundleService)
  304.         .createBundle("chrome://branding/locale/brand.properties");
  305.   }
  306.  
  307.   return gSBStringBrandBundle;
  308. }
  309.  
  310.  
  311. //------------------------------------------------------------------------------
  312. //
  313. // Songbird string bundle utility object.
  314. //
  315. //   The Songbird string bundle utility object provides an expanded set of
  316. // string bundle services.  In particular, this object allows string bundles to
  317. // include other string bundles and to include bundle strings in other bundle
  318. // strings.
  319. //   To include one or more string bundles in a top-level string bundle, define
  320. // the string "include_bundle_list" in the top-level bundle.  This string should
  321. // consist of a comma separated list of included string bundle URI's.  When
  322. // the Songbird string bundle utility object looks up a string, it will look in
  323. // the top-level string bundle and all included string bundles.  The included
  324. // string bundles can include additional string bundles too.
  325. //   To include a bundle string in another bundle string, encapsulate the
  326. // included bundle string in "&" and ";", much like XML entities.  Use "&"
  327. // for a literal "&".
  328. //
  329. // Example:
  330. //
  331. // include_bundle_list=chrome://bundles1.properties,chrome://bundle2.properties
  332. //
  333. // string1=World
  334. // string2=Hello &string1; & Everyone Else
  335. //
  336. // string2 evaluates to "Hello World & Everyone Else".
  337. //
  338. //------------------------------------------------------------------------------
  339.  
  340. /**
  341.  *   Construct a Songbird string bundle utility object using the base string
  342.  * bundle specified by aBundle.  If aBundle is a string, it is treated as a
  343.  * URI for a string bundle; otherwise, it is treated as a string bundle object.
  344.  * If aBundle is not specified, the default Songbird string bundle is used.
  345.  *
  346.  *   ==> aBundle                Base string bundle.
  347.  */
  348.  
  349. function SBStringBundle(aBundle)
  350. {
  351.   // Get the string bundle service. */
  352.   this._stringBundleService = Cc["@mozilla.org/intl/stringbundle;1"]
  353.                                 .getService(Ci.nsIStringBundleService);
  354.  
  355.   // Use the default Songbird string bundle if none specified.
  356.   if (!aBundle)
  357.     aBundle = "chrome://songbird/locale/songbird.properties";
  358.  
  359.   // Initialize the bundle list.
  360.   this._bundleList = [];
  361.  
  362.   // Load the string bundle.
  363.   this._loadBundle(aBundle);
  364. }
  365.  
  366. // Define the class.
  367. SBStringBundle.prototype = {
  368.   // Set the constructor.
  369.   constructor: SBStringBundle,
  370.  
  371.   //
  372.   // Songbird string bundle utility object fields.
  373.   //
  374.   //   _stringBundleService     String bundle service object.
  375.   //   _bundleList              List of string bundles.
  376.   //
  377.  
  378.   _stringBundleService: null,
  379.   _bundleList: null,
  380.  
  381.  
  382.   /**
  383.    *   Get and return the string with the bundle key specified by aKey.  If the
  384.    * string cannot be found, return the string specified by aDefault; if
  385.    * aDefault is not specified or is null, return aKey.
  386.    *
  387.    * \param aKey                  String bundle key.
  388.    * \param aDefault              Default string value.
  389.    *
  390.    * \return                      Bundle string.
  391.    */
  392.  
  393.   get: function SBStringBundle_get(aKey, aDefault) {
  394.     // Set the default string value.
  395.     var value = aKey;
  396.     if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  397.       value = aDefault;
  398.  
  399.     // Get the string from the bundle list.
  400.     for (var i = 0; i < this._bundleList.length; i++) {
  401.       var bundle = this._bundleList[i];
  402.       try {
  403.         value = bundle.GetStringFromName(aKey);
  404.         break;
  405.       } catch (ex) {}
  406.     }
  407.  
  408.     // Apply string substitutions.
  409.     value = this._applySubstitutions(value);
  410.  
  411.     return value;
  412.   },
  413.  
  414.  
  415.   /**
  416.    *   Get and return the formatted string with the bundle key specified by aKey
  417.    * and the parameters specified by aParams.  If the string cannot be found,
  418.    * return the string specified by aDefault; if aDefault is not specified or is
  419.    * null, return aKey.
  420.    *
  421.    * \param aKey                  String bundle key.
  422.    * \param aParams               Bundle string format parameters.
  423.    * \param aDefault              Default string value.
  424.    *
  425.    * \return                      Bundle string.
  426.    */
  427.  
  428.   format: function SBStringBundle_format(aKey, aParams, aDefault) {
  429.     // Set the default string value.
  430.     var value = aKey;
  431.     if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  432.       value = aDefault;
  433.  
  434.     // Get the string from the bundle list.
  435.     for (var i = 0; i < this._bundleList.length; i++) {
  436.       var bundle = this._bundleList[i];
  437.       try {
  438.         value = bundle.formatStringFromName(aKey, aParams, aParams.length);
  439.         break;
  440.       } catch (ex) {}
  441.     }
  442.  
  443.     // Apply string substitutions.
  444.     value = this._applySubstitutions(value);
  445.  
  446.     return value;
  447.   },
  448.  
  449.  
  450.   /**
  451.    *   Get and return the formatted count string with the key base specified by
  452.    * aKeyBase using the count specified by aCount.  If the count is one, get the
  453.    * string using the singular string key; otherwise, get the formatted string
  454.    * using the plural string key and count.
  455.    *   The singular string key is the key base with the suffix "_1".  The plural
  456.    * string key is the key base with the suffix "_n".
  457.    *   Use the format parameters specified by aParams.  If aParams is not
  458.    * specified, use the count as the single format parameter.
  459.    *   If the string cannot be found, return the default string specified by
  460.    * aDefault; if aDefault is not specified or is null, return aKeyBase.
  461.    *
  462.    * \param aKeyBase              String bundle key base.
  463.    * \param aCount                Count value for string.
  464.    * \param aParams               Format params array.
  465.    * \param aDefault              Default string value.
  466.    *
  467.    * \return                      Bundle string.
  468.    */
  469.  
  470.   formatCountString: function SBStringBundle_formatCountString(aKeyBase,
  471.                                                                aCount,
  472.                                                                aParams,
  473.                                                                aDefault) {
  474.     // Get the format parameters.
  475.     var params;
  476.     if (aParams)
  477.       params = aParams;
  478.     else
  479.       params = [ aCount ];
  480.  
  481.     // Produce the string key.
  482.     var key = aKeyBase;
  483.     if (aCount == 1)
  484.       key += "_1";
  485.     else
  486.       key += "_n";
  487.  
  488.     // Set the default string value.
  489.     var value = aKeyBase;
  490.     if ((typeof(aDefault) != "undefined") && (aDefault !== null))
  491.       value = aDefault;
  492.  
  493.     // Get the string from the bundle list.
  494.     for (var i = 0; i < this._bundleList.length; i++) {
  495.       var bundle = this._bundleList[i];
  496.       try {
  497.         value = bundle.formatStringFromName(key, params, params.length);
  498.         break;
  499.       } catch (ex) {}
  500.     }
  501.  
  502.     // Apply string substitutions.
  503.     value = this._applySubstitutions(value);
  504.  
  505.     return value;
  506.   },
  507.  
  508.  
  509.   //----------------------------------------------------------------------------
  510.   //
  511.   // Internal Songbird string bundle utility object services.
  512.   //
  513.   //----------------------------------------------------------------------------
  514.  
  515.   /**
  516.    *   Load the string bundle specified by aBundle and all of its included
  517.    * bundles.  If aBundle is a string, it is treated as a URI for the string
  518.    * bundle; otherwise, it is treated as a string bundle object.
  519.    *
  520.    *   ==> aBundle              Bundle to load.
  521.    */
  522.  
  523.   _loadBundle: function SBStringBundle__loadBundle(aBundle) {
  524.     var bundle = aBundle;
  525.  
  526.     // If the bundle is specified as a URI spec string, create a bundle from it.
  527.     if (typeof(bundle) == "string")
  528.       bundle = this._stringBundleService.createBundle(bundle);
  529.  
  530.     // Add the string bundle to the list of string bundles.
  531.     this._bundleList.push(bundle);
  532.  
  533.     // Get the list of included string bundles.
  534.     var includeBundleList;
  535.     try {
  536.       includeBundleList =
  537.         bundle.GetStringFromName("include_bundle_list").split(",");
  538.     } catch (ex) {
  539.       includeBundleList = [];
  540.     }
  541.  
  542.     // Load each of the included string bundles.
  543.     for (var i = 0; i < includeBundleList.length; i++) {
  544.         this._loadBundle(includeBundleList[i]);
  545.     }
  546.   },
  547.  
  548.  
  549.   /*
  550.    * Apply any string bundle substitutions to the string specified by aString.
  551.    *
  552.    * \param aString               String to which to apply substitutions.
  553.    */
  554.  
  555.   _applySubstitutions: function SBStringBundle__applySubstitutions(aString) {
  556.     // Set up a replacement function.
  557.     var _this = this;
  558.     var replaceFunc = function(aMatch, aKey) {
  559.       if (aKey == "amp")
  560.         return "&";
  561.       return _this.get(aKey, "");
  562.     }
  563.  
  564.     // Apply all string substitutions and return result.
  565.     return aString.replace(/&([^&;]*);/g, replaceFunc);
  566.   }
  567. };
  568.  
  569.  
  570. //------------------------------------------------------------------------------
  571. //
  572. // Songbird string set utility object.
  573. //
  574. //   A string set is a string containing a set of strings, separated by a
  575. // delimiter (e.g., " ").  A string set does not contain duplicates.  A string
  576. // set could be used, for example, with the class attribute of a DOM element.
  577. //
  578. //------------------------------------------------------------------------------
  579.  
  580. var StringSet = {
  581.   /**
  582.    * Add the string specified by aString to the string set specified by
  583.    * aStringSet using the delimiter specified by aDelimiter.  If aDelimiter is
  584.    * not specified, use " ".  Return resulting string set.
  585.    *
  586.    * \param aStringSet          String set to which to add string.
  587.    * \param aString             String to add to string set.
  588.    * \param aDelimiter          String set delimiter.  Defaults to " ".
  589.    *
  590.    * \return                    New string set.
  591.    */
  592.  
  593.   add: function StringSet_add(aStringSet, aString, aDelimiter) {
  594.     // Get the delimiter.
  595.     var delimiter = aDelimiter;
  596.     if (!delimiter)
  597.       delimiter = " ";
  598.  
  599.     // Split the string set into an array and add string if it's not already
  600.     // present.
  601.     var stringSet = aStringSet.split(delimiter);
  602.     if (stringSet.indexOf(aString) < 0)
  603.       stringSet.push(aString);
  604.  
  605.     // Return new string set.
  606.     return stringSet.join(delimiter);
  607.   },
  608.  
  609.  
  610.   /**
  611.    * Remove the string specified by aString from the string set specified by
  612.    * aStringSet using the delimiter specified by aDelimiter.  If aDelimiter is
  613.    * not specified, use " ".  Return resulting string set.
  614.    *
  615.    * \param aStringSet          String set from which to remove string.
  616.    * \param aString             String to remove from string set.
  617.    * \param aDelimiter          String set delimiter.  Defaults to " ".
  618.    *
  619.    * \return                    New string set.
  620.    */
  621.  
  622.   remove: function StringSet_remove(aStringSet, aString, aDelimiter) {
  623.     // Get the delimiter.
  624.     var delimiter = aDelimiter;
  625.     if (!delimiter)
  626.       delimiter = " ";
  627.  
  628.     // Split the string set into an array and remove all instances of the
  629.     // string.
  630.     var stringSet = aStringSet.split(delimiter);
  631.     var stringCount = stringSet.length;
  632.     for (var i = stringCount - 1; i >= 0; i--) {
  633.       if (stringSet[i] == aString)
  634.         stringSet.splice(i, 1);
  635.     }
  636.  
  637.     // Return new string set.
  638.     return stringSet.join(delimiter);
  639.   },
  640.  
  641.  
  642.   /**
  643.    * Return true if the string specified by aString is contained in the string
  644.    * set specified by aStringSet using the delimiter specified by aDelimiter.
  645.    * If aDelimiter is not specified, use " ".
  646.    *
  647.    * \param aStringSet          String set to check.
  648.    * \param aString             String for which to check.
  649.    * \param aDelimiter          String set delimiter.  Defaults to " ".
  650.    *
  651.    * \return                    True if string set contains string.
  652.    */
  653.  
  654.   contains: function StringSet_contains(aStringSet, aString, aDelimiter) {
  655.     // Get the delimiter.
  656.     var delimiter = aDelimiter;
  657.     if (!delimiter)
  658.       delimiter = " ";
  659.  
  660.     // Split the string set into an array and return whether the string set
  661.     // contains the string.
  662.     var stringSet = aStringSet.split(delimiter);
  663.     return (stringSet.indexOf(aString) >= 0);
  664.   }
  665. };
  666.  
  667.