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