Open Source Repository

Home /commons-configuration/commons-configuration-1.7 | Repository Home



org/apache/commons/configuration/INIConfiguration.java
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.configuration;

import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.Reader;
import java.io.Writer;
import java.net.URL;
import java.util.Collection;
import java.util.Iterator;
import java.util.Set;
import java.util.TreeSet;

import org.apache.commons.lang.StringUtils;

/**
 <p>
 * An initialization or ini file is a configuration file typically found on
 * Microsoft's Windows operating system and contains data for Windows based
 * applications.
 </p>
 *
 <p>
 * Although popularized by Windows, ini files can be used on any system or
 * platform due to the fact that they are merely text files that can easily be
 * parsed and modified by both humans and computers.
 </p>
 *
 <p>
 * A typcial ini file could look something like:
 </p>
 <code>
 * [section1]<br>
 * ; this is a comment!<br>
 * var1 = foo<br>
 * var2 = bar<br>
 *<br>
 * [section2]<br>
 * var1 = doo<br>
 </code>
 *
 <p>
 * The format of ini files is fairly straight forward and is composed of three
 * components:<br>
 <ul>
 <li><b>Sections:</b> Ini files are split into sections, each section
 * starting with a section declaration. A section declaration starts with a '['
 * and ends with a ']'. Sections occur on one line only.</li>
 <li><b>Parameters:</b> Items in a section are known as parameters.
 * Parameters have a typical <code>key = value</code> format.</li>
 <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.
 </li>
 </ul>
 </p>
 *
 <p>
 * There are various implementations of the ini file format by various vendors
 * which has caused a number of differences to appear. As far as possible this
 * configuration tries to be lenient and support most of the differences.
 </p>
 *
 <p>
 * Some of the differences supported are as follows:
 <ul>
 <li><b>Comments:</b> The '#' character is also accepted as a comment
 * signifier.</li>
 <li><b>Key value separtor:</b> The ':' character is also accepted in place
 * of '=' to separate keys and values in parameters, for example
 <code>var1 : foo</code>.</li>
 <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed ,
 * this configuration does however support it. In the event of a duplicate
 * section, the two section's values are merged.</li>
 <li><b>Duplicate parameters:</b> Typically duplicate parameters are only
 * allowed if they are in two different sections, thus they are local to
 * sections; this configuration simply merges duplicates; if a section has a
 * duplicate parameter the values are then added to the key as a list. </li>
 </ul>
 </p>
 <p>
 * Global parameters are also allowed; any parameters declared before a section
 * is declared are added to a global section. It is important to note that this
 * global section does not have a name.
 </p>
 <p>
 * In all instances, a parameter's key is prepended with its section name and a
 * '.' (period). Thus a parameter named "var1" in "section1" will have the key
 <code>section1.var1</code> in this configuration. Thus, a section's
 * parameters can easily be retrieved using the <code>subset</code> method
 * using the section name as the prefix.
 </p>
 <p>
 <h3>Implementation Details:</h3>
 * Consider the following ini file:<br>
 <code>
 *  default = ok<br>
 *  <br>
 *  [section1]<br>
 *  var1 = foo<br>
 *  var2 = doodle<br>
 *   <br>
 *  [section2]<br>
 *  ; a comment<br>
 *  var1 = baz<br>
 *  var2 = shoodle<br>
 *  bad =<br>
 *  = worse<br>
 *  <br>
 *  [section3]<br>
 *  # another comment<br>
 *  var1 : foo<br>
 *  var2 : bar<br>
 *  var5 : test1<br>
 *  <br>
 *  [section3]<br>
 *  var3 = foo<br>
 *  var4 = bar<br>
 *  var5 = test2<br>
 *  </code>
 </p>
 <p>
 * This ini file will be parsed without error. Note:
 <ul>
 <li>The parameter named "default" is added to the global section, it's value
 * is accessed simply using <code>getProperty("default")</code>.</li>
 <li>Section 1's parameters can be accessed using
 <code>getProperty("section1.var1")</code>.</li>
 <li>The parameter named "bad" simply adds the parameter with an empty value.
 </li>
 <li>The empty key with value "= worse" is added using an empty key. This key
 * is still added to section 2 and the value can be accessed using
 <code>getProperty("section2.")</code>, notice the period '.' following the
 * section name.</li>
 <li>Section three uses both '=' and ':' to separate keys and values.</li>
 <li>Section 3 has a duplicate key named "var5". The value for this key is
 * [test1, test2], and is represented as a List.</li>
 </ul>
 </p>
 <p>
 * The set of sections in this configuration can be retrieved using the
 <code>getSections</code> method.
 </p>
 <p>
 <em>Note:</em> Configuration objects of this type can be read concurrently
 * by multiple threads. However if one of these threads modifies the object,
 * synchronization has to be performed manually.
 </p>
 *
 @author Trevor Miller
 @version $Id: INIConfiguration.java 720600 2008-11-25 21:20:01Z oheger $
 @since 1.4
 @deprecated This class has been replaced by HierarchicalINIConfiguration,
 * which provides a superset of the functionality offered by this class.
 */
public class INIConfiguration extends AbstractFileConfiguration
{
    /**
     * The characters that signal the start of a comment line.
     */
    protected static final String COMMENT_CHARS = "#;";

    /**
     * The characters used to separate keys from values.
     */
    protected static final String SEPARATOR_CHARS = "=:";

    /**
     * Create a new empty INI Configuration.
     */
    public INIConfiguration()
    {
        super();
    }

    /**
     * Create and load the ini configuration from the given file.
     *
     @param filename The name pr path of the ini file to load.
     @throws ConfigurationException If an error occurs while loading the file
     */
    public INIConfiguration(String filenamethrows ConfigurationException
    {
        super(filename);
    }

    /**
     * Create and load the ini configuration from the given file.
     *
     @param file The ini file to load.
     @throws ConfigurationException If an error occurs while loading the file
     */
    public INIConfiguration(File filethrows ConfigurationException
    {
        super(file);
    }

    /**
     * Create and load the ini configuration from the given url.
     *
     @param url The url of the ini file to load.
     @throws ConfigurationException If an error occurs while loading the file
     */
    public INIConfiguration(URL urlthrows ConfigurationException
    {
        super(url);
    }

    /**
     * Save the configuration to the specified writer.
     *
     @param writer - The writer to save the configuration to.
     @throws ConfigurationException If an error occurs while writing the
     * configuration
     */
    public void save(Writer writerthrows ConfigurationException
    {
        PrintWriter out = new PrintWriter(writer);
        Iterator it = getSections().iterator();
        while (it.hasNext())
        {
            String section = (Stringit.next();
            out.print("[");
            out.print(section);
            out.print("]");
            out.println();

            Configuration subset = subset(section);
            Iterator keys = subset.getKeys();
            while (keys.hasNext())
            {
                String key = (Stringkeys.next();
                Object value = subset.getProperty(key);
                if (value instanceof Collection)
                {
                    Iterator values = ((Collectionvalue).iterator();
                    while (values.hasNext())
                    {
                        value = (Objectvalues.next();
                        out.print(key);
                        out.print(" = ");
                        out.print(formatValue(value.toString()));
                        out.println();
                    }
                }
                else
                {
                    out.print(key);
                    out.print(" = ");
                    out.print(formatValue(value.toString()));
                    out.println();
                }
            }

            out.println();
        }

        out.flush();
    }

    /**
     * Load the configuration from the given reader. Note that the
     <code>clear</code> method is not called so the configuration read in
     * will be merged with the current configuration.
     *
     @param reader The reader to read the configuration from.
     @throws ConfigurationException If an error occurs while reading the
     * configuration
     */
    public void load(Reader readerthrows ConfigurationException
    {
        try
        {
            BufferedReader bufferedReader = new BufferedReader(reader);
            String line = bufferedReader.readLine();
            String section = "";
            while (line != null)
            {
                line = line.trim();
                if (!isCommentLine(line))
                {
                    if (isSectionLine(line))
                    {
                        section = line.substring(1, line.length() 1".";
                    }
                    else
                    {
                        String key = "";
                        String value = "";
                        int index = line.indexOf("=");
                        if (index >= 0)
                        {
                            key = section + line.substring(0, index);
                            value = parseValue(line.substring(index + 1));
                        }
                        else
                        {
                            index = line.indexOf(":");
                            if (index >= 0)
                            {
                                key = section + line.substring(0, index);
                                value = parseValue(line.substring(index + 1));
                            }
                            else
                            {
                                key = section + line;
                            }
                        }
                        addProperty(key.trim(), value);
                    }
                }
                line = bufferedReader.readLine();
            }
        }
        catch (IOException e)
        {
            throw new ConfigurationException("Unable to load the configuration", e);
        }
    }

    /**
     * Parse the value to remove the quotes and ignoring the comment.
     * Example:
     *
     <pre>"value" ; comment -> value</pre>
     *
     <pre>'value' ; comment -> value</pre>
     *
     @param value
     */
    private String parseValue(String value)
    {
        value = value.trim();

        boolean quoted = value.startsWith("\""|| value.startsWith("'");
        boolean stop = false;
        boolean escape = false;

        char quote = quoted ? value.charAt(00;

        int i = quoted ? 0;

        StringBuffer result = new StringBuffer();
        while (i < value.length() && !stop)
        {
            char c = value.charAt(i);

            if (quoted)
            {
                if ('\\' == c && !escape)
                {
                    escape = true;
                }
                else if (!escape && quote == c)
                {
                    stop = true;
                }
                else if (escape && quote == c)
                {
                    escape = false;
                    result.append(c);
                }
                else
                {
                    if (escape)
                    {
                        escape = false;
                        result.append('\\');
                    }

                    result.append(c);
                }
            }
            else
            {
                if (COMMENT_CHARS.indexOf(c== -1)
                {
                    result.append(c);
                }
                else
                {
                    stop = true;
                }
            }

            i++;
        }

        String v = result.toString();
        if (!quoted)
        {
            v = v.trim();
        }
        return v;
    }

    /**
     * Add quotes around the specified value if it contains a comment character.
     */
    private String formatValue(String value)
    {
        boolean quoted = false;

        for (int i = 0; i < COMMENT_CHARS.length() && !quoted; i++)
        {
            char c = COMMENT_CHARS.charAt(i);
            if (value.indexOf(c!= -1)
            {
                quoted = true;
            }
        }

        if (quoted)
        {
            return '"' + StringUtils.replace(value, "\"""\\\""'"';
        }
        else
        {
            return value;
        }
    }

    /**
     * Determine if the given line is a comment line.
     *
     @param line The line to check.
     @return true if the line is empty or starts with one of the comment
     * characters
     */
    protected boolean isCommentLine(String line)
    {
        if (line == null)
        {
            return false;
        }
        // blank lines are also treated as comment lines
        return line.length() || COMMENT_CHARS.indexOf(line.charAt(0)) >= 0;
    }

    /**
     * Determine if the given line is a section.
     *
     @param line The line to check.
     @return true if the line contains a secion
     */
    protected boolean isSectionLine(String line)
    {
        if (line == null)
        {
            return false;
        }
        return line.startsWith("["&& line.endsWith("]");
    }

    /**
     * Return a set containing the sections in this ini configuration. Note that
     * changes to this set do not affect the configuration.
     *
     @return a set containing the sections.
     */
    public Set getSections()
    {
        Set sections = new TreeSet();

        Iterator keys = getKeys();
        while (keys.hasNext())
        {
            String key = (Stringkeys.next();
            int index = key.indexOf(".");
            if (index >= 0)
            {
                sections.add(key.substring(0, index));
            }
        }

        return sections;
    }
}