1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.configuration2.convert; 18 19 import java.util.Collection; 20 import java.util.LinkedList; 21 import java.util.List; 22 23 import org.apache.commons.lang3.StringUtils; 24 25 /** 26 * <p> 27 * The default implementation of the {@code ListDelimiterHandler} interface. 28 * </p> 29 * <p> 30 * This class supports list splitting and delimiter escaping using a delimiter character that can be specified when 31 * constructing an instance. Splitting of strings works by scanning the input for the list delimiter character. The list 32 * delimiter character can be escaped by a backslash. So, provided that a comma is configured as list delimiter, in the 33 * example {@code val1,val2,val3} three values are recognized. In {@code 3\,1415} the list delimiter is escaped so that 34 * only a single element is detected. (Note that when writing these examples in Java code, each backslash has to be 35 * doubled. This is also true for all other examples in this documentation.) 36 * </p> 37 * <p> 38 * Because the backslash has a special meaning as escaping character it is always treated in a special way. If it occurs 39 * as a normal character in a property value, it has to be escaped using another backslash (similar to the rules of the 40 * Java programming language). The following example shows the correct way to define windows network shares: 41 * {@code \\\\Server\\path}. Note that each backslash is doubled. When combining the list delimiter with backslashes the 42 * same escaping rules apply. For instance, in {@code C:\\Temp\\,D:\\data\\} the list delimiter is recognized; it is not 43 * escaped by the preceding backslash because this backslash is itself escaped. In contrast, 44 * {@code C:\\Temp\\\,D:\\data\\} defines a single element with a comma being part of the value; two backslashes after 45 * {@code Temp} result in a single one, the third backslash escapes the list delimiter. 46 * </p> 47 * <p> 48 * As can be seen, there are some constellations which are a bit tricky and cause a larger number of backslashes in 49 * sequence. Nevertheless, the escaping rules are consistent and do not cause ambiguous results. 50 * </p> 51 * <p> 52 * Implementation node: An instance of this class can safely be shared between multiple {@code Configuration} instances. 53 * </p> 54 * 55 * @since 2.0 56 */ 57 public class DefaultListDelimiterHandler extends AbstractListDelimiterHandler { 58 /** Constant for the escape character. */ 59 private static final char ESCAPE = '\\'; 60 61 /** 62 * Constant for a buffer size for escaping strings. When a character is escaped the string becomes longer. Therefore, 63 * the output buffer is longer than the original string length. But we assume, that there are not too many characters 64 * that need to be escaped. 65 */ 66 private static final int BUF_SIZE = 16; 67 68 /** Stores the list delimiter character. */ 69 private final char delimiter; 70 71 /** 72 * Creates a new instance of {@code DefaultListDelimiterHandler} and sets the list delimiter character. 73 * 74 * @param listDelimiter the list delimiter character 75 */ 76 public DefaultListDelimiterHandler(final char listDelimiter) { 77 delimiter = listDelimiter; 78 } 79 80 /** 81 * Gets the list delimiter character used by this instance. 82 * 83 * @return the list delimiter character 84 */ 85 public char getDelimiter() { 86 return delimiter; 87 } 88 89 @Override 90 public Object escapeList(final List<?> values, final ValueTransformer transformer) { 91 final Object[] escapedValues = new Object[values.size()]; 92 int idx = 0; 93 for (final Object v : values) { 94 escapedValues[idx++] = escape(v, transformer); 95 } 96 return StringUtils.join(escapedValues, getDelimiter()); 97 } 98 99 @Override 100 protected String escapeString(final String s) { 101 final StringBuilder buf = new StringBuilder(s.length() + BUF_SIZE); 102 for (int i = 0; i < s.length(); i++) { 103 final char c = s.charAt(i); 104 if (c == getDelimiter() || c == ESCAPE) { 105 buf.append(ESCAPE); 106 } 107 buf.append(c); 108 } 109 return buf.toString(); 110 } 111 112 /** 113 * {@inheritDoc} This implementation reverses the escaping done by the {@code escape()} methods of this class. However, 114 * it tries to be tolerant with unexpected escaping sequences: If after the escape character "\" no allowed character 115 * follows, both the backslash and the following character are output. 116 */ 117 @Override 118 protected Collection<String> splitString(final String s, final boolean trim) { 119 final List<String> list = new LinkedList<>(); 120 StringBuilder token = new StringBuilder(); 121 boolean inEscape = false; 122 123 for (int i = 0; i < s.length(); i++) { 124 final char c = s.charAt(i); 125 if (inEscape) { 126 // last character was the escape marker 127 // can current character be escaped? 128 if (c != getDelimiter() && c != ESCAPE) { 129 // no, also add escape character 130 token.append(ESCAPE); 131 } 132 token.append(c); 133 inEscape = false; 134 } else if (c == getDelimiter()) { 135 // found a list delimiter -> add token and 136 // reset buffer 137 String t = token.toString(); 138 if (trim) { 139 t = t.trim(); 140 } 141 list.add(t); 142 token = new StringBuilder(); 143 } else if (c == ESCAPE) { 144 // potentially escape next character 145 inEscape = true; 146 } else { 147 token.append(c); 148 } 149 } 150 151 // Trailing delimiter? 152 if (inEscape) { 153 token.append(ESCAPE); 154 } 155 // Add last token 156 String t = token.toString(); 157 if (trim) { 158 t = t.trim(); 159 } 160 list.add(t); 161 162 return list; 163 } 164 }