    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}