001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.configuration2; 018 019import java.io.BufferedReader; 020import java.io.IOException; 021import java.io.PrintWriter; 022import java.io.Reader; 023import java.io.Writer; 024import java.util.LinkedHashMap; 025import java.util.LinkedHashSet; 026import java.util.List; 027import java.util.Map; 028import java.util.Set; 029import java.util.stream.Collectors; 030 031import org.apache.commons.configuration2.convert.ListDelimiterHandler; 032import org.apache.commons.configuration2.ex.ConfigurationException; 033import org.apache.commons.configuration2.ex.ConfigurationRuntimeException; 034import org.apache.commons.configuration2.tree.ImmutableNode; 035import org.apache.commons.configuration2.tree.InMemoryNodeModel; 036import org.apache.commons.configuration2.tree.InMemoryNodeModelSupport; 037import org.apache.commons.configuration2.tree.NodeHandler; 038import org.apache.commons.configuration2.tree.NodeHandlerDecorator; 039import org.apache.commons.configuration2.tree.NodeSelector; 040import org.apache.commons.configuration2.tree.TrackedNodeModel; 041 042/** 043 * <p> 044 * A specialized hierarchical configuration implementation for parsing ini files. 045 * </p> 046 * <p> 047 * An initialization or ini file is a configuration file typically found on Microsoft's Windows operating system and 048 * contains data for Windows based applications. 049 * </p> 050 * <p> 051 * Although popularized by Windows, ini files can be used on any system or platform due to the fact that they are merely 052 * text files that can easily be parsed and modified by both humans and computers. 053 * </p> 054 * <p> 055 * A typical ini file could look something like: 056 * </p> 057 * 058 * <pre> 059 * [section1] 060 * ; this is a comment! 061 * var1 = foo 062 * var2 = bar 063 * 064 * [section2] 065 * var1 = doo 066 * </pre> 067 * <p> 068 * The format of ini files is fairly straight forward and is composed of three components: 069 * </p> 070 * <ul> 071 * <li><b>Sections:</b> Ini files are split into sections, each section starting with a section declaration. A section 072 * declaration starts with a '[' and ends with a ']'. Sections occur on one line only.</li> 073 * <li><b>Parameters:</b> Items in a section are known as parameters. Parameters have a typical {@code key = value} 074 * format.</li> 075 * <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.</li> 076 * </ul> 077 * <p> 078 * There are various implementations of the ini file format by various vendors which has caused a number of differences 079 * to appear. As far as possible this configuration tries to be lenient and support most of the differences. 080 * </p> 081 * <p> 082 * Some of the differences supported are as follows: 083 * </p> 084 * <ul> 085 * <li><b>Comments:</b> The '#' character is also accepted as a comment signifier.</li> 086 * <li><b>Key value separator:</b> The ':' character is also accepted in place of '=' to separate keys and values in 087 * parameters, for example {@code var1 : foo}.</li> 088 * <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed, this configuration does however support 089 * this feature. In the event of a duplicate section, the two section's values are merged so that there is only a single 090 * section. <strong>Note</strong>: This also affects the internal data of the configuration. If it is saved, only a 091 * single section is written!</li> 092 * <li><b>Duplicate parameters:</b> Typically duplicate parameters are only allowed if they are in two different 093 * sections, thus they are local to sections; this configuration simply merges duplicates; if a section has a duplicate 094 * parameter the values are then added to the key as a list.</li> 095 * </ul> 096 * <p> 097 * Global parameters are also allowed; any parameters declared before a section is declared are added to a global 098 * section. It is important to note that this global section does not have a name. 099 * </p> 100 * <p> 101 * In all instances, a parameter's key is prepended with its section name and a '.' (period). Thus a parameter named 102 * "var1" in "section1" will have the key {@code section1.var1} in this configuration. (This is the default behavior. 103 * Because this is a hierarchical configuration you can change this by setting a different 104 * {@link org.apache.commons.configuration2.tree.ExpressionEngine}.) 105 * </p> 106 * <h3>Implementation Details:</h3> Consider the following ini file: 107 * 108 * <pre> 109 * default = ok 110 * 111 * [section1] 112 * var1 = foo 113 * var2 = doodle 114 * 115 * [section2] 116 * ; a comment 117 * var1 = baz 118 * var2 = shoodle 119 * bad = 120 * = worse 121 * 122 * [section3] 123 * # another comment 124 * var1 : foo 125 * var2 : bar 126 * var5 : test1 127 * 128 * [section3] 129 * var3 = foo 130 * var4 = bar 131 * var5 = test2 132 * 133 * [sectionSeparators] 134 * passwd : abc=def 135 * a:b = "value" 136 * </pre> 137 * <p> 138 * This ini file will be parsed without error. Note: 139 * </p> 140 * <ul> 141 * <li>The parameter named "default" is added to the global section, it's value is accessed simply using 142 * {@code getProperty("default")}.</li> 143 * <li>Section 1's parameters can be accessed using {@code getProperty("section1.var1")}.</li> 144 * <li>The parameter named "bad" simply adds the parameter with an empty value.</li> 145 * <li>The empty key with value "= worse" is added using a key consisting of a single space character. This key is still 146 * added to section 2 and the value can be accessed using {@code getProperty("section2. ")}, notice the period '.' and 147 * the space following the section name.</li> 148 * <li>Section three uses both '=' and ':' to separate keys and values.</li> 149 * <li>Section 3 has a duplicate key named "var5". The value for this key is [test1, test2], and is represented as a 150 * List.</li> 151 * <li>The section called <em>sectionSeparators</em> demonstrates how the configuration deals with multiple occurrences 152 * of separator characters. Per default the first separator character in a line is detected and used to split the key 153 * from the value. Therefore the first property definition in this section has the key {@code passwd} and the value 154 * {@code abc=def}. This default behavior can be changed by using quotes. If there is a separator character before the 155 * first quote character (ignoring whitespace), this character is used as separator. Thus the second property definition 156 * in the section has the key {@code a:b} and the value {@code value}.</li> 157 * </ul> 158 * <p> 159 * Internally, this configuration maps the content of the represented ini file to its node structure in the following 160 * way: 161 * </p> 162 * <ul> 163 * <li>Sections are represented by direct child nodes of the root node.</li> 164 * <li>For the content of a section, corresponding nodes are created as children of the section node.</li> 165 * </ul> 166 * <p> 167 * This explains how the keys for the properties can be constructed. You can also use other methods of 168 * {@link HierarchicalConfiguration} for querying or manipulating the hierarchy of configuration nodes, for instance the 169 * {@code configurationAt()} method for obtaining the data of a specific section. However, be careful that the storage 170 * scheme described above is not violated (e.g. by adding multiple levels of nodes or inserting duplicate section 171 * nodes). Otherwise, the special methods for ini configurations may not work correctly! 172 * </p> 173 * <p> 174 * The set of sections in this configuration can be retrieved using the {@code getSections()} method. For obtaining a 175 * {@code SubnodeConfiguration} with the content of a specific section the {@code getSection()} method can be used. 176 * </p> 177 * <p> 178 * Like other {@code Configuration} implementations, this class uses a {@code Synchronizer} object to control concurrent 179 * access. By choosing a suitable implementation of the {@code Synchronizer} interface, an instance can be made 180 * thread-safe or not. Note that access to most of the properties typically set through a builder is not protected by 181 * the {@code Synchronizer}. The intended usage is that these properties are set once at construction time through the 182 * builder and after that remain constant. If you wish to change such properties during life time of an instance, you 183 * have to use the {@code lock()} and {@code unlock()} methods manually to ensure that other threads see your changes. 184 * </p> 185 * <p> 186 * As this class extends {@link AbstractConfiguration}, all basic features like variable interpolation, list handling, 187 * or data type conversions are available as well. This is described in the chapter 188 * <a href="https://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html"> Basic features 189 * and AbstractConfiguration</a> of the user's guide. 190 * </p> 191 * <p> 192 * Note that this configuration does not support properties with null values. Such properties are considered to be 193 * section nodes. 194 * </p> 195 * 196 * @since 1.6 197 */ 198public class INIConfiguration extends BaseHierarchicalConfiguration implements FileBasedConfiguration { 199 200 /** 201 * The default characters that signal the start of a comment line. 202 */ 203 protected static final String COMMENT_CHARS = "#;"; 204 205 /** 206 * The default characters used to separate keys from values. 207 */ 208 protected static final String SEPARATOR_CHARS = "=:"; 209 210 /** 211 * Constant for the line separator. 212 */ 213 private static final String LINE_SEPARATOR = System.lineSeparator(); 214 215 /** 216 * The characters used for quoting values. 217 */ 218 private static final String QUOTE_CHARACTERS = "\"'"; 219 220 /** 221 * The line continuation character. 222 */ 223 private static final String LINE_CONT = "\\"; 224 225 /** 226 * The separator used when writing an INI file. 227 */ 228 private String separatorUsedInOutput = " = "; 229 230 /** 231 * The separator used when reading an INI file. 232 */ 233 private String separatorUsedInInput = SEPARATOR_CHARS; 234 235 /** 236 * The characters used to separate keys from values when reading an INI file. 237 */ 238 private String commentCharsUsedInInput = COMMENT_CHARS; 239 240 /** 241 * The flag for decision, whether inline comments on the section line are allowed. 242 */ 243 private boolean sectionInLineCommentsAllowed; 244 245 /** 246 * Create a new empty INI Configuration. 247 */ 248 public INIConfiguration() { 249 } 250 251 /** 252 * Creates a new instance of {@code INIConfiguration} with the content of the specified 253 * {@code HierarchicalConfiguration}. 254 * 255 * @param c the configuration to be copied 256 * @since 2.0 257 */ 258 public INIConfiguration(final HierarchicalConfiguration<ImmutableNode> c) { 259 super(c); 260 } 261 262 /** 263 * Create a new empty INI Configuration with option to allow inline comments on the section line. 264 * 265 * @param sectionInLineCommentsAllowed when true inline comments on the section line are allowed 266 */ 267 private INIConfiguration(final boolean sectionInLineCommentsAllowed) { 268 this.sectionInLineCommentsAllowed = sectionInLineCommentsAllowed; 269 } 270 271 /** 272 * Creates a new builder. 273 * 274 * @return a new builder. 275 * @since 2.9.0 276 */ 277 public static Builder builder() { 278 return new Builder(); 279 } 280 281 /** 282 * Builds instances of INIConfiguration. 283 * 284 * @since 2.9.0 285 */ 286 public static class Builder { 287 288 /** 289 * The flag for decision, whether inline comments on the section line are allowed. 290 */ 291 private boolean sectionInLineCommentsAllowed; 292 293 public Builder setSectionInLineCommentsAllowed(final boolean sectionInLineCommentsAllowed) { 294 this.sectionInLineCommentsAllowed = sectionInLineCommentsAllowed; 295 return this; 296 } 297 298 public INIConfiguration build() { 299 return new INIConfiguration(sectionInLineCommentsAllowed); 300 } 301 302 } 303 304 /** 305 * Get separator used in INI output. see {@code setSeparatorUsedInOutput} for further explanation 306 * 307 * @return the current separator for writing the INI output 308 * @since 2.2 309 */ 310 public String getSeparatorUsedInOutput() { 311 beginRead(false); 312 try { 313 return separatorUsedInOutput; 314 } finally { 315 endRead(); 316 } 317 } 318 319 /** 320 * Allows setting the key and value separator which is used for the creation of the resulting INI output 321 * 322 * @param separator String of the new separator for INI output 323 * @since 2.2 324 */ 325 public void setSeparatorUsedInOutput(final String separator) { 326 beginWrite(false); 327 try { 328 this.separatorUsedInOutput = separator; 329 } finally { 330 endWrite(); 331 } 332 } 333 334 /** 335 * Get separator used in INI reading. see {@code setSeparatorUsedInInput} for further explanation 336 * 337 * @return the current separator for reading the INI input 338 * @since 2.5 339 */ 340 public String getSeparatorUsedInInput() { 341 beginRead(false); 342 try { 343 return separatorUsedInInput; 344 } finally { 345 endRead(); 346 } 347 } 348 349 /** 350 * Allows setting the key and value separator which is used in reading an INI file 351 * 352 * @param separator String of the new separator for INI reading 353 * @since 2.5 354 */ 355 public void setSeparatorUsedInInput(final String separator) { 356 beginRead(false); 357 try { 358 this.separatorUsedInInput = separator; 359 } finally { 360 endRead(); 361 } 362 } 363 364 /** 365 * Get comment leading separator used in INI reading. see {@code setCommentLeadingCharsUsedInInput} for further 366 * explanation 367 * 368 * @return the current separator for reading the INI input 369 * @since 2.5 370 */ 371 public String getCommentLeadingCharsUsedInInput() { 372 beginRead(false); 373 try { 374 return commentCharsUsedInInput; 375 } finally { 376 endRead(); 377 } 378 } 379 380 /** 381 * Allows setting the leading comment separator which is used in reading an INI file 382 * 383 * @param separator String of the new separator for INI reading 384 * @since 2.5 385 */ 386 public void setCommentLeadingCharsUsedInInput(final String separator) { 387 beginRead(false); 388 try { 389 this.commentCharsUsedInInput = separator; 390 } finally { 391 endRead(); 392 } 393 } 394 395 /** 396 * Save the configuration to the specified writer. 397 * 398 * @param writer - The writer to save the configuration to. 399 * @throws ConfigurationException If an error occurs while writing the configuration 400 * @throws IOException if an I/O error occurs. 401 */ 402 @Override 403 public void write(final Writer writer) throws ConfigurationException, IOException { 404 final PrintWriter out = new PrintWriter(writer); 405 boolean first = true; 406 final String separator = getSeparatorUsedInOutput(); 407 408 beginRead(false); 409 try { 410 for (final ImmutableNode node : getModel().getNodeHandler().getRootNode().getChildren()) { 411 if (isSectionNode(node)) { 412 if (!first) { 413 out.println(); 414 } 415 out.print("["); 416 out.print(node.getNodeName()); 417 out.print("]"); 418 out.println(); 419 420 node.forEach(child -> writeProperty(out, child.getNodeName(), child.getValue(), separator)); 421 } else { 422 writeProperty(out, node.getNodeName(), node.getValue(), separator); 423 } 424 first = false; 425 } 426 out.println(); 427 out.flush(); 428 } finally { 429 endRead(); 430 } 431 } 432 433 /** 434 * Load the configuration from the given reader. Note that the {@code clear()} method is not called so the configuration 435 * read in will be merged with the current configuration. 436 * 437 * @param in the reader to read the configuration from. 438 * @throws ConfigurationException If an error occurs while reading the configuration 439 * @throws IOException if an I/O error occurs. 440 */ 441 @Override 442 public void read(final Reader in) throws ConfigurationException, IOException { 443 final BufferedReader bufferedReader = new BufferedReader(in); 444 final Map<String, ImmutableNode.Builder> sectionBuilders = new LinkedHashMap<>(); 445 final ImmutableNode.Builder rootBuilder = new ImmutableNode.Builder(); 446 447 createNodeBuilders(bufferedReader, rootBuilder, sectionBuilders); 448 final ImmutableNode rootNode = createNewRootNode(rootBuilder, sectionBuilders); 449 addNodes(null, rootNode.getChildren()); 450 } 451 452 /** 453 * Creates a new root node from the builders constructed while reading the configuration file. 454 * 455 * @param rootBuilder the builder for the top-level section 456 * @param sectionBuilders a map storing the section builders 457 * @return the root node of the newly created hierarchy 458 */ 459 private static ImmutableNode createNewRootNode(final ImmutableNode.Builder rootBuilder, final Map<String, ImmutableNode.Builder> sectionBuilders) { 460 sectionBuilders.forEach((k, v) -> rootBuilder.addChild(v.name(k).create())); 461 return rootBuilder.create(); 462 } 463 464 /** 465 * Reads the content of an INI file from the passed in reader and creates a structure of builders for constructing the 466 * {@code ImmutableNode} objects representing the data. 467 * 468 * @param in the reader 469 * @param rootBuilder the builder for the top-level section 470 * @param sectionBuilders a map storing the section builders 471 * @throws IOException if an I/O error occurs. 472 */ 473 private void createNodeBuilders(final BufferedReader in, final ImmutableNode.Builder rootBuilder, final Map<String, ImmutableNode.Builder> sectionBuilders) 474 throws IOException { 475 ImmutableNode.Builder sectionBuilder = rootBuilder; 476 String line = in.readLine(); 477 while (line != null) { 478 line = line.trim(); 479 if (!isCommentLine(line)) { 480 if (isSectionLine(line)) { 481 final int length = sectionInLineCommentsAllowed ? line.indexOf("]") : line.length() - 1; 482 final String section = line.substring(1, length); 483 sectionBuilder = sectionBuilders.get(section); 484 if (sectionBuilder == null) { 485 sectionBuilder = new ImmutableNode.Builder(); 486 sectionBuilders.put(section, sectionBuilder); 487 } 488 } else { 489 String key; 490 String value = ""; 491 final int index = findSeparator(line); 492 if (index >= 0) { 493 key = line.substring(0, index); 494 value = parseValue(line.substring(index + 1), in); 495 } else { 496 key = line; 497 } 498 key = key.trim(); 499 if (key.isEmpty()) { 500 // use space for properties with no key 501 key = " "; 502 } 503 createValueNodes(sectionBuilder, key, value); 504 } 505 } 506 507 line = in.readLine(); 508 } 509 } 510 511 /** 512 * Creates the node(s) for the given key value-pair. If delimiter parsing is enabled, the value string is split if 513 * possible, and for each single value a node is created. Otherwise only a single node is added to the section. 514 * 515 * @param sectionBuilder the section builder for adding new nodes 516 * @param key the key 517 * @param value the value string 518 */ 519 private void createValueNodes(final ImmutableNode.Builder sectionBuilder, final String key, final String value) { 520 getListDelimiterHandler().split(value, false).forEach(v -> sectionBuilder.addChild(new ImmutableNode.Builder().name(key).value(v).create())); 521 } 522 523 /** 524 * Writes data about a property into the given stream. 525 * 526 * @param out the output stream 527 * @param key the key 528 * @param value the value 529 */ 530 private void writeProperty(final PrintWriter out, final String key, final Object value, final String separator) { 531 out.print(key); 532 out.print(separator); 533 out.print(escapeValue(value.toString())); 534 out.println(); 535 } 536 537 /** 538 * Parse the value to remove the quotes and ignoring the comment. Example: 539 * 540 * <pre> 541 * "value" ; comment -> value 542 * </pre> 543 * 544 * <pre> 545 * 'value' ; comment -> value 546 * </pre> 547 * 548 * Note that a comment character is only recognized if there is at least one whitespace character before it. So it can 549 * appear in the property value, e.g.: 550 * 551 * <pre> 552 * C:\\Windows;C:\\Windows\\system32 553 * </pre> 554 * 555 * @param val the value to be parsed 556 * @param reader the reader (needed if multiple lines have to be read) 557 * @throws IOException if an IO error occurs 558 */ 559 private String parseValue(final String val, final BufferedReader reader) throws IOException { 560 final StringBuilder propertyValue = new StringBuilder(); 561 boolean lineContinues; 562 String value = val.trim(); 563 564 do { 565 final boolean quoted = value.startsWith("\"") || value.startsWith("'"); 566 boolean stop = false; 567 boolean escape = false; 568 569 final char quote = quoted ? value.charAt(0) : 0; 570 571 int i = quoted ? 1 : 0; 572 573 final StringBuilder result = new StringBuilder(); 574 char lastChar = 0; 575 while (i < value.length() && !stop) { 576 final char c = value.charAt(i); 577 578 if (quoted) { 579 if ('\\' == c && !escape) { 580 escape = true; 581 } else if (!escape && quote == c) { 582 stop = true; 583 } else { 584 if (escape && quote == c) { 585 escape = false; 586 } else if (escape) { 587 escape = false; 588 result.append('\\'); 589 } 590 result.append(c); 591 } 592 } else if (isCommentChar(c) && Character.isWhitespace(lastChar)) { 593 stop = true; 594 } else { 595 result.append(c); 596 } 597 598 i++; 599 lastChar = c; 600 } 601 602 String v = result.toString(); 603 if (!quoted) { 604 v = v.trim(); 605 lineContinues = lineContinues(v); 606 if (lineContinues) { 607 // remove trailing "\" 608 v = v.substring(0, v.length() - 1).trim(); 609 } 610 } else { 611 lineContinues = lineContinues(value, i); 612 } 613 propertyValue.append(v); 614 615 if (lineContinues) { 616 propertyValue.append(LINE_SEPARATOR); 617 value = reader.readLine(); 618 } 619 } while (lineContinues && value != null); 620 621 return propertyValue.toString(); 622 } 623 624 /** 625 * Tests whether the specified string contains a line continuation marker. 626 * 627 * @param line the string to check 628 * @return a flag whether this line continues 629 */ 630 private static boolean lineContinues(final String line) { 631 final String s = line.trim(); 632 return s.equals(LINE_CONT) || s.length() > 2 && s.endsWith(LINE_CONT) && Character.isWhitespace(s.charAt(s.length() - 2)); 633 } 634 635 /** 636 * Tests whether the specified string contains a line continuation marker after the specified position. This method 637 * parses the string to remove a comment that might be present. Then it checks whether a line continuation marker can be 638 * found at the end. 639 * 640 * @param line the line to check 641 * @param pos the start position 642 * @return a flag whether this line continues 643 */ 644 private boolean lineContinues(final String line, final int pos) { 645 final String s; 646 647 if (pos >= line.length()) { 648 s = line; 649 } else { 650 int end = pos; 651 while (end < line.length() && !isCommentChar(line.charAt(end))) { 652 end++; 653 } 654 s = line.substring(pos, end); 655 } 656 657 return lineContinues(s); 658 } 659 660 /** 661 * Tests whether the specified character is a comment character. 662 * 663 * @param c the character 664 * @return a flag whether this character starts a comment 665 */ 666 private boolean isCommentChar(final char c) { 667 return getCommentLeadingCharsUsedInInput().indexOf(c) >= 0; 668 } 669 670 /** 671 * Tries to find the index of the separator character in the given string. This method checks for the presence of 672 * separator characters in the given string. If multiple characters are found, the first one is assumed to be the 673 * correct separator. If there are quoting characters, they are taken into account, too. 674 * 675 * @param line the line to be checked 676 * @return the index of the separator character or -1 if none is found 677 */ 678 private int findSeparator(final String line) { 679 int index = findSeparatorBeforeQuote(line, findFirstOccurrence(line, QUOTE_CHARACTERS)); 680 if (index < 0) { 681 index = findFirstOccurrence(line, getSeparatorUsedInInput()); 682 } 683 return index; 684 } 685 686 /** 687 * Checks for the occurrence of the specified separators in the given line. The index of the first separator is 688 * returned. 689 * 690 * @param line the line to be investigated 691 * @param separators a string with the separator characters to look for 692 * @return the lowest index of a separator character or -1 if no separator is found 693 */ 694 private static int findFirstOccurrence(final String line, final String separators) { 695 int index = -1; 696 697 for (int i = 0; i < separators.length(); i++) { 698 final char sep = separators.charAt(i); 699 final int pos = line.indexOf(sep); 700 if (pos >= 0 && (index < 0 || pos < index)) { 701 index = pos; 702 } 703 } 704 705 return index; 706 } 707 708 /** 709 * Searches for a separator character directly before a quoting character. If the first non-whitespace character before 710 * a quote character is a separator, it is considered the "real" separator in this line - even if there are other 711 * separators before. 712 * 713 * @param line the line to be investigated 714 * @param quoteIndex the index of the quote character 715 * @return the index of the separator before the quote or < 0 if there is none 716 */ 717 private static int findSeparatorBeforeQuote(final String line, final int quoteIndex) { 718 int index = quoteIndex - 1; 719 while (index >= 0 && Character.isWhitespace(line.charAt(index))) { 720 index--; 721 } 722 723 if (index >= 0 && SEPARATOR_CHARS.indexOf(line.charAt(index)) < 0) { 724 index = -1; 725 } 726 727 return index; 728 } 729 730 /** 731 * Escapes the given property value before it is written. This method add quotes around the specified value if it 732 * contains a comment character and handles list delimiter characters. 733 * 734 * @param value the string to be escaped 735 */ 736 private String escapeValue(final String value) { 737 return String.valueOf(getListDelimiterHandler().escape(escapeComments(value), ListDelimiterHandler.NOOP_TRANSFORMER)); 738 } 739 740 /** 741 * Escapes comment characters in the given value. 742 * 743 * @param value the value to be escaped 744 * @return the value with comment characters escaped 745 */ 746 private String escapeComments(final String value) { 747 final String commentChars = getCommentLeadingCharsUsedInInput(); 748 boolean quoted = false; 749 750 for (int i = 0; i < commentChars.length(); i++) { 751 final char c = commentChars.charAt(i); 752 if (value.indexOf(c) != -1) { 753 quoted = true; 754 break; 755 } 756 } 757 758 if (quoted) { 759 return '"' + value.replace("\"", "\\\"") + '"'; 760 } 761 return value; 762 } 763 764 /** 765 * Determine if the given line is a comment line. 766 * 767 * @param line The line to check. 768 * @return true if the line is empty or starts with one of the comment characters 769 */ 770 protected boolean isCommentLine(final String line) { 771 if (line == null) { 772 return false; 773 } 774 // blank lines are also treated as comment lines 775 return line.isEmpty() || getCommentLeadingCharsUsedInInput().indexOf(line.charAt(0)) >= 0; 776 } 777 778 /** 779 * Determine if the given line is a section. 780 * 781 * @param line The line to check. 782 * @return true if the line contains a section 783 */ 784 protected boolean isSectionLine(final String line) { 785 if (line == null) { 786 return false; 787 } 788 return sectionInLineCommentsAllowed ? isNonStrictSection(line) : isStrictSection(line); 789 } 790 791 /** 792 * Determine if the entire given line is a section - inline comments are not allowed. 793 * 794 * @param line The line to check. 795 * @return true if the entire line is a section 796 */ 797 private static boolean isStrictSection(final String line) { 798 return line.startsWith("[") && line.endsWith("]"); 799 } 800 801 /** 802 * Determine if the given line contains a section - inline comments are allowed. 803 * 804 * @param line The line to check. 805 * @return true if the line contains a section 806 */ 807 private static boolean isNonStrictSection(final String line) { 808 return line.startsWith("[") && line.contains("]"); 809 } 810 811 /** 812 * Return a set containing the sections in this ini configuration. Note that changes to this set do not affect the 813 * configuration. 814 * 815 * @return a set containing the sections. 816 */ 817 public Set<String> getSections() { 818 final Set<String> sections = new LinkedHashSet<>(); 819 boolean globalSection = false; 820 boolean inSection = false; 821 822 beginRead(false); 823 try { 824 for (final ImmutableNode node : getModel().getNodeHandler().getRootNode().getChildren()) { 825 if (isSectionNode(node)) { 826 inSection = true; 827 sections.add(node.getNodeName()); 828 } else if (!inSection && !globalSection) { 829 globalSection = true; 830 sections.add(null); 831 } 832 } 833 } finally { 834 endRead(); 835 } 836 837 return sections; 838 } 839 840 /** 841 * Gets a configuration with the content of the specified section. This provides an easy way of working with a single 842 * section only. The way this configuration is structured internally, this method is very similar to calling 843 * {@link HierarchicalConfiguration#configurationAt(String)} with the name of the section in question. There are the 844 * following differences however: 845 * <ul> 846 * <li>This method never throws an exception. If the section does not exist, it is created now. The configuration 847 * returned in this case is empty.</li> 848 * <li>If section is contained multiple times in the configuration, the configuration returned by this method is 849 * initialized with the first occurrence of the section. (This can only happen if {@code addProperty()} has been used in 850 * a way that does not conform to the storage scheme used by {@code INIConfiguration}. If used correctly, there will not 851 * be duplicate sections.)</li> 852 * <li>There is special support for the global section: Passing in <b>null</b> as section name returns a configuration 853 * with the content of the global section (which may also be empty).</li> 854 * </ul> 855 * 856 * @param name the name of the section in question; <b>null</b> represents the global section 857 * @return a configuration containing only the properties of the specified section 858 */ 859 public SubnodeConfiguration getSection(final String name) { 860 if (name == null) { 861 return getGlobalSection(); 862 } 863 try { 864 return (SubnodeConfiguration) configurationAt(name, true); 865 } catch (final ConfigurationRuntimeException iex) { 866 // the passed in key does not map to exactly one node 867 // obtain the node for the section, create it on demand 868 final InMemoryNodeModel parentModel = getSubConfigurationParentModel(); 869 final NodeSelector selector = parentModel.trackChildNodeWithCreation(null, name, this); 870 return createSubConfigurationForTrackedNode(selector, this); 871 } 872 } 873 874 /** 875 * Creates a sub configuration for the global section of the represented INI configuration. 876 * 877 * @return the sub configuration for the global section 878 */ 879 private SubnodeConfiguration getGlobalSection() { 880 final InMemoryNodeModel parentModel = getSubConfigurationParentModel(); 881 final NodeSelector selector = new NodeSelector(null); // selects parent 882 parentModel.trackNode(selector, this); 883 final GlobalSectionNodeModel model = new GlobalSectionNodeModel(this, selector); 884 final SubnodeConfiguration sub = new SubnodeConfiguration(this, model); 885 initSubConfigurationForThisParent(sub); 886 return sub; 887 } 888 889 /** 890 * Checks whether the specified configuration node represents a section. 891 * 892 * @param node the node in question 893 * @return a flag whether this node represents a section 894 */ 895 private static boolean isSectionNode(final ImmutableNode node) { 896 return node.getValue() == null; 897 } 898 899 /** 900 * A specialized node model implementation for the sub configuration representing the global section of the INI file. 901 * This is a regular {@code TrackedNodeModel} with one exception: The {@code NodeHandler} used by this model applies a 902 * filter on the children of the root node so that only nodes are visible that are no sub sections. 903 */ 904 private static class GlobalSectionNodeModel extends TrackedNodeModel { 905 /** 906 * Creates a new instance of {@code GlobalSectionNodeModel} and initializes it with the given underlying model. 907 * 908 * @param modelSupport the underlying {@code InMemoryNodeModel} 909 * @param selector the {@code NodeSelector} 910 */ 911 public GlobalSectionNodeModel(final InMemoryNodeModelSupport modelSupport, final NodeSelector selector) { 912 super(modelSupport, selector, true); 913 } 914 915 @Override 916 public NodeHandler<ImmutableNode> getNodeHandler() { 917 return new NodeHandlerDecorator<ImmutableNode>() { 918 @Override 919 public List<ImmutableNode> getChildren(final ImmutableNode node) { 920 final List<ImmutableNode> children = super.getChildren(node); 921 return filterChildrenOfGlobalSection(node, children); 922 } 923 924 @Override 925 public List<ImmutableNode> getChildren(final ImmutableNode node, final String name) { 926 final List<ImmutableNode> children = super.getChildren(node, name); 927 return filterChildrenOfGlobalSection(node, children); 928 } 929 930 @Override 931 public int getChildrenCount(final ImmutableNode node, final String name) { 932 final List<ImmutableNode> children = name != null ? super.getChildren(node, name) : super.getChildren(node); 933 return filterChildrenOfGlobalSection(node, children).size(); 934 } 935 936 @Override 937 public ImmutableNode getChild(final ImmutableNode node, final int index) { 938 final List<ImmutableNode> children = super.getChildren(node); 939 return filterChildrenOfGlobalSection(node, children).get(index); 940 } 941 942 @Override 943 public int indexOfChild(final ImmutableNode parent, final ImmutableNode child) { 944 final List<ImmutableNode> children = super.getChildren(parent); 945 return filterChildrenOfGlobalSection(parent, children).indexOf(child); 946 } 947 948 @Override 949 protected NodeHandler<ImmutableNode> getDecoratedNodeHandler() { 950 return GlobalSectionNodeModel.super.getNodeHandler(); 951 } 952 953 /** 954 * Filters the child nodes of the global section. This method checks whether the passed in node is the root node of the 955 * configuration. If so, from the list of children all nodes are filtered which are section nodes. 956 * 957 * @param node the node in question 958 * @param children the children of this node 959 * @return a list with the filtered children 960 */ 961 private List<ImmutableNode> filterChildrenOfGlobalSection(final ImmutableNode node, final List<ImmutableNode> children) { 962 final List<ImmutableNode> filteredList; 963 if (node == getRootNode()) { 964 filteredList = children.stream().filter(child -> !isSectionNode(child)).collect(Collectors.toList()); 965 } else { 966 filteredList = children; 967 } 968 969 return filteredList; 970 } 971 }; 972 } 973 } 974}