    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 *     https://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.Strings;
    026
    027/**
    028 * <p>
    029 * A specialized implementation of {@code ListDelimiterHandler} which simulates the list delimiter handling as it was
    030 * used by {@code PropertiesConfiguration} in Commons Configuration 1.x.
    031 * </p>
    032 * <p>
    033 * This class mainly exists for compatibility reasons. It is intended to be used by applications which have to deal with
    034 * properties files created by an older version of this library.
    035 * </p>
    036 * <p>
    037 * In the 1.x series of Commons Configuration list handling was not fully consistent. The escaping of property values
    038 * was done in a different way if they contained a list delimiter or not. From version 2.0 on, escaping is more
    039 * stringent which might cause slightly different results when parsing properties files created by or for Configuration
    040 * 1.x. If you encounter such problems, you can switch to this {@code ListDelimiterHandler} implementation rather than
    041 * the default one. In other cases, this class should not be used!
    042 * </p>
    043 * <p>
    044 * Implementation note: An instance of this class can safely be shared between multiple {@code Configuration} instances.
    045 * </p>
    046 *
    047 * @since 2.0
    048 */
    049public class LegacyListDelimiterHandler extends AbstractListDelimiterHandler {
    050
    051    /** Constant for the escaping character. */
    052    private static final String ESCAPE = "\\";
    053
    054    /** Constant for the escaped escaping character. */
    055    private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
    056
    057    /** Constant for a duplicated sequence of escaping characters. */
    058    private static final String QUAD_ESC = DOUBLE_ESC + DOUBLE_ESC;
    059
    060    /**
    061     * Returns the number of trailing backslashes. This is sometimes needed for the correct handling of escape characters.
    062     *
    063     * @param line the string to investigate
    064     * @return the number of trailing backslashes
    065     */
    066    private static int countTrailingBS(final String line) {
    067        int bsCount = 0;
    068        for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--) {
    069            bsCount++;
    070        }
    071
    072        return bsCount;
    073    }
    074
    075    /** The list delimiter character. */
    076    private final char delimiter;
    077
    078    /**
    079     * Creates a new instance of {@code LegacyListDelimiterHandler} and sets the list delimiter character.
    080     *
    081     * @param listDelimiter the list delimiter character
    082     */
    083    public LegacyListDelimiterHandler(final char listDelimiter) {
    084        delimiter = listDelimiter;
    085    }
    086
    087    /**
    088     * {@inheritDoc} This implementation performs delimiter escaping for a single value (which is not part of a list).
    089     */
    090    @Override
    091    public Object escape(final Object value, final ValueTransformer transformer) {
    092        return escapeValue(value, false, transformer);
    093    }
    094
    095    /**
    096     * Performs the escaping of backslashes in the specified properties value. Because a double backslash is used to escape
    097     * the escape character of a list delimiter, double backslashes also have to be escaped if the property is part of a
    098     * (single line) list. In addition, because the output is written into a properties file, each occurrence of a backslash
    099     * again has to be doubled. This method is called by {@code escapeValue()}.
    100     *
    101     * @param value the value to be escaped
    102     * @param inList a flag whether the value is part of a list
    103     * @return the value with escaped backslashes as string
    104     */
    105    protected String escapeBackslashs(final Object value, final boolean inList) {
    106        String strValue = String.valueOf(value);
    107
    108        if (inList && strValue.contains(DOUBLE_ESC)) {
    109            strValue = Strings.CS.replace(strValue, DOUBLE_ESC, QUAD_ESC);
    110        }
    111
    112        return strValue;
    113    }
    114
    115    /**
    116     * {@inheritDoc} This implementation performs a special encoding of backslashes at the end of a string so that they are
    117     * not interpreted as escape character for a following list delimiter.
    118     */
    119    @Override
    120    public Object escapeList(final List<?> values, final ValueTransformer transformer) {
    121        if (!values.isEmpty()) {
    122            final Iterator<?> it = values.iterator();
    123            String lastValue = escapeValue(it.next(), true, transformer);
    124            final StringBuilder buf = new StringBuilder(lastValue);
    125            while (it.hasNext()) {
    126                // if the last value ended with an escape character, it has
    127                // to be escaped itself; otherwise the list delimiter will
    128                // be escaped
    129                if (lastValue.endsWith(ESCAPE) && countTrailingBS(lastValue) / 2 % 2 != 0) {
    130                    buf.append(ESCAPE).append(ESCAPE);
    131                }
    132                buf.append(getDelimiter());
    133                lastValue = escapeValue(it.next(), true, transformer);
    134                buf.append(lastValue);
    135            }
    136            return buf.toString();
    137        }
    138        return null;
    139    }
    140
    141    /**
    142     * {@inheritDoc} This is just a dummy implementation. It is never called.
    143     */
    144    @Override
    145    protected String escapeString(final String s) {
    146        return null;
    147    }
    148
    149    /**
    150     * Escapes the given property value. This method is called on saving the configuration for each property value. It
    151     * ensures a correct handling of backslash characters and also takes care that list delimiter characters in the value
    152     * are escaped.
    153     *
    154     * @param value the property value
    155     * @param inList a flag whether the value is part of a list
    156     * @param transformer the {@code ValueTransformer}
    157     * @return the escaped property value
    158     */
    159    protected String escapeValue(final Object value, final boolean inList, final ValueTransformer transformer) {
    160        String escapedValue = String.valueOf(transformer.transformValue(escapeBackslashs(value, inList)));
    161        if (getDelimiter() != 0) {
    162            escapedValue = Strings.CS.replace(escapedValue, String.valueOf(getDelimiter()), ESCAPE + getDelimiter());
    163        }
    164        return escapedValue;
    165    }
    166
    167    /**
    168     * Gets the list delimiter character.
    169     *
    170     * @return the list delimiter character
    171     */
    172    public char getDelimiter() {
    173        return delimiter;
    174    }
    175
    176    /**
    177     * {@inheritDoc} This implementation simulates the old splitting algorithm. The string is split at the delimiter
    178     * character if it is not escaped. If the delimiter character is not found, the input is returned unchanged.
    179     */
    180    @Override
    181    protected Collection<String> splitString(final String s, final boolean trim) {
    182        if (s.indexOf(getDelimiter()) < 0) {
    183            return Collections.singleton(s);
    184        }
    185
    186        final List<String> list = new ArrayList<>();
    187
    188        StringBuilder token = new StringBuilder();
    189        int begin = 0;
    190        boolean inEscape = false;
    191        final char esc = ESCAPE.charAt(0);
    192
    193        while (begin < s.length()) {
    194            final char c = s.charAt(begin);
    195            if (inEscape) {
    196                // last character was the escape marker
    197                // can current character be escaped?
    198                if (c != getDelimiter() && c != esc) {
    199                    // no, also add escape character
    200                    token.append(esc);
    201                }
    202                token.append(c);
    203                inEscape = false;
    204            } else if (c == getDelimiter()) {
    205                // found a list delimiter -> add token and
    206                // resetDefaultFileSystem buffer
    207                String t = token.toString();
    208                if (trim) {
    209                    t = t.trim();
    210                }
    211                list.add(t);
    212                token = new StringBuilder();
    213            } else if (c == esc) {
    214                // eventually escape next character
    215                inEscape = true;
    216            } else {
    217                token.append(c);
    218            }
    219
    220            begin++;
    221        }
    222
    223        // Trailing delimiter?
    224        if (inEscape) {
    225            token.append(esc);
    226        }
    227        // Add last token
    228        String t = token.toString();
    229        if (trim) {
    230            t = t.trim();
    231        }
    232        list.add(t);
    233
    234        return list;
    235    }
    236}