This page contains an explanation of the advanced topics of the Java INI Package, along with code examples and explanations. Although this document aims to be as concise as possible, developers are recommended to consult the javadoc for a more complete and upto date documentation of Java INI Package.

Contents

7. Comments
7.1. Comments in INI Files
7.2. Comments in the Java INI Package
7.3. Creating INI comments in Java

7. Comments

7.1. Comments in INI Files

As well as sections and items, INI files can contain comments too. Comments are often used to provide information to users, such as the definition or purpose of items, or explanations of the possible values that are permitted for a given item. However, software which read INI files will simply ignore the comments as the comments have no purpose to them.

In an INI file, a comment is marked with a semi-colon (;). All text that follows the semi-colon on that line is considered a comment. Unlike Java or C++, there is no way to comment multiple lines, therefore, if you want to comment multiple lines, you will need to place a semi-colon at the begining of every line. To explain all this, have a look at the INI file below.

; This file contains settings for displaying the application's main
; window. In particular it stores the properties of the window when
; it was last used, so that the window size and position is kept
; when the application is reloaded
[settings]
width = 600 ; the width of the window
height = 480 ; the height of the window
x = 37 ; the position of the top-left corner of the window
y = 21 ; the position of the top-left corner of the window

As you can see, there is a block comment before the section "settings", as well as a comment after every item. Without the comments, the INI file would look like this:

[settings]
width = 600
height = 480
x = 37
y = 21

which does not tell the user what the file does or what the items mean.

Back to Top

7.2. Comments in the Java INI Package

The Java INI Package recognises comments in INI files and stores three different types of comment:

End line comment
A end line comment occurs on the same line as a section or an item. End line comments cannot contain a new line character ("\n").
Pre-comment
A pre-comment occurs on the line or lines before a section or an item. Unlike end line comments, a pre-comment can contain new line characters ("\n"), therefore, in the above example, the comments before the section "settings" is not 4 seperate pre-comments, but one long continuous pre-comment.
Post-comment
A post-comment is very similar to a pre-comment but differs in that it occurs after a section or an item. A pre-comment can also cantain new line characters ("\n") and therefore be spread accross many lines.

Back to Top

7.3. Creating INI comments in Java

To best demonstrate how to create INI comments in Java, the code below attempt to produce the the INI file from Section 7.1.

import org.dtools.ini.*;
import java.io.*;

public class CreateIniFileWithComments {

public static void main( String args[] ) {

//**********************************************************************
// Step 1 - Create an IniFile
//**********************************************************************
IniFile ini = new BasicIniFile();

//**********************************************************************
// Step 2 - Create the section "settings" and set comments for it
//**********************************************************************
IniSection settings = ini.addSection( "settings" );

settings.setPreComment(
"This file contains settings for displaying the application's main\n" +
"window. In particular it stores the properties of the window when\n" +
"it was last used, so that the window size and position is kept\n" +
"when the application is reloaded" );

//**********************************************************************
// Step 3 - Add items and their comments to the section "settings"
//**********************************************************************

// create width item
IniItem widthItem = settings.addItem( "width" );
widthItem.setValue( 600 );
widthItem.setEndLineComment( "the width of the window" );

// create height item
IniItem heightItem = settings.addItem( "height" );
heightItem.setValue( 480 );
heightItem.setEndLineComment( "the height of the window" );

// create x item
IniItem xItem = settings.addItem( "x" );
xItem.setValue( 37 );
xItem.setEndLineComment(
"the position of the top-left corner of the window" );

// create y item
IniItem yItem = settings.addItem( "y" );
yItem.setValue( 21 );
yItem.setEndLineComment(
"the position of the top-left corner of the window" );

//**********************************************************************
// Step 4 - Save file to hard disk
//**********************************************************************
File iniFile = new File( "settings.ini" );
IniFileWriter writer = new IniFileWriter( ini, iniFile );
writer.write();
}
}

TODO: write documentation for "7. Comments"

Back to Top