001package Torello.Java; 002 003import Torello.Java.ReadOnly.ReadOnlySet; 004import Torello.Java.ReadOnly.ReadOnlyHashSet; 005import Torello.Java.ReadOnly.ReadOnlyList; 006import Torello.Java.ReadOnly.ReadOnlyArrayList; 007 008import Torello.Java.Additional.Counter; 009 010import Torello.JavaDoc.Annotations.LinkJavaSource; 011 012import java.util.regex.Pattern; 013import java.util.regex.Matcher; 014 015import java.util.stream.Stream; 016import java.util.function.Function; 017import java.util.function.Supplier; 018 019@Torello.JavaDoc.Annotations.StaticFunctional 020public class StrSource 021{ 022 private StrSource() { } 023 024 025 // ******************************************************************************************** 026 // ******************************************************************************************** 027 // FIELDS 028 // ******************************************************************************************** 029 // ******************************************************************************************** 030 031 032 private static final char[] REGEX_ESCAPE_CHARS_ARR = 033 { '\\', '/', '(', ')', '[', ']', '{', '}', '$', '^', '+', '*', '?', '-', '.' }; 034 035 /** 036 * These are 'control' characters (Reg Ex Code), so they must be escaped if the are to be 037 * treated as their ASCII-equivalent values. 038 */ 039 public static final ReadOnlySet<Character> REGEX_ESCAPE_CHARS = 040 new ReadOnlyHashSet<>(REGEX_ESCAPE_CHARS_ARR, null); 041 042 private static final char[] JS_ESCAPE_CHARS_ARR = 043 { '\\', '/', '\n', '\"' }; 044 045 /** 046 * When converting a {@code String} for a Java-Script {@code String}, these are the 047 * characters that must be escaped. 048 */ 049 public static final ReadOnlySet<Character> JS_ESCAPE_CHARS = 050 new ReadOnlyHashSet<>(JS_ESCAPE_CHARS_ARR, null); 051 052 /** 053 * The list of reserved Java Key-Words. This list was written by ChatGPT on February 1st, 054 * 2024. 055 */ 056 public static final ReadOnlyList<String> reservedKeywords = new ReadOnlyArrayList<>( 057 "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", 058 "const", "continue", "default", "do", "double", "else", "enum", "extends", "false", 059 "final", "finally", "float", "for", "goto", "if", "implements", "import", "instanceof", 060 "int", "interface", "long", "native", "new", "null", "package", "permirs", "private", 061 "protected", "public", "return", "short", "static", "strictfp", "super", "switch", 062 "synchronized", "this", "throw", "throws", "transient", "true", "try", "void", "volatile", 063 "while" 064 ); 065 066 /** This will match the definition for a java {@code 'Generic'} class or interface */ 067 public static final Pattern GENERIC_PARAMS = Pattern.compile("^.+?<([\\.\\s\\w\\<>,\\?]+)>$"); 068 069 /** This shall match a Java Package {@code String} */ 070 public static final Pattern PACKAGE_NAME = Pattern.compile("([A-Za-z_]\\w*\\.)+"); 071 072 073 // ******************************************************************************************** 074 // ******************************************************************************************** 075 // Various Methods: General Purpose 076 // ******************************************************************************************** 077 // ******************************************************************************************** 078 079 080 /** 081 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_CARET_BEN> 082 * 083 * @param str This may be any input-{@code String} that is less than 100 characters. 084 * 085 * @param strPos This must be a number between 0 and the length 086 * 087 * @return The same input-{@code String} with a second line appended underneath (using a 088 * newline) having a <B>caret</B> ({@code '^'}) directly underneath the character at 089 * {@code strPos}. 090 * 091 * @throws IllegalArgumentException If the input {@code String} is longer than 092 * {@code 100 characters}. 093 * 094 * @throws StringFormatException If the input {@code String} contains any new-line {@code '\n'} 095 * or tab {@code '\t'} characters. 096 * 097 * @throws StringIndexOutOfBoundsException If the value pased to {@code strPos} is negative or 098 * greater than the length of the input-{@code String}. 099 * 100 * @see StringParse#nChars(char, int) 101 */ 102 public static String caretBeneath(String str, int strPos) 103 { 104 if (str.length() > 100) throw new IllegalArgumentException( 105 "The length of the input-string must be less than 100. str has length: " + 106 str.length() 107 ); 108 109 if (StrCmpr.containsOR(str, "\n", "\t")) throw new StringFormatException 110 ("The input-string may not contain new-line or tab characters."); 111 112 if (strPos >= str.length()) throw new StringIndexOutOfBoundsException( 113 "The value you have passed to 'strPos' [" + strPos + "] is greater than the length " + 114 "the input-string [" + str.length() + "]" 115 ); 116 117 if (strPos < 0) throw new StringIndexOutOfBoundsException 118 ("You have passed a negative value to strPos [" + strPos + "]"); 119 120 return str + "\n" + StringParse.nChars(' ', strPos) + '^'; 121 } 122 123 /** 124 * There are actually people out there who are willing to put character {@code '160'} into 125 * a file or document, instead of a simple {@code ' '} element. How rude. 126 * Any instances of this character shall be replaced with the standard space character 127 * {@code ASCII #32}. 128 * 129 * @param s Any {@code String} will pass. Generally {@code String's} that were converted from 130 * HTML pages will contain {@code char #160} as it is occasionally translated from the HTML 131 * escape sequence {@code } 132 * 133 * @return A String where any instance of white-space character {@code #160} have been 134 * replaced with character {@code #32} 135 */ 136 public static String replaceNBSP(String s) 137 { return s.replace((char) 160, ' '); } 138 // { return s.replace(("" + ((char) 160)), " "); } 139 140 /** 141 * Even lower than {@code #160}, apparently is the {@code "Zero Width Space"} (character 142 * {@code #8203}. This is actually inserted by the <B>JavaDoc Tool</B> (by 143 * {@code Sun / Oracle}) into JavaDoc generated HTML Pages. Here, it shall be replaced by 144 * character {@code #32} - the <I>space-character</I>. 145 * 146 * <BR /><BR /><B>A.K.A.:</B> <CODE>"\u200B"</CODE>. 147 * 148 * <BR /><BR /><B><I STYLE='color: red;'>Can you see the character, above?</I></B> No? 149 * That's zero width space for you! If you ever sitting and wondering why a {@code String} 150 * seems to be something else than what it looks like - you might have a zero-width 151 * space in your {@code String}. If so, it will take a while to find the bug. 152 * 153 * @param s Any {@code String} will pass. Generally {@code String's} that were converted from 154 * JavaDoc HTML pages will contain {@code char #8203}. 155 * 156 * @return A String where any instance of white-space character {@code #8203} have been 157 * replaced with character {@code #32} 158 */ 159 public static String replaceZWSP(String s) 160 { return s.replace((char) 8203, ' '); } 161 // { return s.replace(("" + ((char) 8203)), " "); } 162 163 164 // ******************************************************************************************** 165 // ******************************************************************************************** 166 // String-Escape Methods 167 // ******************************************************************************************** 168 // ******************************************************************************************** 169 170 171 /** 172 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_ESC_4JS_DESC> 173 * 174 * @param str This may be any String in java. It is intended to be inserted into a Java-Script 175 * file between an open and close quotation marks. 176 * 177 * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_ESC_4JS_RET> 178 */ 179 public static String escStrForJavaScript(String str) 180 { return StrReplace.r(str, JS_ESCAPE_CHARS_ARR, '\\'); } 181 182 /** 183 * This method should only be used for a <B><I>precise {@code String} match</I></B> using a 184 * regular-expression. This method shall 'escape' all characters that the JVM Regular 185 * Expression Matcher in {@code package java.util.regex.*} would expect be escaped. If the 186 * input parameter {@code 'str'} contains any regular-expression code, then this method would 187 * <B>FAIL</B> as it would escape regular-expression code into unusable text. 188 * 189 * @param str This should be any {@code String} for which the user would like to find an 190 * <B>exact match, as-is</B>. 191 * 192 * @return A regular-expression ready {@code String} 193 */ 194 public static String escStrForRegEx(String str) 195 { return StrReplace.r(str, REGEX_ESCAPE_CHARS_ARR, '\\'); } 196 197 198 // ******************************************************************************************** 199 // ******************************************************************************************** 200 // HTML: HTML-Tag Attribute-Names 201 // ******************************************************************************************** 202 // ******************************************************************************************** 203 204 205 /** 206 * Checks if a Java-{@code String} constitutes a valid HTML Attibute-Name. Note that this 207 * method, in no way consults any "complete list" of all know HTML-Attributes. Instead, it 208 * simply analyzes whether the name is conguent with the Attribute-Name Validator Reg-ex. 209 * 210 * @param attributeName Any Java-{@code String} 211 * 212 * @return {@code TRUE} if and ony if {@code 'attributeName'} is a valid HTML Atribute-Name, 213 * according to the agreed upon Attribute-Name Regular-Expression Validator. 214 */ 215 public static boolean isAttributeName(String attributeName) 216 { 217 if (attributeName.length() == 0) return false; 218 219 if (! isAttributeNameStart(attributeName.charAt(0))) return false; 220 221 for (int i=1; i < attributeName.length(); i++) 222 { 223 final char c = attributeName.charAt(i); 224 if ((c >= 'A') && (c <= 'Z')) continue; 225 if ((c >= 'a') && (c <= 'z')) continue; 226 if ((c >= '0') && (c <= '9')) continue; 227 if ((c == '-') || (c == '_')) continue; 228 return false; 229 } 230 231 return true; 232 } 233 234 /** 235 * Checks whether parameter {@code 'c'} is one of the agreed-upon standard characters that are 236 * allowed to begin HTML Attribute-Names. 237 * 238 * @param c Any Java {@code char}-primitive 239 * 240 * @return {@code TRUE} if and ony if {@code 'c'} is a character that would be allowed to begin 241 * an HTML Attribute-Name 242 */ 243 public static boolean isAttributeNameStart(char c) 244 { 245 if ((c >= 'A') && (c <= 'Z')) return true; 246 if ((c >= 'a') && (c <= 'z')) return true; 247 return false; 248 } 249 250 /** 251 * Checks whether parameter {@code 'c'} is one of the agreed-upon standard characters that are 252 * permitted within HTML Attribute-Names, after the first character of the name. 253 * 254 * @param c Any Java {@code char}-primitive 255 * 256 * @return {@code TRUE} if and ony if {@code 'c'} is a character that would be allowed within a 257 * valid HTML Attribute-Name. 258 */ 259 public static boolean isAttributeNamePart(char c) 260 { 261 if ((c >= 'A') && (c <= 'Z')) return true; 262 if ((c >= 'a') && (c <= 'z')) return true; 263 if ((c >= '0') && (c <= '9')) return true; 264 if ((c == '-') || (c == '_')) return true; 265 return false; 266 } 267 268 269 // ******************************************************************************************** 270 // ******************************************************************************************** 271 // HTML: Retrieve Common HTML Attribue-Values 272 // ******************************************************************************************** 273 // ******************************************************************************************** 274 275 276 /** 277 * If parameter {@code String s} contains any tag within-which there is a valid 278 * {@code "HREF"}, this will return the contents of the {@code HREF} Attribute/InnerTag. 279 * 280 * @param s This is usually some variant of an HTML element/tag {@code String}. This method 281 * was the first one written for HTML in this scrape package, and is just kept here for legacy 282 * reasons. The {@code class HTML.TagNode} has a number of options for extracting the 283 * {@code 'HREF'} attribute from an HTML element. 284 * 285 * @return The attribute-value of an {@code HREF=...} attribute inside (usually an {@code <A>} 286 * 'Anchor') HTML tag. This will return 'null' if there is no {@code HREF="..."} 287 * attribute-value pair is found or identified. 288 * 289 * @throws IllegalArgumentException If there is no end-quote found for the {@code HREF="..."} 290 * sub-string. 291 */ 292 @LinkJavaSource(handle="TagsGREP", name="grepIMG") 293 public static String grep_HREF_tag(String s) 294 { return TagsGREP.grepIMG(s); } 295 296 /** 297 * If parameter {@code String s} contains an HTML {@code "IMG"} tag, this will return the 298 * contents of the {@code "SRC=..."} attribute tag-field. 299 * 300 * @param s This is usually some variant of an HTML element/tag {@code String}. This method 301 * was the first one written for HTML in this scrape package, and is just kept here for legacy 302 * reasons. The {@code class HTML.TagNode} has a number of options for extracting the 303 * {@code 'SRC'} attribute from an HTML element. 304 * 305 * @return The attribute-value of a {@code SRC=...} attribute inside (usually an {@code <IMG>} 306 * 'Image') HTML tag. 'null' is returned if: 307 * 308 * <BR /><BR /><OL CLASS=JDOL> 309 * <LI>There is no HTML {@code 'IMG'} token found in the {@code String}</LI> 310 * <LI>There is no {@code SRC='...'} attribute-value pair found.</LI> 311 * </OL> 312 */ 313 @LinkJavaSource(handle="TagsGREP", name="grepHREF") 314 public static String grep_IMG_SRC_tag(String s) 315 { return TagsGREP.grepHREF(s); } 316 317 318 // ******************************************************************************************** 319 // ******************************************************************************************** 320 // CSS: Class Names 321 // ******************************************************************************************** 322 // ******************************************************************************************** 323 324 325 /** 326 * Checks if a Java-{@code String} constitutes a valid CSS Class-Name. This method does not 327 * consult any "complete list" of all known CSS classes but instead analyzes whether the name 328 * adheres to standard CSS class naming conventions. 329 * 330 * <BR /><BR /><DIV CLASS=JDHint> 331 * <B STYLE="color: red;">Chat-GPT Note:</B> Chat-GPT wrote all three of these (including th 332 * JavaDoc). Chat-GPT makes programming more fun. 333 * </DIV> 334 * 335 * @param cssClassName Any Java-{@code String} 336 * 337 * @return {@code TRUE} if and only if {@code cssClassName} is a valid CSS Class-Name according 338 * to the agreed-upon CSS naming rules. 339 */ 340 public static boolean isCSSClassName(String cssClassName) 341 { 342 if (cssClassName.length() == 0) return false; 343 344 if (!isCSSClassNameStart(cssClassName.charAt(0))) return false; 345 346 for (int i = 1; i < cssClassName.length(); i++) 347 if (!isCSSClassNamePart(cssClassName.charAt(i))) return false; 348 349 return true; 350 } 351 352 /** 353 * Checks whether parameter {@code 'c'} is a valid character to begin a CSS Class-Name. 354 * 355 * <BR /><BR /><DIV CLASS=JDHint> 356 * <B STYLE="color: red;">Chat-GPT Note:</B> Chat-GPT wrote all three of these (including the 357 * JavaDoc). Chat-GPT makes programming more fun. 358 * </DIV> 359 * 360 * @param c Any Java {@code char}-primitive 361 * 362 * @return {@code TRUE} if and only if {@code c} is a character that can begin a CSS 363 * Class-Name. 364 */ 365 public static boolean isCSSClassNameStart(char c) 366 { 367 if ((c >= 'A') && (c <= 'Z')) return true; 368 if ((c >= 'a') && (c <= 'z')) return true; 369 if (c == '-') return true; 370 if (c == '_') return true; 371 return false; 372 } 373 374 /** 375 * Checks whether parameter {@code 'c'} is a valid character within a CSS Class-Name. 376 * 377 * <BR /><BR /><DIV CLASS=JDHint> 378 * <B STYLE="color: red;">Chat-GPT Note:</B> Chat-GPT wrote all three of these (including the 379 * JavaDoc). Chat-GPT makes programming more fun. 380 * </DIV> 381 * 382 * @param c Any Java {@code char}-primitive 383 * 384 * @return {@code TRUE} if and only if {@code c} is a character that can be part of a CSS 385 * Class-Name. 386 */ 387 public static boolean isCSSClassNamePart(char c) 388 { 389 if ((c >= 'A') && (c <= 'Z')) return true; 390 if ((c >= 'a') && (c <= 'z')) return true; 391 if ((c >= '0') && (c <= '9')) return true; 392 if (c == '-') return true; 393 if (c == '_') return true; 394 return false; 395 } 396 397 398 // ******************************************************************************************** 399 // ******************************************************************************************** 400 // CSS: Property Names 401 // ******************************************************************************************** 402 // ******************************************************************************************** 403 404 405 /** 406 * Checks if a Java-{@code String} constitutes a valid CSS Property-Name. Note that this 407 * method, in no way consults any "complete list" of all known CSS-Properties. Instead, it 408 * simply analyzes whether the name is conguent with the CSS-Property Validator Reg-ex. 409 * 410 * @param cssPropertyName Any Java-{@code String} 411 * 412 * @return {@code TRUE} if and ony if {@code 'attributeName'} is a valid HTML Atribute-Name, 413 * according to the agreed upon CSS-Property Regular-Expression Validator. 414 */ 415 public static boolean isCSSPropertyName(String cssPropertyName) 416 { 417 if (cssPropertyName.length() == 0) return false; 418 419 if (! isCSSPropertyNameStart(cssPropertyName.charAt(0))) return false; 420 421 for (int i=1; i < cssPropertyName.length(); i++) 422 { 423 final char c = cssPropertyName.charAt(i); 424 if ((c >= 'A') && (c <= 'Z')) continue; 425 if ((c >= 'a') && (c <= 'z')) continue; 426 if ((c >= '0') && (c <= '9')) continue; 427 if ((c == '-') || (c == '_')) continue; 428 return false; 429 } 430 431 return true; 432 } 433 434 /** 435 * Checks whether parameter {@code 'c'} is one of the agreed-upon standard characters that are 436 * allowed to begin CSS Property-Names. 437 * 438 * @param c Any Java {@code char}-primitive 439 * 440 * @return {@code TRUE} if and ony if {@code 'c'} is a character that would be allowed to begin 441 * a CSS Property-Name 442 */ 443 public static boolean isCSSPropertyNameStart(char c) 444 { 445 if ((c >= 'A') && (c <= 'Z')) return true; 446 if ((c >= 'a') && (c <= 'z')) return true; 447 if ((c == '-') || (c == '_')) return true; 448 return false; 449 } 450 451 /** 452 * Checks whether parameter {@code 'c'} is one of the agreed-upon standard characters that are 453 * permitted within CSS Property-Names, after the first character of the name. 454 * 455 * @param c Any Java {@code char}-primitive 456 * 457 * @return {@code TRUE} if and ony if {@code 'c'} is a character that would be allowed within a 458 * valid CSS Property-Name. 459 */ 460 public static boolean isCSSPropertyNamePart(char c) 461 { 462 if ((c >= 'A') && (c <= 'Z')) return true; 463 if ((c >= 'a') && (c <= 'z')) return true; 464 if ((c >= '0') && (c <= '9')) return true; 465 if ((c == '-') || (c == '_')) return true; 466 return false; 467 } 468 469 470 // ******************************************************************************************** 471 // ******************************************************************************************** 472 // Java: Names, Types and Identifiers, & Literals 473 // ******************************************************************************************** 474 // ******************************************************************************************** 475 476 477 /** 478 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_EX_TYPE_DESC> 479 * 480 * @param srcFileName This is expected to be the file-name of a {@code '.java'} or 481 * {@code '.class'} File. 482 * 483 * @param throwOnBadTypeName When this is passed {@code TRUE}, this method throws an exception 484 * if the Computed Type-Name is not a valid Java Identifier. 485 * 486 * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_EX_TYPE_RET> 487 * 488 * @throws IllegalArgumentException If the file-name ends neither with the text {@code '.java'} 489 * nor with {@code '.class'}. 490 * 491 * @throws JavaIdentifierException Throws if-and-only-if <B>BOTH</B> the returned 492 * {@code String} would not constitute a valid Java-Identifier, <B>AND</B> the input 493 * {@code boolean} parameter {@code throwOnBadTypeName} is passed {@code TRUE}. 494 */ 495 @LinkJavaSource(handle="ExtractTypeName") 496 public static String extractTypeName 497 (final String srcFileName, final boolean throwOnBadTypeName) 498 { return ExtractTypeName.extract(srcFileName, throwOnBadTypeName); } 499 500 /** 501 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_JTYPE_STR> 502 * 503 * @param s Any Java {@code String}. 504 * 505 * @return {@code TRUE} if and only if the Java Compiler could interpret {@code 's'} as a valid 506 * reference to a Java Type. In computer-programming, the world <B>{@code Type}</B> can have a 507 * lot of meanings, but here, the word should be interpreted as a Java Class, Interface, 508 * Enumeration (an {@code 'enum'}), Annotation or Record. 509 * 510 * <BR /><BR /><DIV CLASS=JDHint> 511 * <B STYLE="color: red;">Note:</B> {@code 's'} may include the period {@code '.'} since inner 512 * classes, enum's and interfaces are also valid Java Type's. Two consecutive 513 * period-characters, or a period at the beginning or ending of {@code 's'} will result in this 514 * method returning {@code FALSE}. 515 * </DIV> 516 */ 517 @LinkJavaSource(handle="IsJavaTypeStr") 518 public static boolean isJavaTypeStr(String s) 519 { return IsJavaTypeStr.is(s); } 520 521 /** 522 * Checks whether an input {@code String} would be allowed as a Java Identifier - for instance, 523 * whether the input would make a valid Field-Name, Variable-Name, Class-Name or Method-Name. 524 * 525 * <BR /><BR /><DIV CLASS=JDHint> 526 * <B STYLE="color: red;">NOTE:</B> This class returns {@code FALSE} if it is passed 'null'. 527 * It does not throw a {@code NullPointerException}. 528 * 529 * <BR /><BR /><B STYLE="color: red;">Chat-GPT Note:</B> ChatGPT, 3.5 wrote this whole thing, 530 * including the in-line comments. I had to write the Java-Doc Comments, but I guess I 531 * could have asked it to do that too. 532 * </DIV> 533 * 534 * @param identifier Any Java {@code String} 535 * 536 * @return {@code TRUE} if-and-only-if parameter {@code 'identifier'} is a valid Java 537 * Identifier. 538 */ 539 public static boolean isValidJavaIdentifier(String identifier) 540 { 541 // Check if the string is not null or empty 542 if (identifier == null || identifier.isEmpty()) return false; 543 544 // Check if the first character is a letter, underscore, or dollar sign 545 if (! Character.isJavaIdentifierStart(identifier.charAt(0))) return false; 546 547 // Check the remaining characters 548 for (int i = 1; i < identifier.length(); i++) 549 if (!Character.isJavaIdentifierPart(identifier.charAt(i))) 550 return false; 551 552 // Check if the identifier is a reserved keyword 553 if (reservedKeywords.contains(identifier)) return false; 554 555 // The string is a valid Java identifier 556 return true; 557 } 558 559 /** 560 * Simply removes the trailiing {@code '.java'} from the end of an input File-Name Parameter. 561 * Also removes any leading directory information from the input {@code String}. 562 * 563 * @param javaFileName This is expected to be a legitamite '.java' Source-Code File-Name, as a 564 * {@code java.lang.String}. 565 * 566 * @return Returns a {@code String} in which leading directory information has been truncated, 567 * and the last five characters have been removed. 568 * 569 * <BR /><BR />Due to the highly repetitive nature of using this methpo within a loop, this 570 * method's body <B STYLE='color: red;'><I>does not</I></B> perform any kind of error checking 571 * on its input. 572 * 573 * <BR /><BR />If a null {@code String} is passed as input, this method will throw a 574 * {@code NullPointerException}. If your best friend's address is passed as input, this method 575 * will return a {@code String} in which the last 5 characters of text of that address have 576 * been removed. 577 * 578 * <BR /><BR /><I>And if that address had a forward or backward slash ({@code '/'} or 579 * {@code '\'}), everything prior to the last slash present within that input-mess would be 580 * truncated.</I> 581 * 582 * @throws IndexOutOfBoundsException If, after truncating any leading directory information, 583 * the resulting {@code String} is less than 5 characters, then this exception throws. 584 */ 585 public static String noPathNoExt(String javaFileName) 586 { 587 for (int i=(javaFileName.length()-1); i > 0; i--) 588 { 589 final char c = javaFileName.charAt(i); 590 591 if ((c == '/') || (c == '\\')) 592 { 593 javaFileName = javaFileName.substring(i + 1); 594 break; 595 } 596 } 597 598 return javaFileName.substring(0, javaFileName.length() - 5); 599 } 600 601 /** 602 * <EMBED CLASS='external-html' DATA-FILE-ID=STRS_NUM_2_STRING> 603 * @param i Any Java Integer 604 * 605 * @return The value of {@code 'i'} as a {@code String}, but separated by the underscore 606 * character {@code '_'} in between each spacing of three orders of magnitude. 607 */ 608 @LinkJavaSource(handle="IntegralToJavaLiteral") 609 public static String numToStringJava(int i) 610 { return IntegralToJavaLiteral.charBuffer(i); } 611 612 /** 613 * Identical to {@link #numToStringJava}, but accepts a {@code long}. 614 * @param l Any Java Long 615 * 616 * @return The value of {@code 'l'} as a {@code String}, but separated by the underscore 617 * character {@code '_'} in between each spacing of three orders of magnitude. 618 * 619 * @see #numToStringJava(int) 620 */ 621 @LinkJavaSource(handle="IntegralToJavaLiteral") 622 public static String numToStringJava(long l) 623 { return IntegralToJavaLiteral.charBufferLong(l); } 624 625 /** 626 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_TTJI_DESC> 627 * 628 * @param typeStr 629 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_TTJI_TYPESTR> 630 * 631 * @return a Simplified version of the type that leaves out the scope, but provides a 632 * simple Java Identifier, instead. Throws exceptions if not properly formatted. If any 633 * array-bracket characters are passed, they is preserved, unless the arrays in this type 634 * are part of the generic-type parameters; please see the examples above. 635 * 636 * @throws StringFormatException Please see the explanation provided in 637 * {@link #removeGeneric(String)} under 'Throws'. 638 * 639 * @see #removeGeneric(String) 640 */ 641 @LinkJavaSource(handle="TypeToJavaIdentifier") 642 public static String typeToJavaIdentifier(String typeStr) 643 { return TypeToJavaIdentifier.convert(typeStr); } 644 645 646 // ******************************************************************************************** 647 // ******************************************************************************************** 648 // Java: Generic-Types & Extends-Clauses 649 // ******************************************************************************************** 650 // ******************************************************************************************** 651 652 653 /** 654 * Parses a {@code String} such as {@code T extends TreeMap<Integer, List<String>>}. It is 655 * strictly used, to <B><I>only parse</I></B> the generic-definition lists that are at the top 656 * of generic <B>classes</B> and <B>interfaces</B>. 657 * 658 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_PARSE_GENT DATA-NODE="An Example of Sorts"> 659 * 660 * @param genericTypeParamOrDefinition This should be {@code String} retrieved from inside the 661 * less-than ({@code '<'}) and greater-than ({@code '>'}) symbols. For example, for 662 * {@code SortedList<A extends Comparable, B>}, the {@code String} passed to this method should 663 * be {@code "A extends Comparable, B"} 664 * 665 * @return This should break down this {@code CSV} (comma separated value) list into 666 * individual {@code String's}. 667 * 668 * @throws NoMatchException if the input {@code String} parameter does not match the 669 * generics regular-expression {@link #GENERIC_PARAMS}. 670 * 671 * @throws StringFormatException If the input {@code String} could not be parsed. 672 */ 673 @LinkJavaSource(handle="ParseGenericType") 674 public static String[] parseGenericType(String genericTypeParamOrDefinition) 675 { return ParseGenericType.parse(genericTypeParamOrDefinition); } 676 677 678 // This was designed while staring at the field retrieved from a JavaDoc HTML Page that 679 // looked like this (from AbstractHNLI) 680 // protected java.util.function.Predicate<E extends HTMLNode> p; 681 // This puts a group (group 1) around the ( extends HTMLNode) part, so it can be removed. 682 // JavaParser complained about it. 683 684 private static final Pattern exClause = 685 Pattern.compile("([A-Za-z][A-Za-z0-9]*)(\\s+extends\\s+[\\w\\.]+)"); 686 687 /** 688 * Removes the {@code 'extends'} part of a Java Generic 689 * 690 * <BR /><BR /><DIV CLASS=JDHint> 691 * <B STYLE='color:red;'>TO DO:</B> This will fail for a class such as: 692 * <BR />{@code public class MyClass<T extends Vector<String>}, where the extends clause 693 * also has a generic in it. Java HTML does not define such classes, but they are possible, 694 * and this needs to be fixed, as soon as they let me! 695 * </DIV> 696 * 697 * @param decl Any Type Declaration that includes has the word {{@code 'extends'}}, 698 * followed by type-parameter information. 699 * 700 * @return The same {@code String} without the clause. 701 */ 702 public static String removeExtendsClause(String decl) 703 { 704 Matcher m = exClause.matcher(decl); 705 706 while (m.find()) 707 { 708 decl = m.replaceFirst(m.group(1)); 709 m.reset(decl); 710 } 711 712 return decl; 713 } 714 715 /** 716 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_REM_GEN_DESC> 717 * 718 * @param typeAsStr The "Reference Type" or "Declaration Type". 719 * 720 * @return The same {@code String}, having everything between the <B>outer-most, matching</B> 721 * {@code '<'} and {@code '>'} symbols. 722 * 723 * <BR /><BR /><DIV CLASS=JDHint> 724 * <B STYLE="color: red;">Note:</B> The returned {@code String} will not contain any leading or 725 * trailing white-space. It is trimmed before being returned. 726 * </DIV> 727 * 728 * @throws StringFormatException 729 * <EMBED CLASS='external-html' DATA-FILE-ID=STRSRC_STR_FORM_EX> 730 */ 731 @LinkJavaSource(handle="RemoveGeneric") 732 public static String removeGeneric(String typeAsStr) 733 { return RemoveGeneric.remove(typeAsStr); } 734 735 736 // ******************************************************************************************** 737 // ******************************************************************************************** 738 // Code-Generators: Java-Doc Source-Code Emitters 739 // ******************************************************************************************** 740 // ******************************************************************************************** 741 742 743 /** 744 * It is best to read, exactly, how this method operates by reviewing the code in the "Method 745 * Body" below. This method converts a text description into a Java-Doc Comment. 746 * 747 * @param desc A descriptive String that is to be used as a Java-Doc comment 748 * @param numSpacesIndentation Number of spaces of indentation to be pre-pended to each line 749 * @param maxLineLength Maximum number of characters on any given line. 750 * 751 * @return A Java-Doc String, prepended by {@code " * "} and the number of requested spaces. 752 */ 753 public static String toJavaDoc(String desc, int numSpacesIndentation, int maxLineLength) 754 { 755 final String INDENT = StringParse.nChars(' ', numSpacesIndentation); 756 757 desc = desc.replace('\n', ' ').trim(); 758 759 760 // For: numSpacesIndentation = 4, maxLineLength = 100 761 // 762 // 88 ==> maxLineLength - INDENT.length() - " /** ".length() - " */".length() 763 // 88 ==> 100 - 4 - 5 - 3 764 765 if (desc.length() <= (maxLineLength - numSpacesIndentation - 8)) 766 return INDENT + "/** " + desc + " */\n"; 767 768 769 // ONE THING: I need to come back to this at a later date and re-investigate why I have 770 // needed to add the '-1'. I haven't looked at StrPrint.wrap in 7 months... I am in the 771 // middle of something else right now (Torello.Browser). Thusly, though it looks normal 772 // and official, the extra '-1' at the end of this makes no sense to me... But the testing 773 // shows that -4 was correct, and -3 was failing... I DON'T HAVE TIME / INCLINATION right 774 // now ! 775 // 776 // 92 ==> 100 - INDENT.length() - " * ".length() - 1 777 // 92 ==> maxLineLength - numSpacesIndentation - 3 - 1 778 779 desc = StrPrint 780 .wrap(desc, maxLineLength - numSpacesIndentation - 4) 781 .replace("\n", '\n' + INDENT + " * "); 782 783 return INDENT + "/**\n" + INDENT + " * " + desc + '\n' + INDENT + " */\n"; 784 } 785 786 /** 787 * It is best to read, exactly, how this method operates by reviewing the code in the "Method 788 * Body" below. This method converts a text description into a Java-Doc Comment. 789 * 790 * @param desc A descriptive String that is to be used as a Java-Doc comment 791 * @param numSpacesIndentation Number of spaces of indentation to be pre-pended to each line 792 * @param maxLineLength Maximum number of characters on any given line. 793 * 794 * @return A Java-Doc String, prepended by {@code " * "} and the number of requested spaces. 795 */ 796 public static String toJavaDoc2(String desc, int numSpacesIndentation, int maxLineLength) 797 { 798 final String INDENT = StringParse.nChars(' ', numSpacesIndentation); 799 800 desc = desc.replace('\n', ' ').trim(); 801 802 return 803 INDENT + " * " + StrPrint 804 .wrap(desc, maxLineLength - numSpacesIndentation - 4) 805 .replace("\n", '\n' + INDENT + " * ") + 806 '\n'; 807 } 808 809 810 // ******************************************************************************************** 811 // ******************************************************************************************** 812 // Code Generators: More Emitters 813 // ******************************************************************************************** 814 // ******************************************************************************************** 815 816 817 /** 818 * Returns a function that will print the contents of the iterable, with just enough 819 * right hand space to produce output that begins on a column number that is a multiple of 820 * {@code 'spacesPerTab'}. 821 * 822 * <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_DESC> 823 * @param <PRINTABLE> <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_PRNTB> 824 * @param passedBaseStr <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_BASE> 825 * @param iterable <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_ITER> 826 * @param passedGetStr <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_GET> 827 * @param spacesPerTab The number of spaces a TAB character to should represent. 828 * @return <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_RET> 829 * 830 * @throws NException if {@code 'spacesPerTab'} is less than 2 or greter than 10 831 * @throws StringFormatExcetion <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_SF_EX> 832 * @throws EmptyListException <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_EL_EX> 833 * @throws NullPointerException <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_TABBED_NP_EX> 834 */ 835 @LinkJavaSource(handle="TabbedIndentation") 836 public static <PRINTABLE> Function<PRINTABLE, String> getTabbedPrinter( 837 final String passedBaseStr, 838 final Iterable<PRINTABLE> iterable, 839 final Function<? super PRINTABLE, String> passedGetStr, 840 final byte spacesPerTab 841 ) 842 { return TabbedIndentation.getFunction(passedBaseStr, iterable, passedGetStr, spacesPerTab); } 843 844 /** 845 * Produces a "Comment String" text which contains four rows of stars, and a title string. 846 * <EMBED CLASS='' DATA-FILE-ID=STRSRC_4STARS_DESC> 847 * 848 * @param title Title text to insert between the rows of stars 849 * @param indentation Amount of indentation spaces to add 850 * @param maxLineLength Total expected / required line length of this comment 851 * 852 * @return A Java source string which may be inserted into {@code '.java'} files. 853 * 854 * @throws NullPointerException if title is null 855 * @throws StringFormatException if title won't fit within {@code 'maxLineLength'} 856 * 857 * @throws IllegalArgumentException 858 * <EMBED CLASS=external-html DATA-FILE-ID=STRSRC_4STARS_IA_EX> 859 * 860 * @see StringParse#nChars(char, int) 861 */ 862 @LinkJavaSource(handle="FourRowsStars") 863 public static String fourRowsStars(String title, byte indentation, byte maxLineLength) 864 { return FourRowsStars.get(title, indentation, maxLineLength); } 865 866 /** 867 * Performs the standard "Right Trim Whitespace" on each line of text contained by the input 868 * {@code String}. Converts the input {@code String} to a {@code char[] cArr}, and then 869 * performs an in-place shift operation before rebuilding a new string from the array. 870 * 871 * @param srcCode Any text-file or snippet containing any programming language 872 * @return A new 873 */ 874 @LinkJavaSource(handle="RightTrimAll2") 875 public static String rightTrimAll(String srcCode) 876 { return RightTrimAll2.run(srcCode); } 877 878 /** 879 * Indents each line of input text {@code 'srcCode'}, by the number of spaces 880 * {@code 'numSpaces'}. Does not do any indentation on lines which only contain whitespace. 881 * 882 * @param srcCode Any text-file or snippet containing any programming language 883 * @param numSpaces Number of space characters to pre-pend to each non-blank line 884 * @return The same text, with the requested indentation. 885 * 886 * @throws IllegalArgumentException if {@code 'numSpaces'} is less than 1. 887 */ 888 @LinkJavaSource(handle="IndentNonBlankLines") 889 public static String indentNonBlank(String srcCode, byte numSpaces) 890 { return IndentNonBlankLines.run(srcCode, numSpaces, false); } 891 892 /** 893 * Indents each, non-blank, line of input text {@code 'srcCode'}, by the number of spaces 894 * {@code 'numSpaces'}. 895 * 896 * <BR /><BR /><DIV CLASS=JDHint> 897 * This method also performs a white-space {@code trim()} on each line which only contains 898 * whitespace. 899 * </DIV> 900 * 901 * @param srcCode Any text-file or snippet containing any programming language 902 * @param numSpaces Number of space characters to pre-pend to each non-blank line 903 * @return The same text, with the requested indentation. 904 * 905 * @throws IllegalArgumentException if {@code 'numSpaces'} is less than 1. 906 */ 907 @LinkJavaSource(handle="IndentNonBlankLines") 908 public static String indentNonBlankAndTrim(String srcCode, byte numSpaces) 909 { return IndentNonBlankLines.run(srcCode, numSpaces, true); } 910 911}