public class Ini
extends java.lang.Object
Ini
class represents an INI content: a text-file composed of comments and a basic structure of sections and keys,
plus many extra features.
The implemented INI specification version:
(this specification is partially based on the Wikipedia "INI file" documentation; see
http://en.wikipedia.org/wiki/INI_file)
key = the value
[section]
; comment text
# other comment text
fr.tikione.ini.Config
class.
${@env/PATH}
will refer to the "PATH" system environment value
(System.getenv(String)
function).${@prop/os.name}
will refer to the "os.name" JVM property
(System.getProperty(String)
function), so - in this example, the operating system name.${foo/bar}
will refer to the "bar" key value in the "foo" section of the current INI
file.${bar}
will refer to the "bar" key value in the global section of the current INI
file.InfinitiveLoopException
exception.key = the os is ${@prop/os.name} and the ${dirs/tmp} folder is ${@env/TMP}
Finally, note that an INI parser's configuration can be customized via the fr.tikione.ini.Config
class. Every
Ini
class contains a Config
object that you can edit via the getConfig()
method.
Modifier and Type | Class and Description |
---|---|
static class |
Ini.Entry
An entry to store an information from an INI content.
|
Constructor and Description |
---|
Ini()
Create a new instance of
Ini . |
Ini(Ini ini)
Create a new instance of
Ini by copy. |
Ini(java.util.Properties tikioneProperties)
Create a new instance of
Ini . |
Modifier and Type | Method and Description |
---|---|
void |
addAll(Ini from)
Copy all of the sections and keys from the specified
Ini to the current Ini . |
void |
checkContent()
Try to get all keys values of all sections, in order to throw an exception if a critical error is detected.
|
void |
checkContent(Config config)
Try to get all keys values of all sections, in order to throw an exception if a critical error is detected.
|
Config |
getConfig()
Get the configuration
Config object. |
java.util.List<java.lang.String> |
getKeysNames(java.lang.String section)
Get a list of all key names in a section.
|
protected java.lang.String |
getKeyValue(int loop,
java.lang.String defval,
java.lang.String section,
java.lang.String key,
Config config,
boolean raw)
Get key value from the INI content.
|
java.lang.String |
getKeyValue(java.lang.String section,
java.lang.String key)
Get key value from the INI content.
|
java.lang.String |
getKeyValue(java.lang.String section,
java.lang.String key,
Config config)
Get key value from the INI content.
|
java.lang.String |
getKeyValue(java.lang.String defVal,
java.lang.String section,
java.lang.String key)
Get key value from the INI content.
|
java.lang.String |
getKeyValue(java.lang.String defVal,
java.lang.String section,
java.lang.String key,
Config config)
Get key value from the INI content.
|
java.lang.String |
getNewLineStr()
Return the new line characters combination CR (Carriage Return), LF (Line Feed) or CRLF according to the INI content that
has been read.
|
protected java.lang.String |
getRawKeyValue(java.lang.String defval,
java.lang.String section,
java.lang.String key)
Get key value from the INI content with a configuration that disable shortcuts (section/key shortcuts, environment variables
shortcuts, system properties shortcuts) and other configurable functionalities.
|
protected java.util.Map<java.lang.String,Ini.Entry> |
getSectionContentClone(java.lang.String section)
Make a copy of a section content.
|
java.util.List<java.lang.String> |
getSectionsNames()
Get a list of all section names, the global section included.
|
java.util.Map<java.lang.String,java.lang.String> |
getSectionValues(java.lang.String section)
Get a
Map of all keys and values of a section. |
java.util.Map<java.lang.String,java.lang.String> |
getSectionValues(java.lang.String section,
Config config)
Get a
Map of all keys and values of a section. |
boolean |
hasKey(java.lang.String section,
java.lang.String key)
Indicate if a key exists in the INI content and specified section.
|
boolean |
hasSection(java.lang.String section)
Indicate if a section exists in the INI content.
|
void |
load(AbstractLineReader reader)
Load and parse reader content.
|
void |
load(java.io.File file)
Load and parse file content with platform's default file encoding.
|
void |
load(java.io.File file,
java.lang.String encoding)
Load and parse file content.
|
void |
load(java.io.InputStream inputstream)
Load and parse input stream content with platform's default file encoding.
|
void |
load(java.io.InputStream inputstream,
java.lang.String encoding)
Load and parse input stream content.
|
boolean |
removeKey(java.lang.String section,
java.lang.String key)
Remove a key.
|
boolean |
removeSection(java.lang.String section,
boolean removeSecDecl)
Remove all section's content and, optionally, the section declaration itself.
|
boolean |
renameKey(java.lang.String section,
java.lang.String oldKey,
java.lang.String newKey)
Rename a key if exists.
|
boolean |
renameSection(java.lang.String oldSection,
java.lang.String newSection)
Rename a section if exists.
|
void |
setConfig(Config config)
Set the configuration
Config object. |
void |
setKeyValue(java.lang.String section,
java.lang.String key,
java.lang.String value)
Write a value into the
Ini content. |
void |
sort()
Sort the content by section and key name.
|
void |
sort(java.util.Comparator<java.lang.Object> comparator)
Sort the content by section and key name.
|
void |
sort(java.util.Comparator<java.lang.Object> sectionComparator,
java.util.Comparator<java.lang.Object> keyComparator)
Sort the content by section and key name.
|
void |
store(java.io.File file)
Store the INI content with platform's default file encoding and new line character(s).
|
void |
store(java.io.File file,
java.lang.String encoding,
java.lang.String newLine)
Store the INI content.
|
void |
store(java.io.OutputStream outputStream)
Store the INI content with platform's default file encoding and new line character(s).
|
void |
store(java.io.OutputStream outputStream,
java.lang.String encoding,
java.lang.String newLine)
Store the INI content.
|
public Ini() throws java.io.IOException, java.util.regex.PatternSyntaxException
Ini
. Create a new instance of parser and load the internal
/fr.tikione.ini.properties
file for configuration.java.io.IOException
- if an I/O error occurs while retrieving the internal properties file.java.util.regex.PatternSyntaxException
- if a regular expression (stored in the configuration properties) cannot compile.public Ini(Ini ini)
Ini
by copy.ini
- the Ini
object to copy.public Ini(java.util.Properties tikioneProperties) throws java.util.regex.PatternSyntaxException
Ini
. Create a new instance of parser and load the given properties object for configuration.tikioneProperties
- the configuration properties object to fill the internal /fr.tikione.ini.properties
file.java.util.regex.PatternSyntaxException
- if a regular expression (stored in the configuration properties) cannot compile.public void addAll(Ini from)
Ini
to the current Ini
. Comments are omitted and
existing keys are overwritten.from
- Ini
to be copied.public void checkContent() throws java.io.CharConversionException, InfinitiveLoopException
java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public void checkContent(Config config) throws java.io.CharConversionException, InfinitiveLoopException
config
- the configuration to use during this test.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public Config getConfig()
Config
object.Config
object.protected java.lang.String getRawKeyValue(java.lang.String defval, java.lang.String section, java.lang.String key)
defval
- the default valuesection
- the section to find the key.key
- the key name.defVal
string otherwise.protected java.lang.String getKeyValue(int loop, java.lang.String defval, java.lang.String section, java.lang.String key, Config config, boolean raw) throws java.io.CharConversionException, InfinitiveLoopException
loop
- the position in the shortcuts pursuit counter.defval
- the default value.section
- the section to find the key.key
- the key name.config
- the configuration to (de)activate functionalities.raw
- if true
, shortcuts functionalities (environment variables, system properties, section/key references) are
deactivated, otherwise they depend on the given configuration.defVal
string otherwise.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.lang.String getKeyValue(java.lang.String section, java.lang.String key) throws java.io.CharConversionException, InfinitiveLoopException
section
- the section to find the key.key
- the key name.defVal
string otherwise.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.lang.String getKeyValue(java.lang.String defVal, java.lang.String section, java.lang.String key) throws java.io.CharConversionException, InfinitiveLoopException
defVal
- the default key value. Useful if no value found.section
- the section to find the key.key
- the key name.defVal
string otherwise.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.lang.String getKeyValue(java.lang.String defVal, java.lang.String section, java.lang.String key, Config config) throws java.io.CharConversionException, InfinitiveLoopException
defVal
- the default key value. Useful if no value found.section
- the section to find the key.key
- the key name.config
- the configuration to (de)activate functionalities.defVal
string otherwise.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.lang.String getKeyValue(java.lang.String section, java.lang.String key, Config config) throws java.io.CharConversionException, InfinitiveLoopException
section
- the section to find the key.key
- the key name.config
- the configuration to (de)activate functionalities.defVal
string otherwise.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.util.List<java.lang.String> getKeysNames(java.lang.String section)
List
is an ArrayList
, so the INI keys order is
preserved.section
- the section to get keys.List
into which the keys have been put.public java.lang.String getNewLineStr()
protected java.util.Map<java.lang.String,Ini.Entry> getSectionContentClone(java.lang.String section)
section
- the section to clone content.public java.util.Map<java.lang.String,java.lang.String> getSectionValues(java.lang.String section) throws java.io.CharConversionException, InfinitiveLoopException
Map
of all keys and values of a section. The result Map
is a LinkedHashMap
, so the
INI sections and keys order is preserved.section
- the section to get keys and values.Map
into which the keys and values have been put.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.util.Map<java.lang.String,java.lang.String> getSectionValues(java.lang.String section, Config config) throws java.io.CharConversionException, InfinitiveLoopException
Map
of all keys and values of a section. The result Map
is a LinkedHashMap
, so the
INI sections and keys order is preserved.section
- the section to get keys and values.config
- the configuration to (de)activate functionalities.Map
into which the keys and values have been put.java.io.CharConversionException
- if an invalid Unicode escape is detected.InfinitiveLoopException
- if a pair of shortcuts calls them one another, that could initiate an infinitive loop.public java.util.List<java.lang.String> getSectionsNames()
List
is an ArrayList
, so the
INI sections order is preserved.List
into which the sections names have been put.public boolean hasKey(java.lang.String section, java.lang.String key)
section
- the section to find the key.key
- the key to test existence.true
if the key exists, false
otherwise.public boolean hasSection(java.lang.String section)
section
- the section to test existence.true
if the section exists, false
otherwise.public void load(java.io.File file) throws java.io.IOException
file
- the file to read content.java.io.IOException
- if an I/O error occurs.public void load(java.io.File file, java.lang.String encoding) throws java.io.IOException
file
- the file to read content.encoding
- file encoding.java.io.IOException
- if an I/O error occurs.public void load(java.io.InputStream inputstream) throws java.io.IOException
inputstream
- the input stream to read content.java.io.IOException
- if an I/O error occurs.public void load(java.io.InputStream inputstream, java.lang.String encoding) throws java.io.IOException
inputstream
- the input stream to read content.encoding
- file encoding.java.io.IOException
- if an I/O error occurs.public void load(AbstractLineReader reader) throws java.io.IOException
reader
- the reader to work with.java.io.IOException
- if an I/O error occurs.public boolean removeKey(java.lang.String section, java.lang.String key)
section
- the key section to find the key.key
- the section key.true
if the key existed and has been removed, false
if the key didn't exist.public boolean removeSection(java.lang.String section, boolean removeSecDecl)
section
- the section name.removeSecDecl
- if true
, the section declaration is removed too, otherwise it is not removed.true
if the section existed and has been removed, false
if the section didn't exist.public boolean renameKey(java.lang.String section, java.lang.String oldKey, java.lang.String newKey)
section
- the section to find the key.oldKey
- the key name to renamenewKey
- the new key name.true
if the key existed and has been renamed, false
if the key didn't exist.public boolean renameSection(java.lang.String oldSection, java.lang.String newSection)
oldSection
- the section name to rename.newSection
- the new section name.true
if the section existed and has been renamed, false
if the section didn't exist.public void setConfig(Config config)
Config
object.config
- the new configuration Config
object (a protective copy of the given Config
object is made
first).public void setKeyValue(java.lang.String section, java.lang.String key, java.lang.String value) throws java.lang.IllegalArgumentException
Ini
content.section
- the section to find the key.key
- the key name.value
- the key value.java.lang.IllegalArgumentException
- if an argument value is forbidden (New Line and Carriage Return).public void sort()
String
comparison.public void sort(java.util.Comparator<java.lang.Object> comparator)
comparator
- the comparator to determine the order of the sections and keys.public void sort(java.util.Comparator<java.lang.Object> sectionComparator, java.util.Comparator<java.lang.Object> keyComparator)
sectionComparator
- the comparator to determine the order of the sections.keyComparator
- the comparator to determine the order of the keys.public void store(java.io.File file) throws java.io.IOException
file
- the destination file to write content.java.io.IOException
- if an I/O error occurs.public void store(java.io.File file, java.lang.String encoding, java.lang.String newLine) throws java.io.IOException
file
- the destination file to write content.encoding
- the file encoding.newLine
- the new line character(s).java.io.IOException
- if an I/O error occurs.public void store(java.io.OutputStream outputStream) throws java.io.IOException
outputStream
- the destination output stream to write content.java.io.IOException
- if an I/O error occurs.public void store(java.io.OutputStream outputStream, java.lang.String encoding, java.lang.String newLine) throws java.io.IOException
outputStream
- the destination output stream to write content.encoding
- the file encoding.newLine
- the new line character(s).java.io.IOException
- if an I/O error occurs.