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     */
017    
018    package org.apache.commons.configuration;
019    
020    import java.io.BufferedReader;
021    import java.io.File;
022    import java.io.IOException;
023    import java.io.PrintWriter;
024    import java.io.Reader;
025    import java.io.Writer;
026    import java.net.URL;
027    import java.util.Collection;
028    import java.util.Iterator;
029    import java.util.Set;
030    import java.util.TreeSet;
031    
032    import org.apache.commons.lang.StringUtils;
033    
034    /**
035     * <p>
036     * An initialization or ini file is a configuration file typically found on
037     * Microsoft's Windows operating system and contains data for Windows based
038     * applications.
039     * </p>
040     *
041     * <p>
042     * Although popularized by Windows, ini files can be used on any system or
043     * platform due to the fact that they are merely text files that can easily be
044     * parsed and modified by both humans and computers.
045     * </p>
046     *
047     * <p>
048     * A typcial ini file could look something like:
049     * </p>
050     * <code>
051     * [section1]<br>
052     * ; this is a comment!<br>
053     * var1 = foo<br>
054     * var2 = bar<br>
055     *<br>
056     * [section2]<br>
057     * var1 = doo<br>
058     * </code>
059     *
060     * <p>
061     * The format of ini files is fairly straight forward and is composed of three
062     * components:<br>
063     * <ul>
064     * <li><b>Sections:</b> Ini files are split into sections, each section
065     * starting with a section declaration. A section declaration starts with a '['
066     * and ends with a ']'. Sections occur on one line only.</li>
067     * <li><b>Parameters:</b> Items in a section are known as parameters.
068     * Parameters have a typical <code>key = value</code> format.</li>
069     * <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.
070     * </li>
071     * </ul>
072     * </p>
073     *
074     * <p>
075     * There are various implementations of the ini file format by various vendors
076     * which has caused a number of differences to appear. As far as possible this
077     * configuration tries to be lenient and support most of the differences.
078     * </p>
079     *
080     * <p>
081     * Some of the differences supported are as follows:
082     * <ul>
083     * <li><b>Comments:</b> The '#' character is also accepted as a comment
084     * signifier.</li>
085     * <li><b>Key value separtor:</b> The ':' character is also accepted in place
086     * of '=' to separate keys and values in parameters, for example
087     * <code>var1 : foo</code>.</li>
088     * <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed ,
089     * this configuration does however support it. In the event of a duplicate
090     * section, the two section's values are merged.</li>
091     * <li><b>Duplicate parameters:</b> Typically duplicate parameters are only
092     * allowed if they are in two different sections, thus they are local to
093     * sections; this configuration simply merges duplicates; if a section has a
094     * duplicate parameter the values are then added to the key as a list. </li>
095     * </ul>
096     * </p>
097     * <p>
098     * Global parameters are also allowed; any parameters declared before a section
099     * is declared are added to a global section. It is important to note that this
100     * global section does not have a name.
101     * </p>
102     * <p>
103     * In all instances, a parameter's key is prepended with its section name and a
104     * '.' (period). Thus a parameter named "var1" in "section1" will have the key
105     * <code>section1.var1</code> in this configuration. Thus, a section's
106     * parameters can easily be retrieved using the <code>subset</code> method
107     * using the section name as the prefix.
108     * </p>
109     * <p>
110     * <h3>Implementation Details:</h3>
111     * Consider the following ini file:<br>
112     * <code>
113     *  default = ok<br>
114     *  <br>
115     *  [section1]<br>
116     *  var1 = foo<br>
117     *  var2 = doodle<br>
118     *   <br>
119     *  [section2]<br>
120     *  ; a comment<br>
121     *  var1 = baz<br>
122     *  var2 = shoodle<br>
123     *  bad =<br>
124     *  = worse<br>
125     *  <br>
126     *  [section3]<br>
127     *  # another comment<br>
128     *  var1 : foo<br>
129     *  var2 : bar<br>
130     *  var5 : test1<br>
131     *  <br>
132     *  [section3]<br>
133     *  var3 = foo<br>
134     *  var4 = bar<br>
135     *  var5 = test2<br>
136     *  </code>
137     * </p>
138     * <p>
139     * This ini file will be parsed without error. Note:
140     * <ul>
141     * <li>The parameter named "default" is added to the global section, it's value
142     * is accessed simply using <code>getProperty("default")</code>.</li>
143     * <li>Section 1's parameters can be accessed using
144     * <code>getProperty("section1.var1")</code>.</li>
145     * <li>The parameter named "bad" simply adds the parameter with an empty value.
146     * </li>
147     * <li>The empty key with value "= worse" is added using an empty key. This key
148     * is still added to section 2 and the value can be accessed using
149     * <code>getProperty("section2.")</code>, notice the period '.' following the
150     * section name.</li>
151     * <li>Section three uses both '=' and ':' to separate keys and values.</li>
152     * <li>Section 3 has a duplicate key named "var5". The value for this key is
153     * [test1, test2], and is represented as a List.</li>
154     * </ul>
155     * </p>
156     * <p>
157     * The set of sections in this configuration can be retrieved using the
158     * <code>getSections</code> method.
159     * </p>
160     * <p>
161     * <em>Note:</em> Configuration objects of this type can be read concurrently
162     * by multiple threads. However if one of these threads modifies the object,
163     * synchronization has to be performed manually.
164     * </p>
165     *
166     * @author Trevor Miller
167     * @version $Id: INIConfiguration.java 720600 2008-11-25 21:20:01Z oheger $
168     * @since 1.4
169     * @deprecated This class has been replaced by HierarchicalINIConfiguration,
170     * which provides a superset of the functionality offered by this class.
171     */
172    public class INIConfiguration extends AbstractFileConfiguration
173    {
174        /**
175         * The characters that signal the start of a comment line.
176         */
177        protected static final String COMMENT_CHARS = "#;";
178    
179        /**
180         * The characters used to separate keys from values.
181         */
182        protected static final String SEPARATOR_CHARS = "=:";
183    
184        /**
185         * Create a new empty INI Configuration.
186         */
187        public INIConfiguration()
188        {
189            super();
190        }
191    
192        /**
193         * Create and load the ini configuration from the given file.
194         *
195         * @param filename The name pr path of the ini file to load.
196         * @throws ConfigurationException If an error occurs while loading the file
197         */
198        public INIConfiguration(String filename) throws ConfigurationException
199        {
200            super(filename);
201        }
202    
203        /**
204         * Create and load the ini configuration from the given file.
205         *
206         * @param file The ini file to load.
207         * @throws ConfigurationException If an error occurs while loading the file
208         */
209        public INIConfiguration(File file) throws ConfigurationException
210        {
211            super(file);
212        }
213    
214        /**
215         * Create and load the ini configuration from the given url.
216         *
217         * @param url The url of the ini file to load.
218         * @throws ConfigurationException If an error occurs while loading the file
219         */
220        public INIConfiguration(URL url) throws ConfigurationException
221        {
222            super(url);
223        }
224    
225        /**
226         * Save the configuration to the specified writer.
227         *
228         * @param writer - The writer to save the configuration to.
229         * @throws ConfigurationException If an error occurs while writing the
230         * configuration
231         */
232        public void save(Writer writer) throws ConfigurationException
233        {
234            PrintWriter out = new PrintWriter(writer);
235            Iterator it = getSections().iterator();
236            while (it.hasNext())
237            {
238                String section = (String) it.next();
239                out.print("[");
240                out.print(section);
241                out.print("]");
242                out.println();
243    
244                Configuration subset = subset(section);
245                Iterator keys = subset.getKeys();
246                while (keys.hasNext())
247                {
248                    String key = (String) keys.next();
249                    Object value = subset.getProperty(key);
250                    if (value instanceof Collection)
251                    {
252                        Iterator values = ((Collection) value).iterator();
253                        while (values.hasNext())
254                        {
255                            value = (Object) values.next();
256                            out.print(key);
257                            out.print(" = ");
258                            out.print(formatValue(value.toString()));
259                            out.println();
260                        }
261                    }
262                    else
263                    {
264                        out.print(key);
265                        out.print(" = ");
266                        out.print(formatValue(value.toString()));
267                        out.println();
268                    }
269                }
270    
271                out.println();
272            }
273    
274            out.flush();
275        }
276    
277        /**
278         * Load the configuration from the given reader. Note that the
279         * <code>clear</code> method is not called so the configuration read in
280         * will be merged with the current configuration.
281         *
282         * @param reader The reader to read the configuration from.
283         * @throws ConfigurationException If an error occurs while reading the
284         * configuration
285         */
286        public void load(Reader reader) throws ConfigurationException
287        {
288            try
289            {
290                BufferedReader bufferedReader = new BufferedReader(reader);
291                String line = bufferedReader.readLine();
292                String section = "";
293                while (line != null)
294                {
295                    line = line.trim();
296                    if (!isCommentLine(line))
297                    {
298                        if (isSectionLine(line))
299                        {
300                            section = line.substring(1, line.length() - 1) + ".";
301                        }
302                        else
303                        {
304                            String key = "";
305                            String value = "";
306                            int index = line.indexOf("=");
307                            if (index >= 0)
308                            {
309                                key = section + line.substring(0, index);
310                                value = parseValue(line.substring(index + 1));
311                            }
312                            else
313                            {
314                                index = line.indexOf(":");
315                                if (index >= 0)
316                                {
317                                    key = section + line.substring(0, index);
318                                    value = parseValue(line.substring(index + 1));
319                                }
320                                else
321                                {
322                                    key = section + line;
323                                }
324                            }
325                            addProperty(key.trim(), value);
326                        }
327                    }
328                    line = bufferedReader.readLine();
329                }
330            }
331            catch (IOException e)
332            {
333                throw new ConfigurationException("Unable to load the configuration", e);
334            }
335        }
336    
337        /**
338         * Parse the value to remove the quotes and ignoring the comment.
339         * Example:
340         *
341         * <pre>"value" ; comment -> value</pre>
342         *
343         * <pre>'value' ; comment -> value</pre>
344         *
345         * @param value
346         */
347        private String parseValue(String value)
348        {
349            value = value.trim();
350    
351            boolean quoted = value.startsWith("\"") || value.startsWith("'");
352            boolean stop = false;
353            boolean escape = false;
354    
355            char quote = quoted ? value.charAt(0) : 0;
356    
357            int i = quoted ? 1 : 0;
358    
359            StringBuffer result = new StringBuffer();
360            while (i < value.length() && !stop)
361            {
362                char c = value.charAt(i);
363    
364                if (quoted)
365                {
366                    if ('\\' == c && !escape)
367                    {
368                        escape = true;
369                    }
370                    else if (!escape && quote == c)
371                    {
372                        stop = true;
373                    }
374                    else if (escape && quote == c)
375                    {
376                        escape = false;
377                        result.append(c);
378                    }
379                    else
380                    {
381                        if (escape)
382                        {
383                            escape = false;
384                            result.append('\\');
385                        }
386    
387                        result.append(c);
388                    }
389                }
390                else
391                {
392                    if (COMMENT_CHARS.indexOf(c) == -1)
393                    {
394                        result.append(c);
395                    }
396                    else
397                    {
398                        stop = true;
399                    }
400                }
401    
402                i++;
403            }
404    
405            String v = result.toString();
406            if (!quoted)
407            {
408                v = v.trim();
409            }
410            return v;
411        }
412    
413        /**
414         * Add quotes around the specified value if it contains a comment character.
415         */
416        private String formatValue(String value)
417        {
418            boolean quoted = false;
419    
420            for (int i = 0; i < COMMENT_CHARS.length() && !quoted; i++)
421            {
422                char c = COMMENT_CHARS.charAt(i);
423                if (value.indexOf(c) != -1)
424                {
425                    quoted = true;
426                }
427            }
428    
429            if (quoted)
430            {
431                return '"' + StringUtils.replace(value, "\"", "\\\"") + '"';
432            }
433            else
434            {
435                return value;
436            }
437        }
438    
439        /**
440         * Determine if the given line is a comment line.
441         *
442         * @param line The line to check.
443         * @return true if the line is empty or starts with one of the comment
444         * characters
445         */
446        protected boolean isCommentLine(String line)
447        {
448            if (line == null)
449            {
450                return false;
451            }
452            // blank lines are also treated as comment lines
453            return line.length() < 1 || COMMENT_CHARS.indexOf(line.charAt(0)) >= 0;
454        }
455    
456        /**
457         * Determine if the given line is a section.
458         *
459         * @param line The line to check.
460         * @return true if the line contains a secion
461         */
462        protected boolean isSectionLine(String line)
463        {
464            if (line == null)
465            {
466                return false;
467            }
468            return line.startsWith("[") && line.endsWith("]");
469        }
470    
471        /**
472         * Return a set containing the sections in this ini configuration. Note that
473         * changes to this set do not affect the configuration.
474         *
475         * @return a set containing the sections.
476         */
477        public Set getSections()
478        {
479            Set sections = new TreeSet();
480    
481            Iterator keys = getKeys();
482            while (keys.hasNext())
483            {
484                String key = (String) keys.next();
485                int index = key.indexOf(".");
486                if (index >= 0)
487                {
488                    sections.add(key.substring(0, index));
489                }
490            }
491    
492            return sections;
493        }
494    }