public class IniEditor extends Object
IniEditor
preserves comments and
blank lines as well as the order of sections and lines in general.
IniEditor
assumes configuration files to be split in sections. A
section starts out with a header, which consists of the section name enclosed
in brackets ('['
and ']'
). Everything before the
first section header is ignored when loading from a stream or file. The
class can be used to load
configuration files without sections (ie Java-style properties).
IniEditor.Section
A "common section" may be named. All sections inherit the options of this section but can overwrite them.
IniEditor
represents an INI file (or rather, its sections) line
by line, as comment, blank and option lines. A comment is a line which has a
comment delimiter as its first non-white space character. The default comment
delimiters, which may be overwritten, are '#'
and
';'
.
A blank line is any line that consists only of white space.
Everything else is an option line. Option names and values are separated by
option delimiters '='
, ':'
or white space (spaces
and tabs).
Here's a minimal example. Suppose, we have this in a file called
users.ini
:
[root] role = administrator last_login = 2003-05-04 [joe] role = author last_login = 2003-05-13Let's load that file, add something to it and save the changes:
IniEditor users = new IniEditor(); users.load("users.ini"); users.set("root", "last_login", "2003-05-16"); users.addComment("root", "Must change password often"); users.set("root", "change_pwd", "10 days"); users.addBlankLine("root"); users.save("users.ini");Now, the file looks like this:
[root] role = administrator last_login = 2003-05-16 # Must change password often change_pwd = 10 days [joe] role = author last_login = 2003-05-13
IniEditor provides services simliar to the standard Java API class
java.util.Properties
. It uses its own parser, though, which
differs in these respects from that of Properties
:
load(InputStreamReader)
and
save(OutputStreamWriter)
methods with a reader and writer tuned to
the desired character encoding.'='
, ':'
and white space).Modifier and Type | Class and Description |
---|---|
static class |
IniEditor.NoSuchSectionException
Thrown when an non-existent section is addressed.
|
static class |
IniEditor.Section
Loads, edits and saves a section of an INI-style configuration file.
|
Constructor and Description |
---|
IniEditor()
Constructs new bare IniEditor instance.
|
IniEditor(boolean isCaseSensitive)
Constructs new bare IniEditor instance specifying case-sensitivity.
|
IniEditor(char[] delims)
Constructs new IniEditor defining comment delimiters.
|
IniEditor(char[] delims,
boolean isCaseSensitive)
Constructs new IniEditor defining comment delimiters.
|
IniEditor(String commonName)
Constructs new IniEditor instance with a common section.
|
IniEditor(String commonName,
boolean isCaseSensitive)
Constructs new IniEditor instance with a common section.
|
IniEditor(String commonName,
char[] delims)
Constructs new IniEditor instance with a common section, defining comment
delimiters.
|
IniEditor(String commonName,
char[] delims,
boolean isCaseSensitive)
Constructs new IniEditor instance with a common section, defining comment
delimiters.
|
Modifier and Type | Method and Description |
---|---|
void |
addBlankLine(String section)
Adds a blank line to the end of a section.
|
void |
addComment(String section,
String comment)
Adds a comment line to the end of a section.
|
boolean |
addSection(String name)
Adds a section if it doesn't exist yet.
|
String |
get(String section,
String option)
Returns the value of a given option in a given section or null if either
the section or the option don't exist.
|
Map<String,String> |
getSectionMap(String section)
Returns a map of a given section with option/value pairs or null if the
section doesn't exist.
|
boolean |
hasOption(String section,
String option)
Checks whether an option exists in a given section.
|
boolean |
hasSection(String name)
Checks whether a section with a particular name exists in this instance.
|
void |
load(File file)
Loads INI formatted input from a file into this instance, using the
default character encoding.
|
void |
load(InputStream stream)
Loads INI formatted input from a stream into this instance, using the
default character encoding.
|
void |
load(InputStreamReader streamReader)
Loads INI formatted input from a stream reader into this instance.
|
void |
load(String filename)
Loads INI formatted input from a file into this instance, using the
default character encoding.
|
List<String> |
optionNames(String section)
Returns all option names of a section, not including options from the
common section.
|
boolean |
remove(String section,
String option)
Removes an option from a section if it exists.
|
boolean |
removeSection(String name)
Removes a section if it exists.
|
void |
save(File file)
Writes this instance in INI format to a file.
|
void |
save(OutputStream stream)
Writes this instance in INI format to an output stream.
|
void |
save(OutputStreamWriter streamWriter)
Writes this instance in INI format to an output stream writer.
|
void |
save(String filename)
Writes this instance in INI format to a file.
|
List<String> |
sectionNames()
Returns all section names in this instance minus the common section if
one was defined.
|
void |
set(String section,
String option,
String value)
Sets the value of an option in a section, if the option exist, otherwise
adds the option to the section.
|
void |
setOptionFormatString(String formatString)
Sets the option format for this instance to the given string.
|
public IniEditor()
public IniEditor(boolean isCaseSensitive)
isCaseSensitive
- section and option names are case-sensitive if this is truepublic IniEditor(String commonName)
commonName
- name of the common sectionpublic IniEditor(String commonName, boolean isCaseSensitive)
commonName
- name of the common sectionisCaseSensitive
- section and option names are case-sensitive if this is truepublic IniEditor(char[] delims)
delims
- an array of characters to be recognized as starters of comment
lines; the first of them will be used for newly created
commentspublic IniEditor(char[] delims, boolean isCaseSensitive)
delims
- an array of characters to be recognized as starters of comment
lines; the first of them will be used for newly created
commentsisCaseSensitive
- section and option names are case-sensitive if this is truepublic IniEditor(String commonName, char[] delims)
commonName
- name of the common sectiondelims
- an array of characters to be recognized as starters of comment
lines; the first of them will be used for newly created
commentspublic IniEditor(String commonName, char[] delims, boolean isCaseSensitive)
commonName
- name of the common sectiondelims
- an array of characters to be recognized as starters of comment
lines; the first of them will be used for newly created
commentspublic void setOptionFormatString(String formatString)
%s
three times, these will be replaced
with the option name, the option separator and the option value in this
order. Literal percentage signs must be escaped by preceding them with
another percentage sign (i.e., %%
corresponds to one
percentage sign). The default format string is "%s %s %s"
.
Option formats may look like format strings as supported by Java 1.5, but
the string is in fact parsed in a custom fashion to guarantee backwards
compatibility. So don't try clever stuff like using format conversion
types other than %s
.formatString
- a format string, containing %s
exactly three
timesIllegalArgumentException
- if the format string is illegalpublic String get(String section, String option)
section
- the section's nameoption
- the option's nameNullPointerException
- any of the arguments is null
public Map<String,String> getSectionMap(String section)
section
- the section's nameNullPointerException
- if section is null
public void set(String section, String option, String value)
section
- the section's nameoption
- the option's namevalue
- the option's valueIniEditor.NoSuchSectionException
- no section with the given name existsIllegalArgumentException
- the option name is illegal, ie contains a '=' character or
consists only of white spaceNullPointerException
- section or option are null
public boolean remove(String section, String option)
section
- the section's nameoption
- the option's nametrue
if the option was actually removedIniEditor.NoSuchSectionException
- no section with the given name existspublic boolean hasOption(String section, String option)
section
- the section's nameoption
- the option's namepublic boolean hasSection(String name)
name
- the name of the sectionpublic boolean addSection(String name)
name
- the name of the sectiontrue
if the section didn't already existIllegalArgumentException
- the name is illegal, ie contains one of the characters '['
and ']' or consists only of white spacepublic boolean removeSection(String name)
name
- the section's nametrue
if the section actually existedIllegalArgumentException
- when trying to remove the common sectionpublic List<String> sectionNames()
public List<String> optionNames(String section)
section
- the section's nameIniEditor.NoSuchSectionException
- no section with the given name existspublic void addComment(String section, String comment)
section
- the section's namecomment
- the commentIniEditor.NoSuchSectionException
- no section with the given name existspublic void addBlankLine(String section)
section
- the section's nameIniEditor.NoSuchSectionException
- no section with the given name existspublic void save(String filename) throws IOException
filename
- the file to write toIOException
- at an I/O problempublic void save(File file) throws IOException
file
- where to save toIOException
- at an I/O problempublic void save(OutputStream stream) throws IOException
OutputStream
for maximum flexibility, internally it does
of course use a writer for character based output.stream
- where to writeIOException
- at an I/O problempublic void save(OutputStreamWriter streamWriter) throws IOException
streamWriter
- where to writeIOException
- at an I/O problempublic void load(String filename) throws IOException
filename
- file to read fromIOException
- at an I/O problempublic void load(File file) throws IOException
file
- file to read fromIOException
- at an I/O problempublic void load(InputStream stream) throws IOException
InputStream
for maximum flexibility, internally it does use a reader (using the
default character encoding) for character based input. Everything in the
stream before the first section header is ignored.stream
- where to read fromIOException
- at an I/O problempublic void load(InputStreamReader streamReader) throws IOException
streamReader
- where to read fromIOException
- at an I/O problemCopyright © 2021. All Rights Reserved.