/*
 * 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
 *
 *     http://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.commons.configuration2.convert;

import java.util.Collection;
import java.util.List;


Definition of an interface that controls the handling of list delimiters in
configuration properties.

 
AbstractConfiguration supports list delimiters in property values. If such a delimiter is found, the value actually contains multiple values and has to be split. This is useful for instance for 
PropertiesConfiguration: properties files that have to be compatible with the java.util.Properties class cannot have multiple occurrences of a single property key, therefore a different storage scheme for multi-valued properties is needed. A possible storage scheme could look as follows: 
myProperty=value1,value2,value3

 Here a comma is used as list delimiter. When parsing this property (and using a corresponding ListDelimiterHandler implementation) the string value is split, and three values are added for the property key. 
 A ListDelimiterHandler knows how to parse and to escape property values. It is called by concrete Configuration implementations when they have to deal with properties with multiple values. 
Since:
2.0/**
 * <p>
 * Definition of an interface that controls the handling of list delimiters in
 * configuration properties.
 * </p>
 * <p>
 * {@link org.apache.commons.configuration2.AbstractConfiguration
 * AbstractConfiguration} supports list delimiters in property values. If such a
 * delimiter is found, the value actually contains multiple values and has to be
 * split. This is useful for instance for
 * {@link org.apache.commons.configuration2.PropertiesConfiguration
 * PropertiesConfiguration}: properties files that have to be compatible with
 * the {@code java.util.Properties} class cannot have multiple occurrences of a
 * single property key, therefore a different storage scheme for multi-valued
 * properties is needed. A possible storage scheme could look as follows:
 * </p>
 *
 * <pre>
 * myProperty=value1,value2,value3
 * </pre>
 *
 * <p>
 * Here a comma is used as list delimiter. When parsing this property (and using
 * a corresponding {@code ListDelimiterHandler} implementation) the string value
 * is split, and three values are added for the property key.
 * </p>
 * <p>
 * A {@code ListDelimiterHandler} knows how to parse and to escape property
 * values. It is called by concrete {@code Configuration} implementations when
 * they have to deal with properties with multiple values.
 * </p>
 *
 * @since 2.0
 */
public interface ListDelimiterHandler
{
    
A specialized ValueTransformer implementation which does no transformation. The transformValue() method just returns the passed in object without changes. This instance can be used by configurations which do not require additional encoding. /**
     * A specialized {@code ValueTransformer} implementation which does no
     * transformation. The {@code transformValue()} method just returns the
     * passed in object without changes. This instance can be used by
     * configurations which do not require additional encoding.
     */
    ValueTransformer NOOP_TRANSFORMER = value -> value;

    
Parses the specified value for list delimiters and splits it if necessary. The passed in object can be either a single value or a complex one, e.g. a collection, an array, or an Iterable. It is the responsibility of this method to return an Iterable which contains all extracted values. 
Params:
value – the value to be parsed
Returns:
an Iterable allowing access to all extracted values/**
     * Parses the specified value for list delimiters and splits it if
     * necessary. The passed in object can be either a single value or a complex
     * one, e.g. a collection, an array, or an {@code Iterable}. It is the
     * responsibility of this method to return an {@code Iterable} which
     * contains all extracted values.
     *
     * @param value the value to be parsed
     * @return an {@code Iterable} allowing access to all extracted values
     */
    Iterable<?> parse(Object value);

    
Splits the specified string at the list delimiter and returns a collection with all extracted components. A concrete implementation also has to deal with escape characters which might mask a list delimiter character at certain positions. The boolean trim flag determines whether each extracted component should be trimmed. This typically makes sense as the list delimiter may be surrounded by whitespace. However, there may be specific use cases in which automatic trimming is not desired. 
Params:
s – the string to be split
trim – a flag whether each component of the string is to be trimmed
Returns:
a collection with all components extracted from the string/**
     * Splits the specified string at the list delimiter and returns a
     * collection with all extracted components. A concrete implementation also
     * has to deal with escape characters which might mask a list delimiter
     * character at certain positions. The boolean {@code trim} flag determines
     * whether each extracted component should be trimmed. This typically makes
     * sense as the list delimiter may be surrounded by whitespace. However,
     * there may be specific use cases in which automatic trimming is not
     * desired.
     *
     * @param s the string to be split
     * @param trim a flag whether each component of the string is to be trimmed
     * @return a collection with all components extracted from the string
     */
    Collection<String> split(String s, boolean trim);

    
Escapes the specified single value object. This method is called for
properties containing only a single value. So this method can rely on the
fact that the passed in object is not a list. An implementation has to
check whether the value contains list delimiter characters and - if so -
escape them accordingly.
Params:
value – the value to be escaped
transformer – a ValueTransformer for an additional encoding (must not be null)
Returns:
the escaped value/**
     * Escapes the specified single value object. This method is called for
     * properties containing only a single value. So this method can rely on the
     * fact that the passed in object is not a list. An implementation has to
     * check whether the value contains list delimiter characters and - if so -
     * escape them accordingly.
     *
     * @param value the value to be escaped
     * @param transformer a {@code ValueTransformer} for an additional encoding
     *        (must not be <b>null</b>)
     * @return the escaped value
     */
    Object escape(Object value, ValueTransformer transformer);

    
Escapes all values in the given list and concatenates them to a single
string. This operation is required by configurations that have to
represent properties with multiple values in a single line in their
external configuration representation. This may require an advanced
escaping in some cases.
Params:
values – the list with all the values to be converted to a single
       value
transformer – a ValueTransformer for an additional encoding (must not be null)
Returns:
the resulting escaped value/**
     * Escapes all values in the given list and concatenates them to a single
     * string. This operation is required by configurations that have to
     * represent properties with multiple values in a single line in their
     * external configuration representation. This may require an advanced
     * escaping in some cases.
     *
     * @param values the list with all the values to be converted to a single
     *        value
     * @param transformer a {@code ValueTransformer} for an additional encoding
     *        (must not be <b>null</b>)
     * @return the resulting escaped value
     */
    Object escapeList(List<?> values, ValueTransformer transformer);
}