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 * @version $Id: LegacyListDelimiterHandler.java 1842194 2018-09-27 22:24:23Z ggregory $
053 * @since 2.0
054 */
055public class LegacyListDelimiterHandler extends AbstractListDelimiterHandler
056{
057    /** Constant for the escaping character. */
058    private static final String ESCAPE = "\\";
059
060    /** Constant for the escaped escaping character. */
061    private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
062
063    /** Constant for a duplicated sequence of escaping characters. */
064    private static final String QUAD_ESC = DOUBLE_ESC + DOUBLE_ESC;
065
066    /** The list delimiter character. */
067    private final char delimiter;
068
069    /**
070     * Creates a new instance of {@code LegacyListDelimiterHandler} and sets the
071     * list delimiter character.
072     *
073     * @param listDelimiter the list delimiter character
074     */
075    public LegacyListDelimiterHandler(final char listDelimiter)
076    {
077        delimiter = listDelimiter;
078    }
079
080    /**
081     * Returns the list delimiter character.
082     *
083     * @return the list delimiter character
084     */
085    public char getDelimiter()
086    {
087        return delimiter;
088    }
089
090    /**
091     * {@inheritDoc} This implementation performs delimiter escaping for a
092     * single value (which is not part of a list).
093     */
094    @Override
095    public Object escape(final Object value, final ValueTransformer transformer)
096    {
097        return escapeValue(value, false, transformer);
098    }
099
100    /**
101     * {@inheritDoc} This implementation performs a special encoding of
102     * backslashes at the end of a string so that they are not interpreted as
103     * escape character for a following list delimiter.
104     */
105    @Override
106    public Object escapeList(final List<?> values, final ValueTransformer transformer)
107    {
108        if (!values.isEmpty())
109        {
110            final Iterator<?> it = values.iterator();
111            String lastValue = escapeValue(it.next(), true, transformer);
112            final StringBuilder buf = new StringBuilder(lastValue);
113            while (it.hasNext())
114            {
115                // if the last value ended with an escape character, it has
116                // to be escaped itself; otherwise the list delimiter will
117                // be escaped
118                if (lastValue.endsWith(ESCAPE)
119                        && (countTrailingBS(lastValue) / 2) % 2 != 0)
120                {
121                    buf.append(ESCAPE).append(ESCAPE);
122                }
123                buf.append(getDelimiter());
124                lastValue = escapeValue(it.next(), true, transformer);
125                buf.append(lastValue);
126            }
127            return buf.toString();
128        }
129        return null;
130    }
131
132    /**
133     * {@inheritDoc} This implementation simulates the old splitting algorithm.
134     * The string is split at the delimiter character if it is not escaped. If
135     * the delimiter character is not found, the input is returned unchanged.
136     */
137    @Override
138    protected Collection<String> splitString(final String s, final boolean trim)
139    {
140        if (s.indexOf(getDelimiter()) < 0)
141        {
142            return Collections.singleton(s);
143        }
144
145        final List<String> list = new ArrayList<>();
146
147        StringBuilder token = new StringBuilder();
148        int begin = 0;
149        boolean inEscape = false;
150        final char esc = ESCAPE.charAt(0);
151
152        while (begin < s.length())
153        {
154            final char c = s.charAt(begin);
155            if (inEscape)
156            {
157                // last character was the escape marker
158                // can current character be escaped?
159                if (c != getDelimiter() && c != esc)
160                {
161                    // no, also add escape character
162                    token.append(esc);
163                }
164                token.append(c);
165                inEscape = false;
166            }
167
168            else
169            {
170                if (c == getDelimiter())
171                {
172                    // found a list delimiter -> add token and
173                    // resetDefaultFileSystem buffer
174                    String t = token.toString();
175                    if (trim)
176                    {
177                        t = t.trim();
178                    }
179                    list.add(t);
180                    token = new StringBuilder();
181                }
182                else if (c == esc)
183                {
184                    // eventually escape next character
185                    inEscape = true;
186                }
187                else
188                {
189                    token.append(c);
190                }
191            }
192
193            begin++;
194        }
195
196        // Trailing delimiter?
197        if (inEscape)
198        {
199            token.append(esc);
200        }
201        // Add last token
202        String t = token.toString();
203        if (trim)
204        {
205            t = t.trim();
206        }
207        list.add(t);
208
209        return list;
210    }
211
212    /**
213     * {@inheritDoc} This is just a dummy implementation. It is never called.
214     */
215    @Override
216    protected String escapeString(final String s)
217    {
218        return null;
219    }
220
221    /**
222     * Performs the escaping of backslashes in the specified properties value.
223     * Because a double backslash is used to escape the escape character of a
224     * list delimiter, double backslashes also have to be escaped if the
225     * property is part of a (single line) list. In addition, because the output
226     * is written into a properties file, each occurrence of a backslash again
227     * has to be doubled. This method is called by {@code escapeValue()}.
228     *
229     * @param value the value to be escaped
230     * @param inList a flag whether the value is part of a list
231     * @return the value with escaped backslashes as string
232     */
233    protected String escapeBackslashs(final Object value, final boolean inList)
234    {
235        String strValue = String.valueOf(value);
236
237        if (inList && strValue.indexOf(DOUBLE_ESC) >= 0)
238        {
239            strValue = StringUtils.replace(strValue, DOUBLE_ESC, QUAD_ESC);
240        }
241
242        return strValue;
243    }
244
245    /**
246     * Escapes the given property value. This method is called on saving the
247     * configuration for each property value. It ensures a correct handling of
248     * backslash characters and also takes care that list delimiter characters
249     * in the value are escaped.
250     *
251     * @param value the property value
252     * @param inList a flag whether the value is part of a list
253     * @param transformer the {@code ValueTransformer}
254     * @return the escaped property value
255     */
256    protected String escapeValue(final Object value, final boolean inList,
257            final ValueTransformer transformer)
258    {
259        String escapedValue =
260                String.valueOf(transformer.transformValue(escapeBackslashs(
261                        value, inList)));
262        if (getDelimiter() != 0)
263        {
264            escapedValue =
265                    StringUtils.replace(escapedValue,
266                            String.valueOf(getDelimiter()), ESCAPE
267                                    + getDelimiter());
268        }
269        return escapedValue;
270    }
271
272    /**
273     * Returns the number of trailing backslashes. This is sometimes needed for
274     * the correct handling of escape characters.
275     *
276     * @param line the string to investigate
277     * @return the number of trailing backslashes
278     */
279    private static int countTrailingBS(final String line)
280    {
281        int bsCount = 0;
282        for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
283        {
284            bsCount++;
285        }
286
287        return bsCount;
288    }
289}