org.refcodes.configuration.ext.console.ArgsParserProperties Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of refcodes-configuration-ext-console Show documentation
Show all versions of refcodes-configuration-ext-console Show documentation
Artifact for providing event based extended functionality for the
refcodes-configuration artifact.
// /////////////////////////////////////////////////////////////////////////////
// REFCODES.ORG
// /////////////////////////////////////////////////////////////////////////////
// This code is copyright (c) by Siegfried Steiner, Munich, Germany and licensed
// under the following (see "http://en.wikipedia.org/wiki/Multi-licensing")
// licenses:
// -----------------------------------------------------------------------------
// GNU General Public License, v3.0 ("http://www.gnu.org/licenses/gpl-3.0.html")
// -----------------------------------------------------------------------------
// Apache License, v2.0 ("http://www.apache.org/licenses/LICENSE-2.0")
// -----------------------------------------------------------------------------
// Please contact the copyright holding author(s) of the software artifacts in
// question for licensing issues not being covered by the above listed licenses,
// also regarding commercial licensing models or regarding the compatibility
// with other open source licenses.
// /////////////////////////////////////////////////////////////////////////////
package org.refcodes.configuration.ext.console;
import java.util.List;
import org.refcodes.configuration.Properties;
import org.refcodes.console.AmbiguousArgsException;
import org.refcodes.console.ArgsParser;
import org.refcodes.console.Operand;
import org.refcodes.console.Option;
import org.refcodes.console.ParseArgsException;
import org.refcodes.console.SuperfluousArgsException;
import org.refcodes.console.UnknownArgsException;
/**
* The {@link ArgsParserProperties} represent {@link Properties} generated from
* command line arguments being parsed by a command line syntax as of the
* definition for the {@link ArgsParser}.
*/
public interface ArgsParserProperties extends Properties, ArgsParser {
/**
* Evaluates the command line arguments and sets the identified properties
* in this {@link Properties} instance. Previously identified properties are
* reset upon invocation of this method. When provided, then an
* {@link Operand}'s alias is used as property name, else as fall back, the
* operand's (when being of sub-type {@link Option}) long-option or
* short-option is used. Make sure, to provide an alias to make the
* {@link Properties} work and feel as intended!
*
* {@inheritDoc}
*/
@Override
List> evalArgs( String[] aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException;
/**
* Evaluates the command line arguments and sets the identified properties
* in this {@link Properties} instance. Previously identified properties are
* reset upon invocation of this method. When provided, then an
* {@link Operand}'s alias is used as property name, else as fall back, the
* operand's (when being of sub-type {@link Option}) long-option or
* short-option is used. Make sure, to provide an alias to make the
* {@link Properties} work and feel as intended!
*
* {@inheritDoc}
*/
@Override
List> evalArgs( List aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException;
/**
* Same as {@link #evalArgs(String[])} with the difference that the
* identified properties are inserted below the provided path.
*
* @param aToPath The path below which to insert the identified properties.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return The list of evaluated command line arguments being instances of
* the {@link Operand} interfaces or its sub-types.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
List> evalArgs( String aToPath, List aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException;
/**
* Same as {@link #evalArgs(String[])} with the difference that the
* identified properties are inserted below the provided path.
*
* @param aToPath The path below which to insert the identified properties.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return The list of evaluated command line arguments being instances of
* the {@link Operand} interfaces or its sub-types.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
List> evalArgs( String aToPath, String[] aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException;
/**
* Same as {@link #evalArgs(String[])} with the difference that this class's
* instance being invoked is returned as of the builder pattern.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return This invoked instance as of the builder pattern to chain method
* calls.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
default ArgsParserProperties withEvalArgs( String[] aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException {
evalArgs( aArgs );
return this;
}
/**
* Same as {@link #evalArgs(List)} with the difference that this class's
* instance being invoked is returned as of the builder pattern.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return This invoked instance as of the builder pattern to chain method
* calls.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
default ArgsParserProperties withEvalArgs( List aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException {
evalArgs( aArgs.toArray( new String[aArgs.size()] ) );
return this;
}
/**
* Same as {@link #evalArgs(String[])} with the difference that the
* identified properties are inserted below the provided path and that this
* class's instance being invoked is returned as of the builder pattern.
*
* @param aToPath The path below which to insert the identified properties.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return This invoked instance as of the builder pattern to chain method
* calls.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
default ArgsParserProperties withEvalArgs( String aToPath, List aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException {
evalArgs( aArgs.toArray( new String[aArgs.size()] ) );
return this;
}
/**
* Same as {@link #evalArgs(String[])} with the difference that the
* identified properties are inserted below the provided path and that this
* class's instance being invoked is returned as of the builder pattern.
*
* @param aToPath The path below which to insert the identified properties.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return This invoked instance as of the builder pattern to chain method
* calls.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
default ArgsParserProperties withEvalArgs( String aToPath, String[] aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException {
evalArgs( aToPath, aArgs );
return this;
}
}