/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.tools.ant.util;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintStream;
import java.io.PushbackReader;
import java.io.Serializable;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Properties;
A Properties collection which preserves comments and whitespace
present in the input stream from which it was loaded.
The class defers the usual work of the java.util.Properties
class to there, but it also keeps track of the contents of the
input stream from which it was loaded (if applicable), so that it can
write out the properties in as close a form as possible to the input.
If no changes occur to property values, the output should be the same
as the input, except for the leading date stamp, as normal for a
properties file. Properties added are appended to the file. Properties
whose values are changed are changed in place. Properties that are
removed are excised. If the removeComments
flag is set,
then the comments immediately preceding the property are also removed.
If a second set of properties is loaded into an existing set, the
lines of the second set are added to the end. Note however, that if a
property already stored is present in a stream subsequently loaded, then
that property is removed before the new value is set. For example,
consider the file
# the first line
alpha=one
# the second line
beta=two
This file is loaded, and then the following is also loaded into the
same LayoutPreservingProperties
object
# association
beta=band
# and finally
gamma=rays
The resulting collection sequence of logical lines depends on whether
or not removeComments
was set at the time the second stream
is loaded. If it is set, then the resulting list of lines is
# the first line
alpha=one
# association
beta=band
# and finally
gamma=rays
If the flag is not set, then the comment "the second line" is retained,
although the key-value pair beta=two
is removed.
/**
* <p>A Properties collection which preserves comments and whitespace
* present in the input stream from which it was loaded.</p>
* <p>The class defers the usual work of the <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html">java.util.Properties</a>
* class to there, but it also keeps track of the contents of the
* input stream from which it was loaded (if applicable), so that it can
* write out the properties in as close a form as possible to the input.</p>
* <p>If no changes occur to property values, the output should be the same
* as the input, except for the leading date stamp, as normal for a
* properties file. Properties added are appended to the file. Properties
* whose values are changed are changed in place. Properties that are
* removed are excised. If the <code>removeComments</code> flag is set,
* then the comments immediately preceding the property are also removed.</p>
* <p>If a second set of properties is loaded into an existing set, the
* lines of the second set are added to the end. Note however, that if a
* property already stored is present in a stream subsequently loaded, then
* that property is removed before the new value is set. For example,
* consider the file</p>
* <pre> # the first line
* alpha=one
*
* # the second line
* beta=two</pre>
* <p>This file is loaded, and then the following is also loaded into the
* same <code>LayoutPreservingProperties</code> object</p>
* <pre> # association
* beta=band
*
* # and finally
* gamma=rays</pre>
* <p>The resulting collection sequence of logical lines depends on whether
* or not <code>removeComments</code> was set at the time the second stream
* is loaded. If it is set, then the resulting list of lines is</p>
* <pre> # the first line
* alpha=one
*
* # association
* beta=band
*
* # and finally
* gamma=rays</pre>
* <p>If the flag is not set, then the comment "the second line" is retained,
* although the key-value pair <code>beta=two</code> is removed.</p>
*/
public class LayoutPreservingProperties extends Properties {
private static final long serialVersionUID = 1L;
private String eol = System.lineSeparator();
Logical lines have escaping and line continuation taken care
of. Comments and blank lines are logical lines; they are not
removed.
/**
* Logical lines have escaping and line continuation taken care
* of. Comments and blank lines are logical lines; they are not
* removed.
*/
private List<LogicalLine> logicalLines = new ArrayList<>();
Position in the logicalLines
list, keyed by property name.
/**
* Position in the <code>logicalLines</code> list, keyed by property name.
*/
private Map<String, Integer> keyedPairLines = new HashMap<>();
Flag to indicate that, when we remove a property from the file, we
also want to remove the comments that precede it.
/**
* Flag to indicate that, when we remove a property from the file, we
* also want to remove the comments that precede it.
*/
private boolean removeComments;
Create a new, empty, Properties collection, with no defaults.
/**
* Create a new, empty, Properties collection, with no defaults.
*/
public LayoutPreservingProperties() {
super();
}
Create a new, empty, Properties collection, with the specified defaults.
Params: - defaults – the default property values
/**
* Create a new, empty, Properties collection, with the specified defaults.
* @param defaults the default property values
*/
public LayoutPreservingProperties(final Properties defaults) {
super(defaults);
}
Returns true
if comments are removed along with
properties, or false
otherwise. If
true
, then when a property is removed, the comment
preceding it in the original file is removed also.
Returns: true
if leading comments are removed when
a property is removed; false
otherwise
/**
* Returns <code>true</code> if comments are removed along with
* properties, or <code>false</code> otherwise. If
* <code>true</code>, then when a property is removed, the comment
* preceding it in the original file is removed also.
* @return <code>true</code> if leading comments are removed when
* a property is removed; <code>false</code> otherwise
*/
public boolean isRemoveComments() {
return removeComments;
}
Sets the behaviour for comments accompanying properties that
are being removed. If true
, then when a property
is removed, the comment preceding it in the original file is
removed also.
Params: - val –
true
if leading comments are to be
removed when a property is removed; false
otherwise
/**
* Sets the behaviour for comments accompanying properties that
* are being removed. If <code>true</code>, then when a property
* is removed, the comment preceding it in the original file is
* removed also.
* @param val <code>true</code> if leading comments are to be
* removed when a property is removed; <code>false</code>
* otherwise
*/
public void setRemoveComments(final boolean val) {
removeComments = val;
}
@Override
public void load(final InputStream inStream) throws IOException {
final String s = readLines(inStream);
final byte[] ba = s.getBytes(StandardCharsets.ISO_8859_1);
final ByteArrayInputStream bais = new ByteArrayInputStream(ba);
super.load(bais);
}
@Override
public Object put(final Object key, final Object value) throws NullPointerException {
final Object obj = super.put(key, value);
// the above call will have failed if key or value are null
innerSetProperty(key.toString(), value.toString());
return obj;
}
@Override
public Object setProperty(final String key, final String value)
throws NullPointerException {
final Object obj = super.setProperty(key, value);
// the above call will have failed if key or value are null
innerSetProperty(key, value);
return obj;
}
Store a new key-value pair, or add a new one. The normal functionality is taken care of by the superclass in the call to setProperty
; this method takes care of this classes extensions. Params: - key – the key of the property to be stored
- value – the value to be stored
/**
* Store a new key-value pair, or add a new one. The normal
* functionality is taken care of by the superclass in the call to
* {@link #setProperty}; this method takes care of this classes
* extensions.
* @param key the key of the property to be stored
* @param value the value to be stored
*/
private void innerSetProperty(String key, String value) {
value = escapeValue(value);
if (keyedPairLines.containsKey(key)) {
final Integer i = keyedPairLines.get(key);
final Pair p = (Pair) logicalLines.get(i);
p.setValue(value);
} else {
key = escapeName(key);
final Pair p = new Pair(key, value);
p.setNew(true);
keyedPairLines.put(key, logicalLines.size());
logicalLines.add(p);
}
}
@Override
public void clear() {
super.clear();
keyedPairLines.clear();
logicalLines.clear();
}
@Override
public Object remove(final Object key) {
final Object obj = super.remove(key);
final Integer i = keyedPairLines.remove(key);
if (null != i) {
if (removeComments) {
removeCommentsEndingAt(i);
}
logicalLines.set(i, null);
}
return obj;
}
@Override
public Object clone() {
final LayoutPreservingProperties dolly =
(LayoutPreservingProperties) super.clone();
dolly.keyedPairLines = new HashMap<>(this.keyedPairLines);
dolly.logicalLines = new ArrayList<>(this.logicalLines);
final int size = dolly.logicalLines.size();
for (int j = 0; j < size; j++) {
final LogicalLine line = dolly.logicalLines.get(j);
if (line instanceof Pair) {
final Pair p = (Pair) line;
dolly.logicalLines.set(j, (Pair) p.clone());
}
// no reason to clone other lines are they are immutable
}
return dolly;
}
Echo the lines of the properties (including blanks and comments) to the
stream.
Params: - out – the stream to write to
/**
* Echo the lines of the properties (including blanks and comments) to the
* stream.
* @param out the stream to write to
*/
public void listLines(final PrintStream out) {
out.println("-- logical lines --");
for (LogicalLine line : logicalLines) {
if (line instanceof Blank) {
out.println("blank: \"" + line + "\"");
} else if (line instanceof Comment) {
out.println("comment: \"" + line + "\"");
} else if (line instanceof Pair) {
out.println("pair: \"" + line + "\"");
}
}
}
Save the properties to a file.
Params: - dest – the file to write to
Throws: - IOException – if save fails
/**
* Save the properties to a file.
* @param dest the file to write to
* @throws IOException if save fails
*/
public void saveAs(final File dest) throws IOException {
final OutputStream fos = Files.newOutputStream(dest.toPath());
store(fos, null);
fos.close();
}
@Override
public void store(final OutputStream out, final String header) throws IOException {
final OutputStreamWriter osw = new OutputStreamWriter(out, StandardCharsets.ISO_8859_1);
int skipLines = 0;
final int totalLines = logicalLines.size();
if (header != null) {
osw.write("#" + header + eol);
if (totalLines > 0
&& logicalLines.get(0) instanceof Comment
&& header.equals(logicalLines.get(0).toString().substring(1))) {
skipLines = 1;
}
}
// we may be updating a file written by this class, replace
// the date comment instead of adding a new one and preserving
// the one written last time
if (totalLines > skipLines
&& logicalLines.get(skipLines) instanceof Comment) {
try {
DateUtils.parseDateFromHeader(logicalLines
.get(skipLines)
.toString().substring(1));
skipLines++;
} catch (final java.text.ParseException pe) {
// not an existing date comment
}
}
osw.write("#" + DateUtils.getDateForHeader() + eol);
boolean writtenSep = false;
for (LogicalLine line : logicalLines.subList(skipLines, totalLines)) {
if (line instanceof Pair) {
if (((Pair) line).isNew()) {
if (!writtenSep) {
osw.write(eol);
writtenSep = true;
}
}
osw.write(line.toString() + eol);
} else if (line != null) {
osw.write(line.toString() + eol);
}
}
osw.close();
}
Reads a properties file into an internally maintained
collection of logical lines (possibly spanning physical lines),
which make up the comments, blank lines and properties of the
file.
Params: - is – the stream from which to read the data
/**
* Reads a properties file into an internally maintained
* collection of logical lines (possibly spanning physical lines),
* which make up the comments, blank lines and properties of the
* file.
* @param is the stream from which to read the data
*/
private String readLines(final InputStream is) throws IOException {
final InputStreamReader isr = new InputStreamReader(is, StandardCharsets.ISO_8859_1);
final PushbackReader pbr = new PushbackReader(isr, 1);
if (!logicalLines.isEmpty()) {
// we add a blank line for spacing
logicalLines.add(new Blank());
}
String s = readFirstLine(pbr);
final BufferedReader br = new BufferedReader(pbr);
boolean continuation = false;
boolean comment = false;
final StringBuilder fileBuffer = new StringBuilder();
final StringBuilder logicalLineBuffer = new StringBuilder();
while (s != null) {
fileBuffer.append(s).append(eol);
if (continuation) {
// put in the line feed that was removed
s = "\n" + s;
} else {
// could be a comment, if first non-whitespace is a # or !
comment = s.matches("^[ \t\f]*[#!].*");
}
// continuation if not a comment and the line ends is an
// odd number of backslashes
if (!comment) {
continuation = requiresContinuation(s);
}
logicalLineBuffer.append(s);
if (!continuation) {
LogicalLine line;
if (comment) {
line = new Comment(logicalLineBuffer.toString());
} else if (logicalLineBuffer.toString().trim().isEmpty()) {
line = new Blank();
} else {
line = new Pair(logicalLineBuffer.toString());
final String key = unescape(((Pair) line).getName());
if (keyedPairLines.containsKey(key)) {
// this key is already present, so we remove it and add
// the new one
remove(key);
}
keyedPairLines.put(key, logicalLines.size());
}
logicalLines.add(line);
logicalLineBuffer.setLength(0);
}
s = br.readLine();
}
return fileBuffer.toString();
}
Reads the first line and determines the EOL-style of the file
(relies on the style to be consistent, of course).
Sets LS as a side-effect.
Returns: the first line without any line separator, leaves the
reader positioned after the first line separator Since: Ant 1.8.2
/**
* Reads the first line and determines the EOL-style of the file
* (relies on the style to be consistent, of course).
*
* <p>Sets LS as a side-effect.</p>
*
* @return the first line without any line separator, leaves the
* reader positioned after the first line separator
*
* @since Ant 1.8.2
*/
private String readFirstLine(final PushbackReader r) throws IOException {
final StringBuilder sb = new StringBuilder(80);
int ch = r.read();
boolean hasCR = false;
// when reaching EOF before the first EOL, assume native line
// feeds
eol = System.lineSeparator();
while (ch >= 0) {
if (hasCR && ch != '\n') {
// line feed is sole CR
r.unread(ch);
break;
}
if (ch == '\r') {
eol = "\r";
hasCR = true;
} else if (ch == '\n') {
eol = hasCR ? "\r\n" : "\n";
break;
} else {
sb.append((char) ch);
}
ch = r.read();
}
return sb.toString();
}
Returns true
if the line represented by
s
is to be continued on the next line of the file,
or false
otherwise.
Params: - s – the contents of the line to examine
Returns: true
if the line is to be continued,
false
otherwise
/**
* Returns <code>true</code> if the line represented by
* <code>s</code> is to be continued on the next line of the file,
* or <code>false</code> otherwise.
* @param s the contents of the line to examine
* @return <code>true</code> if the line is to be continued,
* <code>false</code> otherwise
*/
private boolean requiresContinuation(final String s) {
final char[] ca = s.toCharArray();
int i = ca.length - 1;
while (i > 0 && ca[i] == '\\') {
i--;
}
// trailing backslashes
final int tb = ca.length - i - 1;
return tb % 2 == 1;
}
Unescape the string according to the rules for a Properties
file, as laid out in the docs for java.util.Properties.
Params: - s – the string to unescape (coming from the source file)
Returns: the unescaped string
/**
* Unescape the string according to the rules for a Properties
* file, as laid out in the docs for <a
* href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html">java.util.Properties</a>.
* @param s the string to unescape (coming from the source file)
* @return the unescaped string
*/
private String unescape(final String s) {
/*
* The following combinations are converted:
* \n newline
* \r carriage return
* \f form feed
* \t tab
* \\ backslash
* \u0000 unicode character
* Any other slash is ignored, so
* \b becomes 'b'.
*/
final char[] ch = new char[s.length() + 1];
s.getChars(0, s.length(), ch, 0);
ch[s.length()] = '\n';
final StringBuilder buffy = new StringBuilder(s.length());
for (int i = 0; i < ch.length; i++) {
char c = ch[i];
if (c == '\n') {
// we have hit out end-of-string marker
break;
}
if (c == '\\') {
// possibly an escape sequence
c = ch[++i];
if (c == 'n') {
buffy.append('\n');
} else if (c == 'r') {
buffy.append('\r');
} else if (c == 'f') {
buffy.append('\f');
} else if (c == 't') {
buffy.append('\t');
} else if (c == 'u') {
// handle unicode escapes
c = unescapeUnicode(ch, i + 1);
i += 4;
buffy.append(c);
} else {
buffy.append(c);
}
} else {
buffy.append(c);
}
}
return buffy.toString();
}
Retrieve the unicode character whose code is listed at position
i
in the character array ch
.
Params: - ch – the character array containing the unicode character code
Returns: the character extracted
/**
* Retrieve the unicode character whose code is listed at position
* <code>i</code> in the character array <code>ch</code>.
* @param ch the character array containing the unicode character code
* @return the character extracted
*/
private char unescapeUnicode(final char[] ch, final int i) {
final String s = new String(ch, i, 4);
return (char) Integer.parseInt(s, 16);
}
Escape the string s
according to the rules in the
docs for java.util.Properties.
Params: - s – the string to escape
Returns: the escaped string
/**
* Escape the string <code>s</code> according to the rules in the
* docs for <a
* href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html">java.util.Properties</a>.
* @param s the string to escape
* @return the escaped string
*/
private String escapeValue(final String s) {
return escape(s, false);
}
Escape the string s
according to the rules in the
docs for java.util.Properties.
This method escapes all the whitespace, not just the stuff at
the beginning.
Params: - s – the string to escape
Returns: the escaped string
/**
* Escape the string <code>s</code> according to the rules in the
* docs for <a
* href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html">java.util.Properties</a>.
* This method escapes all the whitespace, not just the stuff at
* the beginning.
* @param s the string to escape
* @return the escaped string
*/
private String escapeName(final String s) {
return escape(s, true);
}
Escape the string s
according to the rules in the
docs for java.util.Properties.
Params: - s – the string to escape
- escapeAllSpaces – if
true
the method escapes
all the spaces, if false
, it escapes only the
leading whitespace
Returns: the escaped string
/**
* Escape the string <code>s</code> according to the rules in the
* docs for <a
* href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html">java.util.Properties</a>.
* @param s the string to escape
* @param escapeAllSpaces if <code>true</code> the method escapes
* all the spaces, if <code>false</code>, it escapes only the
* leading whitespace
* @return the escaped string
*/
private String escape(final String s, final boolean escapeAllSpaces) {
if (s == null) {
return null;
}
final char[] ch = new char[s.length()];
s.getChars(0, s.length(), ch, 0);
final String forEscaping = "\t\f\r\n\\:=#!";
final String escaped = "tfrn\\:=#!";
final StringBuilder buffy = new StringBuilder(s.length());
boolean leadingSpace = true;
for (final char c : ch) {
if (c == ' ') {
if (escapeAllSpaces || leadingSpace) {
buffy.append("\\");
}
} else {
leadingSpace = false;
}
final int p = forEscaping.indexOf(c);
if (p != -1) {
buffy.append("\\").append(escaped, p, p + 1);
} else if (c < 0x0020 || c > 0x007e) {
buffy.append(escapeUnicode(c));
} else {
buffy.append(c);
}
}
return buffy.toString();
}
Return the unicode escape sequence for a character, in the form
\u005CuNNNN.
Params: - ch – the character to encode
Returns: the unicode escape sequence
/**
* Return the unicode escape sequence for a character, in the form
* \u005CuNNNN.
* @param ch the character to encode
* @return the unicode escape sequence
*/
private String escapeUnicode(final char ch) {
return "\\" + UnicodeUtil.EscapeUnicode(ch);
}
Remove the comments in the leading up the logicalLines
list leading up to line pos
.
Params: - pos – the line number to which the comments lead
/**
* Remove the comments in the leading up the {@link #logicalLines}
* list leading up to line <code>pos</code>.
* @param pos the line number to which the comments lead
*/
private void removeCommentsEndingAt(int pos) {
/* We want to remove comments preceding this position. Step
* back counting blank lines (call this range B1) until we hit
* something non-blank. If what we hit is not a comment, then
* exit. If what we hit is a comment, then step back counting
* comment lines (call this range C1). Nullify lines in C1 and
* B1.
*/
final int end = pos - 1;
// step pos back until it hits something non-blank
for (pos = end; pos > 0; pos--) {
if (!(logicalLines.get(pos) instanceof Blank)) {
break;
}
}
// if the thing it hits is not a comment, then we have nothing
// to remove
if (!(logicalLines.get(pos) instanceof Comment)) {
return;
}
// step back until we hit the start of the comment
for (; pos >= 0; pos--) {
if (!(logicalLines.get(pos) instanceof Comment)) {
break;
}
}
// now we want to delete from pos+1 to end
for (pos++; pos <= end; pos++) {
logicalLines.set(pos, null);
}
}
A logical line of the properties input stream.
/**
* A logical line of the properties input stream.
*/
private abstract static class LogicalLine implements Serializable {
private static final long serialVersionUID = 1L;
private String text;
public LogicalLine(final String text) {
this.text = text;
}
public void setText(final String text) {
this.text = text;
}
@Override
public String toString() {
return text;
}
}
A blank line of the input stream.
/**
* A blank line of the input stream.
*/
private static class Blank extends LogicalLine {
private static final long serialVersionUID = 1L;
public Blank() {
super("");
}
}
A comment line of the input stream.
/**
* A comment line of the input stream.
*/
private class Comment extends LogicalLine {
private static final long serialVersionUID = 1L;
public Comment(final String text) {
super(text);
}
}
A key-value pair from the input stream. This may span more than
one physical line, but it is constitues as a single logical
line.
/**
* A key-value pair from the input stream. This may span more than
* one physical line, but it is constitues as a single logical
* line.
*/
private static class Pair extends LogicalLine implements Cloneable {
private static final long serialVersionUID = 1L;
private String name;
private String value;
private boolean added;
public Pair(final String text) {
super(text);
parsePair(text);
}
public Pair(final String name, final String value) {
this(name + "=" + value);
}
public String getName() {
return name;
}
@SuppressWarnings("unused")
public String getValue() {
return value;
}
public void setValue(final String value) {
this.value = value;
setText(name + "=" + value);
}
public boolean isNew() {
return added;
}
public void setNew(final boolean val) {
added = val;
}
@Override
public Object clone() {
Object dolly = null;
try {
dolly = super.clone();
} catch (final CloneNotSupportedException e) {
// should be fine
e.printStackTrace(); //NOSONAR
}
return dolly;
}
private void parsePair(final String text) {
// need to find first non-escaped '=', ':', '\t' or ' '.
final int pos = findFirstSeparator(text);
if (pos == -1) {
// trim leading whitespace only
name = text;
setValue(null);
} else {
name = text.substring(0, pos);
setValue(text.substring(pos + 1));
}
// trim leading whitespace only
name = stripStart(name, " \t\f");
}
private String stripStart(final String s, final String chars) {
if (s == null) {
return null;
}
int i = 0;
for (; i < s.length(); i++) {
if (chars.indexOf(s.charAt(i)) == -1) {
break;
}
}
if (i == s.length()) {
return "";
}
return s.substring(i);
}
private int findFirstSeparator(String s) {
// Replace double backslashes with underscores so that they don't
// confuse us looking for '\t' or '\=', for example, but they also
// don't change the position of other characters
s = s.replaceAll("\\\\\\\\", "__");
// Replace single backslashes followed by separators, so we don't
// pick them up
s = s.replaceAll("\\\\=", "__");
s = s.replaceAll("\\\\:", "__");
s = s.replaceAll("\\\\ ", "__");
s = s.replaceAll("\\\\t", "__");
// Now only the unescaped separators are left
return indexOfAny(s, " :=\t");
}
private int indexOfAny(final String s, final String chars) {
if (s == null || chars == null) {
return -1;
}
int p = s.length() + 1;
for (int i = 0; i < chars.length(); i++) {
final int x = s.indexOf(chars.charAt(i));
if (x != -1 && x < p) {
p = x;
}
}
if (p == s.length() + 1) {
return -1;
}
return p;
}
}
}