001package org.unix4j.unix.xargs;
002
003import java.util.Collections;
004import java.util.Iterator;
005
006import org.unix4j.convert.OptionSetConverters.OptionSetConverter;
007import org.unix4j.convert.ValueConverter;
008import org.unix4j.option.DefaultOptionSet;
009import org.unix4j.option.Option;
010import org.unix4j.option.OptionSet;
011
012import org.unix4j.unix.Xargs;
013import org.unix4j.unix.xargs.XargsOption;
014
015/**
016 * Interface implemented by all option sets for the {@link Xargs xargs} command.
017 * It is recommended to use {@link Xargs#Options} to specify a valid 
018 * combination of options.
019 * <p>
020 * The options for the xargs command are: 
021 * <p>
022 * <table>
023 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -z}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --delimiter0}</td><td>&nbsp;</td><td>Input items are terminated by a null character instead of by 
024                        whitespace, and the quotes and backslash are not special (every
025                        character is taken literally). Disables the end of file string,
026                        which is treated like any other argument. Useful when input items 
027                        might contain white space, quote marks, or backslashes. The find 
028                        --print0 option produces input suitable for this mode.
029                        <p>
030                        (This option is ignored if an explicit delimiter operand is specified).</td></tr>
031 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -x}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --exactArgs}</td><td>&nbsp;</td><td>Terminate immediately if {@code maxArgs} is specified but the found
032                        number of variable items is less than {@code maxArgs}.          
033<p>
034                        (This option is ignored if no {@code maxArgs} operand is specified).</td></tr>
035 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --noRunIfEmpty}</td><td>&nbsp;</td><td>If the standard input does not contain any nonblanks, do not run the
036                        command. Normally, the command is run once even if there is no 
037                        input.</td></tr>
038 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --verbose}</td><td>&nbsp;</td><td>Print the command line on the standard error output before executing
039                        it.</td></tr>
040 * </table>
041 * <p>
042 * This interface serves as an alias for the extended interface to simplify the
043 * command signature methods by avoiding generic parameters.
044 */
045public interface XargsOptions extends OptionSet<XargsOption> {
046        /**
047         * Constant for an empty option set.
048         */
049        XargsOptions EMPTY = new XargsOptions() {
050                @Override
051                public Class<XargsOption> optionType() {
052                        return XargsOption.class;
053                }
054                @Override
055                public boolean isSet(XargsOption option) {
056                        return false;
057                }
058                /**
059                 * Returns 0 as this is a set with no active options.
060                 * 
061                 * @return zero
062                 */
063                @Override
064                public int size() {
065                        return 0;
066                }
067                /**
068                 * Returns an immutable empty set.
069                 * 
070                 * @return an immutable empty set.
071                 */
072                @Override
073                public java.util.Set<XargsOption> asSet() {
074                        return Collections.emptySet();
075                }
076                
077                /**
078                 * Returns an iterator returning no elements. 
079                 * 
080                 * @return an immutable iterator with no elements.
081                 */
082                @Override
083                public Iterator<XargsOption> iterator() {
084                        return asSet().iterator();
085                }
086                
087                /**
088                 * Returns true if the {@link Option#acronym() acronym} should be used
089                 * for the specified {@code option} in string representations. 
090                 * <p>
091                 * This method returns always true;
092                 *  
093                 * @param option
094                 *            the option of interest
095                 * @return always true
096                 */
097                @Override
098                public boolean useAcronymFor(XargsOption option) {
099                        return true;
100                }
101        };
102        /**
103         * Default implementation for a modifiable option set.
104         */
105        class Default extends DefaultOptionSet<XargsOption> implements XargsOptions {
106                /**
107                 * Default constructor for an empty option set with no active options.
108                 */
109                public Default() {
110                        super(XargsOption.class);
111                }
112                /**
113                 * Constructor for an option set with a single active option.
114                 * @param option the option to be set
115                 */
116                public Default(XargsOption option) {
117                        super(option);
118                }
119                /**
120                 * Constructor for an option set with the given active options.
121                 * @param options the options to be set
122                 */
123                public Default(XargsOption... options) {
124                        this();
125                        setAll(options);
126                }
127                /**
128                 * Constructor for an option set initialized with the options given by
129                 * another option set.
130                 * 
131                 * @param optionSet set with the options to be active
132                 */
133                public Default(OptionSet<XargsOption> optionSet) {
134                        this();
135                        setAll(optionSet);
136                }
137        }
138        
139        /**
140         * Value converter for {@link XargsOptions} based on an {@link OptionSetConverter}. 
141         */
142        ValueConverter<XargsOptions> CONVERTER = new ValueConverter<XargsOptions>() {
143                private final OptionSetConverter<XargsOption> converter = new OptionSetConverter<XargsOption>(XargsOption.class);
144                @Override
145                public XargsOptions convert(Object value) {
146                        final OptionSet<XargsOption> set = converter.convert(value);
147                        return set == null ? null : new Default(set);
148                }
149        };
150}