Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.crosswire.common.util
Class Ini

    java.lang.Object
      org.crosswire.common.util.Ini

    final class Ini

extends Object

A utility class for loading an INI style, Multimap configuration file.

SWORD defines a conf as an INI file with one or more sections. Originally, all modules were described in a single conf, but now each module has its own conf.

SWORD will be using a single conf to hold overrides for many modules. This is the motivation for this class as opposed to allowing only a single section as `IniSection`.

Since the most common use case is for a single section, this implementation has an API for delegating to the first IniSection.

This implementation allows for:

- Case Insensitive -- Section names, keys and values are case insensitive.
- Comments -- ; and # preceded only by white space indicate that a line is a comment. Note: SWORD does not support ; but it is present in some 3rd Party repositories such as IBT.
- Multiple Values -- Each key can have one or more values.
- Order -- Order of sections, keys and values are retained

This implementation does not allow for:

- Globals -- (key,value) pairs before the first section.
- Quoted Values -- Values surrounded by "" or ''. If present they are part of the value.
- Retaining comments -- Comments are ignored.
- Comments after content -- Comments are on lines to themselves.
- : -- as an alternative for =.
- nulls -- null values.

Author:
  DM Smith
See Also:
  `The GNU Lesser General Public License for details.
  The copyright to this program is held by its authors.`

Field Summary
`private List<String>` | `list` Indexed list of sections maintaining insertion order.
`private static org.slf4j.Logger` | `LOGGER` The log stream
`private static int` | `MAX_BUFF_SIZE` Buffer size is based on file size but keep it with within reasonable limits
`private Map<String,IniSection>` | `sectionMap` A map of sections by section names.

Constructor Summary
`Ini()` Create an empty INI Config.

Method Summary
`boolean` | `add(String sectionName, String key, String value)` Add a key/value pair to a section.
`boolean` | `addValue(String key, String value)` Add a value for the key.
`private String` | `advance(BufferedReader bin)` Get the next line from the input
`void` | `clear()` Start over.
`List<String>` | `getKeys()` Get the unmodifiable set of keys of the first section.
`private IniSection` | `getOrCreateSection(String sectionName)` Get a section, creating it if necessary.
`IniSection` | `getSection()` Get the first section.
`private IniSection` | `getSection(String sectionName)`
`String` | `getSectionName()` Get the name of the first section.
`String` | `getSectionName(int index)`
`List<String>` | `getSections()` Get an unmodifiable collection of the sections in this INI.
`private int` | `getSplitPos(String line)` Does this line of text represent a key/value pair?
`String` | `getValue(String key)` Get the first value for the key in the first section.
`String` | `getValue(String key, int index)` Get the value for the key specified by the index for the first section.
`String` | `getValue(String sectionName, String key)` Get the first value for the key specified by the index and the section.
`String` | `getValue(String sectionName, String key, int index)` Get the value for the key specified by the index and the section.
`Collection<String>` | `getValues(String key)` Get the values of a key of the first section.
`int` | `getValueSize(String key)` Get the number of values for a key in the first section
`int` | `getValueSize(String sectionName, String key)`
`private boolean` | `isCommentLine(String line)` Determine if the given line is a blank or a comment line.
`private boolean` | `isSectionLine(String line)` Is this line a [section]?
`void` | `load(byte[] buffer, String encoding)` Load the conf from a buffer.
`void` | `load(File file, String encoding)` Load the INI from a file using the given encoding.
`void` | `load(InputStream is, String encoding)`
`private void` | `load(Reader in)`
`private String` | `more(BufferedReader bin, String value)` Get continuation lines, if any.
`private static boolean` | `more(String line)` Is there more following this line
`boolean` | `remove(String sectionName, String key)` Remove the key if present.
`boolean` | `remove(String sectionName, String key, String value)` Remove the value if present.
`boolean` | `removeValue(String key)` Remove the key if present.
`boolean` | `removeValue(String key, String value)` Remove the value if present in the first section.
`boolean` | `replace(String sectionName, String key, String value)` Replace a value for a key.
`boolean` | `replaceValue(String key, String value)` Replace a value for a key.
`void` | `save(File file, String encoding)` Save the INI to a file using the given encoding.
`private void` | `save(Writer out)` Output the Ini to the given Writer.
`int` | `size()` Get the number of sections

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### sectionMap

    private Map<String,IniSection> sectionMap

  A map of sections by section names.

### list

    private List<String> list

  Indexed list of sections maintaining insertion order.

### MAX_BUFF_SIZE

    private static final int MAX_BUFF_SIZE

  Buffer size is based on file size but keep it with within reasonable limits

  See Also:
    Constant Field Values

### LOGGER

    private static final org.slf4j.Logger LOGGER

  The log stream

Constructor Detail

### Ini

    public Ini()

  Create an empty INI Config.

Method Detail

### clear

    public void clear()

  Start over.

### size

    public int size()

  Get the number of sections

  Returns:
    the number of known sections

### getSections

    public List<String> getSections()

  Get an unmodifiable collection of the sections in this INI.

  Returns:
    the ordered section names

### getSectionName

    public String getSectionName(int index)

### getValueSize

    public int getValueSize(String sectionName,
                            String key)

### getValue

    public String getValue(String sectionName,
                           String key,
                           int index)

  Get the value for the key specified by the index and the section.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
    `index` - the index in the list of values
  Returns:
    the value at the specified index
  Throws:
    `ArrayIndexOutOfBoundsException` - when the index is out of bounds

### getValue

    public String getValue(String sectionName,
                           String key)

  Get the first value for the key specified by the index and the section.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
  Returns:
    the value at the specified index
  Throws:
    `ArrayIndexOutOfBoundsException` - when the index is out of bounds

### add

    public boolean add(String sectionName,
                       String key,
                       String value)

  Add a key/value pair to a section. If the section does not exist, it is created. A null for key or value is not allowed. An empty string for a key is not allowed.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    `true` if the element was added or already was present

### replace

    public boolean replace(String sectionName,
                           String key,
                           String value)

  Replace a value for a key. A null for key or value is not allowed. An empty string for a key is not allowed.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    `true` if the element was added or already was present

### remove

    public boolean remove(String sectionName,
                          String key,
                          String value)

  Remove the value if present. If it were the last value for the key, the key is removed. If it were the last key, the section is removed.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    whether the value was present and removed

### remove

    public boolean remove(String sectionName,
                          String key)

  Remove the key if present. If it were the last key for the section, the section is removed.

  Parameters:
    `sectionName` - the name of the section
    `key` - the key for the section
  Returns:
    whether the key was present and removed

### getSectionName

    public String getSectionName()

  Get the name of the first section.

  Returns:
    the name of the first section or null if there are no sections
  Throws:
    `ArrayIndexOutOfBoundsException` - if there are no sections

### getSection

    public IniSection getSection()

  Get the first section.

  Returns:
    the first section or null if there are no sections

### getKeys

    public List<String> getKeys()

  Get the unmodifiable set of keys of the first section. The set has insertion order.

  Returns:
    the keys of the first section

### getValues

    public Collection<String> getValues(String key)

  Get the values of a key of the first section. The collection has insertion order. Note many keys only have one value. A key that has no values returns null.

  Parameters:
    `key` - the key
  Returns:
    the keyed values or null if the key doesn't exist

### getValueSize

    public int getValueSize(String key)

  Get the number of values for a key in the first section

  Parameters:
    `key` - the key
  Returns:
    the number of values for a key in the first section

### getValue

    public String getValue(String key,
                           int index)

  Get the value for the key specified by the index for the first section.

  Parameters:
    `key` - the key
    `index` - the index
  Returns:
    the value at the specified index
  Throws:
    `ArrayIndexOutOfBoundsException` - when the index is out of bounds

### getValue

    public String getValue(String key)

  Get the first value for the key in the first section.

  Parameters:
    `key` - the key
  Returns:
    the value at the specified index
  Throws:
    `ArrayIndexOutOfBoundsException` - when the index is out of bounds

### addValue

    public boolean addValue(String key,
                            String value)

  Add a value for the key. Duplicate values are not allowed.

  Parameters:
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    whether the value was added or is already present.

### removeValue

    public boolean removeValue(String key,
                               String value)

  Remove the value if present in the first section. If it were the last value for the key, the key is removed. If it were the last key, the section is removed.

  Parameters:
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    whether the value was present and removed

### removeValue

    public boolean removeValue(String key)

  Remove the key if present. If it were the last key for the section, the section is removed.

  Parameters:
    `key` - the key for the section
  Returns:
    whether the key was present and removed

### replaceValue

    public boolean replaceValue(String key,
                                String value)

  Replace a value for a key. A null for key or value is not allowed. An empty string for a key is not allowed.

  Parameters:
    `key` - the key for the section
    `value` - the value for the key
  Returns:
    `true` if the element was added or already was present

### load

    public void load(InputStream is,
                     String encoding)
              throws IOException

  Throws:
    `IOException`

### load

    public void load(File file,
                     String encoding)
              throws IOException

  Load the INI from a file using the given encoding.

  Parameters:
    `file` - the file to load
    `encoding` - the encoding of the file
  Throws:
    `IOException`

### load

    public void load(byte[] buffer,
                     String encoding)
              throws IOException

  Load the conf from a buffer. This is used to load conf entries from the mods.d.tar.gz file.

  Parameters:
    `buffer` - the buffer to load
    `encoding` - the character encoding for this INI
  Throws:
    `IOException`

### save

    public void save(File file,
                     String encoding)
              throws IOException

  Save the INI to a file using the given encoding.

  Parameters:
    `file` - the file to load
    `encoding` - the encoding of the file
  Throws:
    `IOException`

### save

    private void save(Writer out)

  Output the Ini to the given Writer.

  Parameters:
    `out` - the Writer to which this Ini should be written

### getSection

    private IniSection getSection(String sectionName)

### getOrCreateSection

    private IniSection getOrCreateSection(String sectionName)

  Get a section, creating it if necessary.

  Parameters:
    `sectionName` -
  Returns:
    the found or created section

### load

    private void load(Reader in)
               throws IOException

  Throws:
    `IOException`

### advance

    private String advance(BufferedReader bin)
                    throws IOException

  Get the next line from the input

  Parameters:
    `bin` - The reader to get data from
  Returns:
    the next line or null if there is nothing more
  Throws:
    `IOException` - if encountered

### isCommentLine

    private boolean isCommentLine(String line)

  Determine if the given line is a blank or a comment line.

  Parameters:
    `line` - The line to check.
  Returns:
    true if the line is empty or starts with one of the comment characters

### isSectionLine

    private boolean isSectionLine(String line)

  Is this line a [section]?

  Parameters:
    `line` - The line to check.
  Returns:
    true if the line designates a section

### getSplitPos

    private int getSplitPos(String line)

  Does this line of text represent a key/value pair?

  Parameters:
    `line` - The line to check.
  Returns:
    the position of the split position or -1

### more

    private String more(BufferedReader bin,
                        String value)
                 throws IOException

  Get continuation lines, if any.

  Throws:
    `IOException`

### more

    private static boolean more(String line)

  Is there more following this line

  Parameters:
    `line` - the trimmed string to check
  Returns:
    whether this line continues

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Copyright ¨ 2003-2015
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD