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.cli;
018
019import java.io.File;
020import java.net.MalformedURLException;
021import java.net.URL;
022import java.nio.file.InvalidPathException;
023import java.nio.file.Path;
024import java.nio.file.Paths;
025import java.text.SimpleDateFormat;
026import java.util.Date;
027
028/**
029 * The definition of the functional interface to call when doing a conversion. Like {@code Function<String,T>} but can throw an Exception.
030 *
031 * @param <T> The return type for the function.
032 * @param <E> The kind of thrown exception or error.
033 * @since 1.7.0
034 */
035@FunctionalInterface
036public interface Converter<T, E extends Throwable> {
037    // See also Apache Commons Lang FailableFunction
038
039    /**
040     * The default converter. Does nothing.
041     */
042    Converter<?, RuntimeException> DEFAULT = s -> s;
043
044    /**
045     * Class name converter. Calls {@link Class#forName(String)}.
046     */
047    Converter<Class<?>, ClassNotFoundException> CLASS = Class::forName;
048
049    /**
050     * File name converter. Calls {@link File#File(String)}.
051     */
052    Converter<File, NullPointerException> FILE = File::new;
053
054    /**
055     * Path converter. Calls {@link Paths#get(java.net.URI)}.
056     */
057    Converter<Path, InvalidPathException> PATH = Paths::get;
058
059    /**
060     * Number converter. Converts to a Double if a decimal point ('.') is in the string or a Long otherwise.
061     */
062    Converter<Number, NumberFormatException> NUMBER = s -> s.indexOf('.') != -1 ? (Number) Double.valueOf(s) : (Number) Long.valueOf(s);
063
064    /**
065     * Converts a class name to an instance of the class. Uses the Class converter to find the class and then call the default constructor.
066     *
067     * @see #CLASS
068     */
069    Converter<Object, ReflectiveOperationException> OBJECT = s -> CLASS.apply(s).getConstructor().newInstance();
070
071    /**
072     * Creates a URL. Calls {@link URL#URL(String)}.
073     */
074    Converter<URL, MalformedURLException> URL = URL::new;
075
076    /**
077     * Converts to a date using the format string Form "EEE MMM dd HH:mm:ss zzz yyyy".
078     */
079    Converter<Date, java.text.ParseException> DATE = s -> new SimpleDateFormat("EEE MMM dd HH:mm:ss zzz yyyy").parse(s);
080
081    /**
082     * Applies the conversion function to the String argument.
083     *
084     * @param string the String to convert
085     * @return the Object from the conversion.
086     * @throws E on error.
087     */
088    T apply(String string) throws E;
089}