001package org.unix4j.command;
002
003import org.unix4j.context.ExecutionContext;
004import org.unix4j.convert.ValueConverter;
005import org.unix4j.variable.VariableContext;
006
007/**
008 * Interface implemented by command arguments. Arguments is usually a container
009 * for argument values of different types as well as for option flags. The
010 * implementing arguments class is command specific, hence the generic {@code A}
011 * parameter specified by the concrete command implementation.
012 * 
013 * @param <A>
014 *            the concrete command specific arguments type
015 */
016public interface Arguments<A extends Arguments<A>> {
017        /**
018         * Returns an arguments object for the given execution context with resolved
019         * variables if necessary and possible. If variables are defined in this
020         * arguments instance, a new arguments instance is created with values
021         * instead of variables for those variables that are defined in the
022         * specified context object. If this arguments instance uses no variables,
023         * {@code this} arguments instance is simply returned.
024         * <p>
025         * If variables are present, they are resolved if such a variable is defined
026         * in the {@link VariableContext} returned by 
027         * {@code context.}{@link ExecutionContext#getVariableContext() getVariableContext()}.
028         * Values are converted if necessary with the {@link ValueConverter}s
029         * returned by 
030         * {@code context.}{@link ExecutionContext#getValueConverterFor(Class)
031         * getValueConverterFor(Class)}.
032         * 
033         * @param context
034         *            the execution context providing access to variables and
035         *            converters
036         * @return an arguments object with resolved variables where possible
037         * @throws NullPointerException
038         *             if context is null
039         * @throws IllegalArgumentException
040         *             if variables are defined but cannot be converted into the
041         *             target type
042         */
043        A getForContext(ExecutionContext context);
044
045        /**
046         * Returns a string representation of the command arguments and options.
047         * 
048         * @return a string representation of the command arguments and options,
049         *         such as "-matchString myString -ignoreCase"
050         */
051        @Override
052        String toString();
053}