    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.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 Exception> {
    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}