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     * &quot;value&quot; ; comment -&gt; value
542     * </pre>
543     *
544     * <pre>
545     * 'value' ; comment -&gt; 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 &lt; 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}