Ini.java

/*
 * Ini
 *
 * $Id$
 * $URL$
 */
package gov.usgs.util;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.PrintStream;
import java.io.PrintWriter;

import java.util.Collections;
import java.util.Iterator;
import java.util.Properties;
import java.util.HashMap;

/**
 * Ini is a Properties that supports sections.
 *
 * Format Rules:
 * <ul>
 * <li>Empty lines are ignored.
 * <li>Leading and trailing white space are ignored.
 * <li>Comments must be on separate lines, and begin with '#' or ';'.
 * <li>Properties are key value pairs delimited by an equals: key = value
 * <li>Section Names are on separate lines, begin with '[' and end with ']'. Any
 * whitespace around the brackets is ignored.
 * <li>Any properties before the first section are in the "null" section
 * </ul>
 *
 * Format Example:
 *
 * <pre>
 * #comment about the global
 * global = value
 *
 * # comment about this section
 * ; another comment about this section
 * [ Section Name ]
 * section = value
 * </pre>
 *
 */
public class Ini extends Properties {

  /** Serialization version. */
  private static final long serialVersionUID = 1L;

  /** Section names map to Section properties. */
  private HashMap<String, Properties> sections = new HashMap<String, Properties>();

  /** String for representing a comment start */
  public static final String COMMENT_START = ";";
  /** String for representing an alternate comment start */
  public static final String ALTERNATE_COMMENT_START = "#";

  /** String to represent a section start */
  public static final String SECTION_START = "[";
  /** String to represent a section end */
  public static final String SECTION_END = "]";
  /** String to delimit properties */
  public static final String PROPERTY_DELIMITER = "=";

  /**
   * Same as new Ini(null).
   */
  public Ini() {
    this(null);
  }

  /**
   * Construct a new Ini with defaults.
   *
   * @param properties a Properties or Ini object with defaults. If an Ini object,
   *                   also makes a shallow copy of sections.
   */
  public Ini(final Properties properties) {
    super(properties);

    if (properties instanceof Ini) {
      sections.putAll(((Ini) properties).getSections());
    }
  }

  /**
   * @return the section properties map.
   */
  public HashMap<String, Properties> getSections() {
    return sections;
  }

  /**
   * Get a section property.
   *
   * @param section the section, if null calls getProperty(key).
   * @param key     the property name.
   * @return value or property, or null if no matching property found.
   */
  public String getSectionProperty(String section, String key) {
    if (section == null) {
      return getProperty(key);
    } else {
      Properties props = sections.get(section);
      if (props != null) {
        return props.getProperty(key);
      } else {
        return null;
      }
    }
  }

  /**
   * Set a section property.
   *
   * @param section the section, if null calls super.setProperty(key, value).
   * @param key     the property name.
   * @param value   the property value.
   * @return any previous value for key.
   */
  public Object setSectionProperty(String section, String key, String value) {
    if (section == null) {
      return setProperty(key, value);
    } else {
      Properties props = sections.get(section);
      if (props == null) {
        // new section
        props = new Properties();
        sections.put(section, props);
      }
      return props.setProperty(key, value);
    }
  }

  /**
   * Read an Ini input stream.
   *
   * @param inStream the input stream to read.
   * @throws IOException if unable to parse input stream.
   */
  public void load(InputStream inStream) throws IOException {
    BufferedReader br = new BufferedReader(new InputStreamReader(inStream));

    // keep track of current line number
    int lineNumber = 0;
    // line being parsed
    String line;
    // section being parsed
    Properties section = null;

    while ((line = br.readLine()) != null) {
      lineNumber = lineNumber + 1;
      line = line.trim();

      // empty line or comment
      if (line.length() == 0 || line.startsWith(COMMENT_START) || line.startsWith(ALTERNATE_COMMENT_START)) {
        // ignore
        continue;
      }

      // section
      else if (line.startsWith(SECTION_START) && line.endsWith(SECTION_END)) {
        // remove brackets
        line = line.replace(SECTION_START, "");
        line = line.replace(SECTION_END, "");
        line = line.trim();

        // store all properties in section
        section = new Properties();
        getSections().put(line, section);
      }

      // parse as property
      else {
        int index = line.indexOf("=");
        if (index == -1) {
          throw new IOException("Expected " + PROPERTY_DELIMITER + " on line " + lineNumber + ": '" + line + "'");
        } else {
          String[] parts = line.split(PROPERTY_DELIMITER, 2);
          String key = parts[0].trim();
          String value = parts[1].trim();
          if (section != null) {
            section.setProperty(key, value);
          } else {
            setProperty(key, value);
          }
        }
      }

    }

    br.close();
  }

  /**
   * Write an Ini format to a PrintWriter.
   *
   * @param props  properties to write.
   * @param writer the writer that writes.
   * @param header an optioal header that will appear in comments at the start of
   *               the ini format.
   * @throws IOException if unable to write output.
   */
  @SuppressWarnings("unchecked")
  public static void write(final Properties props, final PrintWriter writer, String header) throws IOException {

    if (header != null) {
      // write the header
      writer.write(new StringBuffer(COMMENT_START).append(" ")
          .append(header.trim().replace("\n", "\n" + COMMENT_START + " ")).append("\n").toString());
    }

    // write properties
    Iterator<String> iter = (Iterator<String>) Collections.list(props.propertyNames()).iterator();
    while (iter.hasNext()) {
      String key = iter.next();
      writer.write(
          new StringBuffer(key).append(PROPERTY_DELIMITER).append(props.getProperty(key)).append("\n").toString());
    }

    // write sections
    if (props instanceof Ini) {
      Ini ini = (Ini) props;
      iter = ini.getSections().keySet().iterator();
      while (iter.hasNext()) {
        String sectionName = iter.next();
        writer.write(new StringBuffer(SECTION_START).append(sectionName).append(SECTION_END).append("\n").toString());
        write(ini.getSections().get(sectionName), writer, null);
      }
    }

    // flush, but don't close
    writer.flush();
  }

  /**
   * Calls write(new PrintWriter(out), header).
   */
  public void store(OutputStream out, String header) throws IOException {
    write(this, new PrintWriter(out), header);
  }

  /**
   * Write properties to an OutputStream.
   *
   * @param out the OutputStream used for writing.
   */
  public void save(final OutputStream out) {
    try {
      store(out, null);
    } catch (IOException e) {
      e.printStackTrace();
    }
  }

  /**
   * Write properties to a PrintStream.
   *
   * @param out the PrintStream used for writing.
   */
  public void list(PrintStream out) {
    try {
      store(out, null);
    } catch (IOException e) {
      e.printStackTrace();
    }
  }

  /**
   * Write properties to a PrintWriter.
   *
   * @param out the PrintWriter used for writing.
   */
  public void list(PrintWriter out) {
    try {
      write(this, out, null);
    } catch (IOException e) {
      e.printStackTrace();
    }
  }

}