src/jexer/bits/StringUtils.java

   1 /*
   2  * Jexer - Java Text User Interface
   3  *
   4  * The MIT License (MIT)
   5  *
   6  * Copyright (C) 2017 Kevin Lamonte
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a
   9  * copy of this software and associated documentation files (the "Software"),
  10  * to deal in the Software without restriction, including without limitation
  11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12  * and/or sell copies of the Software, and to permit persons to whom the
  13  * Software is furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24  * DEALINGS IN THE SOFTWARE.
  25  *
  26  * @author Kevin Lamonte [kevin.lamonte@gmail.com]
  27  * @version 1
  28  */
  29 package jexer.bits;
  30
  31 import java.util.List;
  32 import java.util.LinkedList;
  33
  34 /**
  35  * StringUtils contains methods to:
  36  *
  37  *    - Convert one or more long lines of strings into justified text
  38  *      paragraphs.
  39  *
  40  *    - Unescape C0 control codes.
  41  *
  42  */
  43 public final class StringUtils {
  44
  45     /**
  46      * Left-justify a string into a list of lines.
  47      *
  48      * @param str the string
  49      * @param n the maximum number of characters in a line
  50      * @return the list of lines
  51      */
  52     public static List<String> left(final String str, final int n) {
  53         List<String> result = new LinkedList<String>();
  54
  55         /*
  56          * General procedure:
  57          *
  58          *   1. Split on '\n' into paragraphs.
  59          *
  60          *   2. Scan each line, noting the position of the last
  61          *      beginning-of-a-word.
  62          *
  63          *   3. Chop at the last #2 if the next beginning-of-a-word exceeds
  64          *      n.
  65          *
  66          *   4. Return the lines.
  67          */
  68
  69         String [] rawLines = str.split("\n");
  70         for (int i = 0; i < rawLines.length; i++) {
  71             StringBuilder line = new StringBuilder();
  72             StringBuilder word = new StringBuilder();
  73             boolean inWord = false;
  74             for (int j = 0; j < rawLines[i].length(); j++) {
  75                 char ch = rawLines[i].charAt(j);
  76                 if ((ch == ' ') || (ch == '\t')) {
  77                     if (inWord == true) {
  78                         // We have just transitioned from a word to
  79                         // whitespace.  See if we have enough space to add
  80                         // the word to the line.
  81                         if (word.length() + line.length() > n) {
  82                             // This word will exceed the line length.  Wrap
  83                             // at it instead.
  84                             result.add(line.toString());
  85                             line = new StringBuilder();
  86                         }
  87                         if ((word.toString().startsWith(" "))
  88                             && (line.length() == 0)
  89                         ) {
  90                             line.append(word.substring(1));
  91                         } else {
  92                             line.append(word);
  93                         }
  94                         word = new StringBuilder();
  95                         word.append(ch);
  96                         inWord = false;
  97                     } else {
  98                         // We are in the whitespace before another word.  Do
  99                         // nothing.
 100                     }
 101                 } else {
 102                     if (inWord == true) {
 103                         // We are appending to a word.
 104                         word.append(ch);
 105                     } else {
 106                         // We have transitioned from whitespace to a word.
 107                         word.append(ch);
 108                         inWord = true;
 109                     }
 110                 }
 111             } // for (int j = 0; j < rawLines[i].length(); j++)
 112
 113             if (word.length() + line.length() > n) {
 114                 // This word will exceed the line length.  Wrap at it
 115                 // instead.
 116                 result.add(line.toString());
 117                 line = new StringBuilder();
 118             }
 119             if ((word.toString().startsWith(" "))
 120                 && (line.length() == 0)
 121             ) {
 122                 line.append(word.substring(1));
 123             } else {
 124                 line.append(word);
 125             }
 126             result.add(line.toString());
 127         } // for (int i = 0; i < rawLines.length; i++) {
 128
 129         return result;
 130     }
 131
 132     /**
 133      * Right-justify a string into a list of lines.
 134      *
 135      * @param str the string
 136      * @param n the maximum number of characters in a line
 137      * @return the list of lines
 138      */
 139     public static List<String> right(final String str, final int n) {
 140         List<String> result = new LinkedList<String>();
 141
 142         /*
 143          * Same as left(), but preceed each line with spaces to make it n
 144          * chars long.
 145          */
 146         List<String> lines = left(str, n);
 147         for (String line: lines) {
 148             StringBuilder sb = new StringBuilder();
 149             for (int i = 0; i < n - line.length(); i++) {
 150                 sb.append(' ');
 151             }
 152             sb.append(line);
 153             result.add(sb.toString());
 154         }
 155
 156         return result;
 157     }
 158
 159     /**
 160      * Center a string into a list of lines.
 161      *
 162      * @param str the string
 163      * @param n the maximum number of characters in a line
 164      * @return the list of lines
 165      */
 166     public static List<String> center(final String str, final int n) {
 167         List<String> result = new LinkedList<String>();
 168
 169         /*
 170          * Same as left(), but preceed/succeed each line with spaces to make
 171          * it n chars long.
 172          */
 173         List<String> lines = left(str, n);
 174         for (String line: lines) {
 175             StringBuilder sb = new StringBuilder();
 176             int l = (n - line.length()) / 2;
 177             int r = n - line.length() - l;
 178             for (int i = 0; i < l; i++) {
 179                 sb.append(' ');
 180             }
 181             sb.append(line);
 182             for (int i = 0; i < r; i++) {
 183                 sb.append(' ');
 184             }
 185             result.add(sb.toString());
 186         }
 187
 188         return result;
 189     }
 190
 191     /**
 192      * Fully-justify a string into a list of lines.
 193      *
 194      * @param str the string
 195      * @param n the maximum number of characters in a line
 196      * @return the list of lines
 197      */
 198     public static List<String> full(final String str, final int n) {
 199         List<String> result = new LinkedList<String>();
 200
 201         /*
 202          * Same as left(), but insert spaces between words to make each line
 203          * n chars long.  The "algorithm" here is pretty dumb: it performs a
 204          * split on space and then re-inserts multiples of n between words.
 205          */
 206         List<String> lines = left(str, n);
 207         for (int lineI = 0; lineI < lines.size() - 1; lineI++) {
 208             String line = lines.get(lineI);
 209             String [] words = line.split(" ");
 210             if (words.length > 1) {
 211                 int charCount = 0;
 212                 for (int i = 0; i < words.length; i++) {
 213                     charCount += words[i].length();
 214                 }
 215                 int spaceCount = n - charCount;
 216                 int q = spaceCount / (words.length - 1);
 217                 int r = spaceCount % (words.length - 1);
 218                 StringBuilder sb = new StringBuilder();
 219                 for (int i = 0; i < words.length - 1; i++) {
 220                     sb.append(words[i]);
 221                     for (int j = 0; j < q; j++) {
 222                         sb.append(' ');
 223                     }
 224                     if (r > 0) {
 225                         sb.append(' ');
 226                         r--;
 227                     }
 228                 }
 229                 for (int j = 0; j < r; j++) {
 230                     sb.append(' ');
 231                 }
 232                 sb.append(words[words.length - 1]);
 233                 result.add(sb.toString());
 234             } else {
 235                 result.add(line);
 236             }
 237         }
 238         if (lines.size() > 0) {
 239             result.add(lines.get(lines.size() - 1));
 240         }
 241
 242         return result;
 243     }
 244
 245     /**
 246      * Convert raw strings into escaped strings that be splatted on the
 247      * screen.
 248      *
 249      * @param str the string
 250      * @return a string that can be passed into Screen.putStringXY()
 251      */
 252     public static String unescape(final String str) {
 253         StringBuilder sb = new StringBuilder();
 254         for (int i = 0; i < str.length(); i++) {
 255             char ch = str.charAt(i);
 256             if ((ch < 0x20) || (ch == 0x7F)) {
 257                 switch (ch) {
 258                 case '\b':
 259                     sb.append("\\b");
 260                     continue;
 261                 case '\f':
 262                     sb.append("\\f");
 263                     continue;
 264                 case '\n':
 265                     sb.append("\\n");
 266                     continue;
 267                 case '\r':
 268                     sb.append("\\r");
 269                     continue;
 270                 case '\t':
 271                     sb.append("\\t");
 272                     continue;
 273                 case 0x7f:
 274                     sb.append("^?");
 275                     continue;
 276                 default:
 277                     sb.append(' ');
 278                     continue;
 279                 }
 280             }
 281             sb.append(ch);
 282         }
 283         return sb.toString();
 284     }
 285
 286 }