001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.configuration2.convert;
018
019import java.util.ArrayList;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Iterator;
023import java.util.List;
024
025import org.apache.commons.lang3.StringUtils;
026
027/**
028 * <p>
029 * A specialized implementation of {@code ListDelimiterHandler} which simulates
030 * the list delimiter handling as it was used by {@code PropertiesConfiguration}
031 * in Commons Configuration 1.x.
032 * </p>
033 * <p>
034 * This class mainly exists for compatibility reasons. It is intended to be used
035 * by applications which have to deal with properties files created by an older
036 * version of this library.
037 * </p>
038 * <p>
039 * In the 1.x series of Commons Configuration list handling was not fully
040 * consistent. The escaping of property values was done in a different way if
041 * they contained a list delimiter or not. From version 2.0 on, escaping is more
042 * stringent which might cause slightly different results when parsing
043 * properties files created by or for Configuration 1.x. If you encounter such
044 * problems, you can switch to this {@code ListDelimiterHandler} implementation
045 * rather than the default one. In other cases, this class should not be used!
046 * </p>
047 * <p>
048 * Implementation note: An instance of this class can safely be shared between
049 * multiple {@code Configuration} instances.
050 * </p>
051 *
052 * @since 2.0
053 */
054public class LegacyListDelimiterHandler extends AbstractListDelimiterHandler
055{
056    /** Constant for the escaping character. */
057    private static final String ESCAPE = "\\";
058
059    /** Constant for the escaped escaping character. */
060    private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
061
062    /** Constant for a duplicated sequence of escaping characters. */
063    private static final String QUAD_ESC = DOUBLE_ESC + DOUBLE_ESC;
064
065    /** The list delimiter character. */
066    private final char delimiter;
067
068    /**
069     * Creates a new instance of {@code LegacyListDelimiterHandler} and sets the
070     * list delimiter character.
071     *
072     * @param listDelimiter the list delimiter character
073     */
074    public LegacyListDelimiterHandler(final char listDelimiter)
075    {
076        delimiter = listDelimiter;
077    }
078
079    /**
080     * Returns the list delimiter character.
081     *
082     * @return the list delimiter character
083     */
084    public char getDelimiter()
085    {
086        return delimiter;
087    }
088
089    /**
090     * {@inheritDoc} This implementation performs delimiter escaping for a
091     * single value (which is not part of a list).
092     */
093    @Override
094    public Object escape(final Object value, final ValueTransformer transformer)
095    {
096        return escapeValue(value, false, transformer);
097    }
098
099    /**
100     * {@inheritDoc} This implementation performs a special encoding of
101     * backslashes at the end of a string so that they are not interpreted as
102     * escape character for a following list delimiter.
103     */
104    @Override
105    public Object escapeList(final List<?> values, final ValueTransformer transformer)
106    {
107        if (!values.isEmpty())
108        {
109            final Iterator<?> it = values.iterator();
110            String lastValue = escapeValue(it.next(), true, transformer);
111            final StringBuilder buf = new StringBuilder(lastValue);
112            while (it.hasNext())
113            {
114                // if the last value ended with an escape character, it has
115                // to be escaped itself; otherwise the list delimiter will
116                // be escaped
117                if (lastValue.endsWith(ESCAPE)
118                        && (countTrailingBS(lastValue) / 2) % 2 != 0)
119                {
120                    buf.append(ESCAPE).append(ESCAPE);
121                }
122                buf.append(getDelimiter());
123                lastValue = escapeValue(it.next(), true, transformer);
124                buf.append(lastValue);
125            }
126            return buf.toString();
127        }
128        return null;
129    }
130
131    /**
132     * {@inheritDoc} This implementation simulates the old splitting algorithm.
133     * The string is split at the delimiter character if it is not escaped. If
134     * the delimiter character is not found, the input is returned unchanged.
135     */
136    @Override
137    protected Collection<String> splitString(final String s, final boolean trim)
138    {
139        if (s.indexOf(getDelimiter()) < 0)
140        {
141            return Collections.singleton(s);
142        }
143
144        final List<String> list = new ArrayList<>();
145
146        StringBuilder token = new StringBuilder();
147        int begin = 0;
148        boolean inEscape = false;
149        final char esc = ESCAPE.charAt(0);
150
151        while (begin < s.length())
152        {
153            final char c = s.charAt(begin);
154            if (inEscape)
155            {
156                // last character was the escape marker
157                // can current character be escaped?
158                if (c != getDelimiter() && c != esc)
159                {
160                    // no, also add escape character
161                    token.append(esc);
162                }
163                token.append(c);
164                inEscape = false;
165            }
166
167            else
168            {
169                if (c == getDelimiter())
170                {
171                    // found a list delimiter -> add token and
172                    // resetDefaultFileSystem buffer
173                    String t = token.toString();
174                    if (trim)
175                    {
176                        t = t.trim();
177                    }
178                    list.add(t);
179                    token = new StringBuilder();
180                }
181                else if (c == esc)
182                {
183                    // eventually escape next character
184                    inEscape = true;
185                }
186                else
187                {
188                    token.append(c);
189                }
190            }
191
192            begin++;
193        }
194
195        // Trailing delimiter?
196        if (inEscape)
197        {
198            token.append(esc);
199        }
200        // Add last token
201        String t = token.toString();
202        if (trim)
203        {
204            t = t.trim();
205        }
206        list.add(t);
207
208        return list;
209    }
210
211    /**
212     * {@inheritDoc} This is just a dummy implementation. It is never called.
213     */
214    @Override
215    protected String escapeString(final String s)
216    {
217        return null;
218    }
219
220    /**
221     * Performs the escaping of backslashes in the specified properties value.
222     * Because a double backslash is used to escape the escape character of a
223     * list delimiter, double backslashes also have to be escaped if the
224     * property is part of a (single line) list. In addition, because the output
225     * is written into a properties file, each occurrence of a backslash again
226     * has to be doubled. This method is called by {@code escapeValue()}.
227     *
228     * @param value the value to be escaped
229     * @param inList a flag whether the value is part of a list
230     * @return the value with escaped backslashes as string
231     */
232    protected String escapeBackslashs(final Object value, final boolean inList)
233    {
234        String strValue = String.valueOf(value);
235
236        if (inList && strValue.indexOf(DOUBLE_ESC) >= 0)
237        {
238            strValue = StringUtils.replace(strValue, DOUBLE_ESC, QUAD_ESC);
239        }
240
241        return strValue;
242    }
243
244    /**
245     * Escapes the given property value. This method is called on saving the
246     * configuration for each property value. It ensures a correct handling of
247     * backslash characters and also takes care that list delimiter characters
248     * in the value are escaped.
249     *
250     * @param value the property value
251     * @param inList a flag whether the value is part of a list
252     * @param transformer the {@code ValueTransformer}
253     * @return the escaped property value
254     */
255    protected String escapeValue(final Object value, final boolean inList,
256            final ValueTransformer transformer)
257    {
258        String escapedValue =
259                String.valueOf(transformer.transformValue(escapeBackslashs(
260                        value, inList)));
261        if (getDelimiter() != 0)
262        {
263            escapedValue =
264                    StringUtils.replace(escapedValue,
265                            String.valueOf(getDelimiter()), ESCAPE
266                                    + getDelimiter());
267        }
268        return escapedValue;
269    }
270
271    /**
272     * Returns the number of trailing backslashes. This is sometimes needed for
273     * the correct handling of escape characters.
274     *
275     * @param line the string to investigate
276     * @return the number of trailing backslashes
277     */
278    private static int countTrailingBS(final String line)
279    {
280        int bsCount = 0;
281        for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
282        {
283            bsCount++;
284        }
285
286        return bsCount;
287    }
288}