MonoRail/Castle.MonoRail.Framework/Helpers/TextHelper.cs

   1 // Copyright 2004-2007 Castle Project - http://www.castleproject.org/
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 namespace Castle.MonoRail.Framework.Helpers
  16 {
  17         using System;
  18         using System.Collections;
  19         using System.Text;
  20
  21         /// <summary>
  22         /// Provides methods for working with strings and grammar. At the moment,
  23         /// it contains the ToSentence overloads.
  24         /// </summary>
  25         public class TextHelper : AbstractHelper
  26         {
  27                 /// <summary>
  28                 /// Default word connector
  29                 /// </summary>
  30                 public const string DefaultConnector = "and";
  31
  32                 /// <summary>
  33                 /// Converts a camelized text to words. For instance:
  34                 /// <c>FileWriter</c> is converted to <c>File Writer</c>
  35                 /// </summary>
  36                 /// <param name="pascalText">Content in pascal case</param>
  37                 /// <returns></returns>
  38                 public static string PascalCaseToWord(string pascalText)
  39                 {
  40                         if (pascalText == null) throw new ArgumentNullException("pascalText");
  41
  42                         if (pascalText == string.Empty) return string.Empty;
  43
  44                         StringBuilder sbText = new StringBuilder(pascalText.Length + 4);
  45
  46                         char[] chars = pascalText.ToCharArray();
  47
  48                         sbText.Append(chars[0]);
  49
  50                         for(int i=1; i < chars.Length; i++)
  51                         {
  52                                 char c = chars[i];
  53
  54                                 if (Char.IsUpper(c))
  55                                 {
  56                                         sbText.Append(' ');
  57                                 }
  58
  59                                 sbText.Append(c);
  60                         }
  61
  62                         return sbText.ToString();
  63                 }
  64
  65                 /// <summary>
  66                 /// Builds a phrase listing a series of strings with with proper sentence semantics,
  67                 /// i.e. separating elements with &quot;, &quot; and prefacing the last element with
  68                 /// the specified <paramref name="connector"/>.
  69                 /// </summary>
  70                 /// <param name="elements">Collection with items to use in the sentence.</param>
  71                 /// <param name="connector">String to preface the last element.</param>
  72                 /// <returns>String suitable for use in a sentence.</returns>
  73                 /// <remarks>Calling <c>ToSentence( elements, "y" )</c> results in:
  74                 /// <code>
  75                 /// element1, element2 y element3
  76                 /// </code>
  77                 /// <para>If <paramref name="elements"/> is not an array of strings, each element will be
  78                 /// converted to string through <see cref="object.ToString"/>.</para>
  79                 /// </remarks>
  80                 /// <example>This example shows how to use <b>ToSentence</b>:
  81                 /// <code>
  82                 /// $TextHelper.ToSentence( elements, "y" )
  83                 /// </code>
  84                 /// </example>
  85                 public string ToSentence(ICollection elements, string connector)
  86                 {
  87                         return ToSentence(elements, connector, true);
  88                 }
  89
  90                 /// <summary>
  91                 /// Builds a phrase listing a series of strings with with proper sentence semantics,
  92                 /// i.e. separating elements with &quot;, &quot; and prefacing the last element with
  93                 /// &quot; and &quot;.
  94                 /// </summary>
  95                 /// <param name="elements">Collection with items to use in the sentence.</param>
  96                 /// <param name="skipLastComma">True to skip the comma before the connector, false to include it.</param>
  97                 /// <returns>String suitable for use in a sentence.</returns>
  98                 /// <remarks>Calling <c>ToSentence( elements, false )</c> results in:
  99                 /// <code>
 100                 /// element1, element2, and element3
 101                 /// </code>
 102                 /// <para>If <paramref name="elements"/> is not an array of strings, each element will be
 103                 /// converted to string through <see cref="object.ToString"/>.</para>
 104                 /// </remarks>
 105                 /// <example>This example shows how to use <b>ToSentence</b>:
 106                 /// <code>
 107                 /// $TextHelper.ToSentence( elements, false )
 108                 /// </code>
 109                 /// </example>
 110                 public string ToSentence(ICollection elements, bool skipLastComma)
 111                 {
 112                         return ToSentence(elements, DefaultConnector, skipLastComma);
 113                 }
 114
 115                 /// <summary>
 116                 /// Builds a phrase listing a series of strings with with proper sentence semantics,
 117                 /// i.e. separating elements with &quot;, &quot; and prefacing the last element with
 118                 /// &quot; and &quot;.
 119                 /// </summary>
 120                 /// <param name="elements">Collection with items to use in the sentence.</param>
 121                 /// <returns>String suitable for use in a sentence.</returns>
 122                 /// <remarks>Calling <c>ToSentence( elements )</c> results in:
 123                 /// <code>
 124                 /// element1, element2 and element3
 125                 /// </code>
 126                 /// <para>If <paramref name="elements"/> is not an array of strings, each element will be
 127                 /// converted to string through <see cref="object.ToString"/>.</para>
 128                 /// </remarks>
 129                 /// <example>This example shows how to use <b>ToSentence</b>:
 130                 /// <code>
 131                 /// $TextHelper.ToSentence( elements )
 132                 /// </code>
 133                 /// </example>
 134                 public string ToSentence(ICollection elements)
 135                 {
 136                         if (elements == null)
 137                         {
 138                                 throw new ArgumentNullException("elements");
 139                         }
 140
 141                         return ToSentence(elements, DefaultConnector, true);
 142                 }
 143
 144                 /// <summary>
 145                 /// Builds a phrase listing a series of strings with with proper sentence semantics,
 146                 /// i.e. separating elements with &quot;, &quot; and prefacing the last element with
 147                 /// the specified <paramref name="connector"/>.
 148                 /// </summary>
 149                 /// <param name="elements">Collection with items to use in the sentence.</param>
 150                 /// <param name="connector">String to preface the last element.</param>
 151                 /// <param name="skipLastComma">True to skip the comma before the <paramref name="connector"/>, false to include it.</param>
 152                 /// <returns>String suitable for use in a sentence.</returns>
 153                 /// <remarks>Calling <c>ToSentence( elements, "y", false )</c> results in:
 154                 /// <code>
 155                 /// element1, element2, y element3
 156                 /// </code>
 157                 /// <para>If <paramref name="elements"/> is not an array of strings, each element will be
 158                 /// converted to string through <see cref="Object.ToString"/>.</para>
 159                 /// </remarks>
 160                 /// <example>This example shows how to use <b>ToSentence</b>:
 161                 /// <code>
 162                 /// $TextHelper.ToSentence( elements, "y", false )
 163                 /// </code>
 164                 /// </example>
 165                 public string ToSentence(ICollection elements, string connector, bool skipLastComma)
 166                 {
 167                         string[] array = elements as string[];
 168                         if (array == null)
 169                         {
 170                                 array = new string[elements.Count];
 171                                 IEnumerator enumerator = elements.GetEnumerator();
 172                                 for(int i = 0; i < elements.Count; i++)
 173                                 {
 174                                         enumerator.MoveNext();
 175                                         array[i] = enumerator.Current.ToString();
 176                                 }
 177                         }
 178                         return ToSentence(array, connector, skipLastComma);
 179                 }
 180
 181                 /// <summary>
 182                 /// Builds a phrase listing a series of strings with with proper sentence semantics,
 183                 /// i.e. separating elements with &quot;, &quot; and prefacing the last element with
 184                 /// the specified <paramref name="connector"/>.
 185                 /// </summary>
 186                 /// <param name="elements">Array of strings with items to use in the sentence.</param>
 187                 /// <param name="connector">String to preface the last element.</param>
 188                 /// <param name="skipLastComma">True to skip the comma before the <paramref name="connector"/>, false to include it.</param>
 189                 /// <returns>String suitable for use in a sentence.</returns>
 190                 /// <remarks>Calling <c>ToSentence( elements, "y", false )</c> results in:
 191                 /// <code>
 192                 /// element1, element2, y element3
 193                 /// </code>
 194                 /// </remarks>
 195                 /// <example>This example shows how to use <b>ToSentence</b>:
 196                 /// <code>
 197                 /// $TextHelper.ToSentence( elements, "y", false )
 198                 /// </code>
 199                 /// </example>
 200                 public string ToSentence(string[] elements, string connector, bool skipLastComma)
 201                 {
 202                         switch(elements.Length)
 203                         {
 204                                 case 0:
 205                                         {
 206                                                 return String.Empty;
 207                                         }
 208                                 case 1:
 209                                         {
 210                                                 return elements[0];
 211                                         }
 212                                 case 2:
 213                                         {
 214                                                 return String.Format("{0} {1} {2}", elements[0], connector, elements[1]);
 215                                         }
 216                                 default:
 217                                         {
 218                                                 String[] allButLast = new String[elements.Length - 1];
 219
 220                                                 Array.Copy(elements, allButLast, elements.Length - 1);
 221
 222                                                 return String.Format("{0}{1} {2} {3}",
 223                                                                      String.Join(", ", allButLast),
 224                                                                      skipLastComma ? "" : ",",
 225                                                                      connector,
 226                                                                      elements[elements.Length - 1]);
 227                                         }
 228                         }
 229                 }
 230
 231                 /// <summary>
 232                 /// Shortens a text to the specified length and wraps it into a span-
 233                 /// element that has the title-property with the full text associated.
 234                 /// This is convenient for displaying properties in tables that might
 235                 /// have very much content (desription fields etc.) without destroying
 236                 /// the table's layout.
 237                 /// Due to the title-property of the surrounding span-element, the full
 238                 /// text is displayed in the browser while hovering over the shortened
 239                 /// text.
 240                 /// </summary>
 241                 /// <param name="text">The text to display</param>
 242                 /// <param name="maxLength">The maximum number of character to display</param>
 243                 /// <returns>The generated HTML</returns>
 244                 public string Fold(string text, int maxLength)
 245                 {
 246                         // Empty text
 247                         if (text == null) return "";
 248
 249                         // maxLenght <= 0 switches off folding
 250                         // Determine whether text must be cut
 251                         if (maxLength <= 0 || text.Length < maxLength) return text;
 252
 253                         StringBuilder caption = new StringBuilder();
 254                         foreach(string word in text.Split())
 255                         {
 256                                 if (caption.Length + word.Length + 1 > maxLength - 1) break;
 257                                 if (caption.Length > 0) caption.Append(" "); // Adding space
 258                                 caption.Append(word);
 259                         }
 260
 261                         caption.Append("&hellip;");
 262                         return string.Format("<span title=\"{1}\">{0}</span>", caption, text.Replace("\"", "&quot;"));
 263                 }
 264         }
 265 }