net.nand.util.i18n
Class PropsFileWriter

java.lang.Object
  net.nand.util.i18n.PropsFileWriter

public class PropsFileWriter
extends java.lang.Object

Write a properties file out to disk, in the same format used by the jsettlers project: Valid ISO-8859-1 high-bit characters will be in the file as such, and not as \uXXXX code escapes, unlike Java's built-in Properties.store(java.io.OutputStream, String) method.

Usage:

• writer = new PropsFileWriter(File) or PropsFileWriter(PrintWriter);
• writer..write(pairs, filecomment);
• // Or:
  writeOne(writer, key, value, paircomment, spacedEquals);
  writeOne(...); ...
• writer.close();

Author:

Jeremy D Monin <jeremy@nand.net>

See Also:

PropsFileParser

Field Summary

private java.io.PrintWriter

pw An open PrintWriter for the output file; must have encoding ISO-8859-1

Constructor Summary

PropsFileWriter(java.io.File pFile)
Create and open a new PropsFileWriter to this file.

PropsFileWriter(java.io.PrintWriter pw)
Create a new PropsFileWriter using this open PrintWriter, which must use the "ISO-8859-1" file encoding.

Method Summary

static void	appendEsc(java.lang.StringBuilder sb, char c) Escape and append 1 special character to a StringBuilder.
void	close()
static java.lang.String	escValue(java.lang.String val) Examine a property value string, and escape any non-ISO-8859-1 unicode characters and leading whitespace.
void	flush()
static boolean	isValidHighISO8859_1(char c) For java properties file encoding, is "high-bit" character c valid in both ISO-8859-1 and ISO-8859-15? If not, it should be escaped (\uXXXX) in the output file.
void	write(java.util.List<PropsFileParser.KeyPairLine> pairs, java.lang.String fileComment) Write these key-value pairs through the open writer.
static void	writeOne(java.io.PrintWriter pw, java.lang.String key, java.lang.String val, java.util.List<java.lang.String> comments, boolean spacedEquals) Write one key-value pair line to the properties file, making sure unicode escapes are re-escaped to \uXXXX where needed, otherwise keeping val unchanged and keeping high-bit ISO-8859-1 characters for easier viewing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

pw

private java.io.PrintWriter pw

An open PrintWriter for the output file; must have encoding ISO-8859-1

Constructor Detail

PropsFileWriter

public PropsFileWriter(java.io.PrintWriter pw)

Create a new PropsFileWriter using this open PrintWriter, which must use the "ISO-8859-1" file encoding.

PropsFileWriter

public PropsFileWriter(java.io.File pFile)
                throws java.io.FileNotFoundException,
                       java.lang.SecurityException,
                       java.io.UnsupportedEncodingException

Create and open a new PropsFileWriter to this file.

Parameters:

pFile - Properties file to write

Throws:

java.io.FileNotFoundException - if the file can't be created, opened, or written, or is a unix special file

java.lang.SecurityException - if write access is denied

java.io.UnsupportedEncodingException - if the "ISO-8859-1" file encoding is somehow not supported; this is the encoding used by Java properties files, so it should be available; this error is not expected to occur.

Method Detail

isValidHighISO8859_1

public static final boolean isValidHighISO8859_1(char c)

For java properties file encoding, is "high-bit" character c valid in both ISO-8859-1 and ISO-8859-15? If not, it should be escaped (\uXXXX) in the output file.

If a character returns true here, its unicode char can be output as its ISO-8859-1 byte: "ISO-8859-1 was incorporated as the first 256 code points ... of Unicode" -- Wikipedia ISO-8859-1 article

This function tests only "high-bit" characters (0x80 and above): Any character below 00A0 returns false, including ascii characters which are valid in ISO-8859-1. Just use an if-statement to test the range 0x20 to 0x7E (' ' to '~') instead.

In case of editing on a computer using the newer ISO-8859-15, the few ISO-8859-1 characters dropped from that encoding return false.

Parameters:

c - A non-ascii "high-bit" character, with unicode code point 0080 or higher

See Also:

Wikipedia: ISO/IEC 8859-1, Wikipedia: ISO/IEC 8859-15

appendEsc

public static final void appendEsc(java.lang.StringBuilder sb,
                                   char c)

Escape and append 1 special character to a StringBuilder.

Parameters:

sb - StringBuilder to append c onto

c - A character to escape; \t \r \n and ' ' are appended as their 2-character text escapes, all others will be appended as \uXXXX (4 hex digits).

escValue

public static final java.lang.String escValue(java.lang.String val)

Examine a property value string, and escape any non-ISO-8859-1 unicode characters and leading whitespace.

Parameters:

val - Property value to unicode-escape

Returns:

Escaped val if escapes were needed, otherwise val

writeOne

public static final void writeOne(java.io.PrintWriter pw,
                                  java.lang.String key,
                                  java.lang.String val,
                                  java.util.List<java.lang.String> comments,
                                  boolean spacedEquals)

Write one key-value pair line to the properties file, making sure unicode escapes are re-escaped to \uXXXX where needed, otherwise keeping val unchanged and keeping high-bit ISO-8859-1 characters for easier viewing.

Parameters:

pw - An open PrintWriter for the output file; must have encoding ISO-8859-1

key - Key to write; assumes no special characters to be escaped

val - Value to write; leading whitespace and special characters will be escaped; backslashes will not be doubled, assumes they are part of an escape sequence in val

comments - Comment lines to write above key=value, or null; each one must contain a leading "# "

spacedEquals - If true, If true, the key and value are separated by " = " instead of "="

flush

public void flush()

close

public void close()

write

public void write(java.util.List<PropsFileParser.KeyPairLine> pairs,
                  java.lang.String fileComment)

Write these key-value pairs through the open writer.

Parameters:

pairs - Key-value pairs to write, same format as PropsFileParser.parseOneFile(File)

fileComment - Optional single-line comment to place above output keys, or null; will prepend "# "