001package org.unix4j.unix.ls;
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.Ls;
013import org.unix4j.unix.ls.LsOption;
014
015/**
016 * Interface implemented by all option sets for the {@link Ls ls} command.
017 * It is recommended to use {@link Ls#Options} to specify a valid 
018 * combination of options.
019 * <p>
020 * The options for the ls command are: 
021 * <p>
022 * <table>
023 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -a}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --allFiles}</td><td>&nbsp;</td><td>Lists all files in the given directory, including hidden files
024                        (those whose names start with \".\" in Unix). By default, these 
025                        files are excluded from the list.</td></tr>
026 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -h}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --humanReadable}</td><td>&nbsp;</td><td>Print sizes in human readable format. (e.g., 1K, 234M, 2G, etc.)</td></tr>
027 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --longFormat}</td><td>&nbsp;</td><td>Long format, displaying file types, permissions, number of hard 
028                        links, owner, group, size, date, and filename.</td></tr>
029 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -R}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --recurseSubdirs}</td><td>&nbsp;</td><td>Recursively lists subdirectories encountered.</td></tr>
030 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --reverseOrder}</td><td>&nbsp;</td><td>Reverses the order of the sort to get reverse collating sequence or 
031                        oldest first.</td></tr>
032 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --timeSorted}</td><td>&nbsp;</td><td>Sorts with the primary key being time modified (most recently 
033                        modified first) and the secondary key being filename in the 
034                        collating sequence.</td></tr>
035 * </table>
036 * <p>
037 * This interface serves as an alias for the extended interface to simplify the
038 * command signature methods by avoiding generic parameters.
039 */
040public interface LsOptions extends OptionSet<LsOption> {
041        /**
042         * Constant for an empty option set.
043         */
044        LsOptions EMPTY = new LsOptions() {
045                @Override
046                public Class<LsOption> optionType() {
047                        return LsOption.class;
048                }
049                @Override
050                public boolean isSet(LsOption option) {
051                        return false;
052                }
053                /**
054                 * Returns 0 as this is a set with no active options.
055                 * 
056                 * @return zero
057                 */
058                @Override
059                public int size() {
060                        return 0;
061                }
062                /**
063                 * Returns an immutable empty set.
064                 * 
065                 * @return an immutable empty set.
066                 */
067                @Override
068                public java.util.Set<LsOption> asSet() {
069                        return Collections.emptySet();
070                }
071                
072                /**
073                 * Returns an iterator returning no elements. 
074                 * 
075                 * @return an immutable iterator with no elements.
076                 */
077                @Override
078                public Iterator<LsOption> iterator() {
079                        return asSet().iterator();
080                }
081                
082                /**
083                 * Returns true if the {@link Option#acronym() acronym} should be used
084                 * for the specified {@code option} in string representations. 
085                 * <p>
086                 * This method returns always true;
087                 *  
088                 * @param option
089                 *            the option of interest
090                 * @return always true
091                 */
092                @Override
093                public boolean useAcronymFor(LsOption option) {
094                        return true;
095                }
096        };
097        /**
098         * Default implementation for a modifiable option set.
099         */
100        class Default extends DefaultOptionSet<LsOption> implements LsOptions {
101                /**
102                 * Default constructor for an empty option set with no active options.
103                 */
104                public Default() {
105                        super(LsOption.class);
106                }
107                /**
108                 * Constructor for an option set with a single active option.
109                 * @param option the option to be set
110                 */
111                public Default(LsOption option) {
112                        super(option);
113                }
114                /**
115                 * Constructor for an option set with the given active options.
116                 * @param options the options to be set
117                 */
118                public Default(LsOption... options) {
119                        this();
120                        setAll(options);
121                }
122                /**
123                 * Constructor for an option set initialized with the options given by
124                 * another option set.
125                 * 
126                 * @param optionSet set with the options to be active
127                 */
128                public Default(OptionSet<LsOption> optionSet) {
129                        this();
130                        setAll(optionSet);
131                }
132        }
133        
134        /**
135         * Value converter for {@link LsOptions} based on an {@link OptionSetConverter}. 
136         */
137        ValueConverter<LsOptions> CONVERTER = new ValueConverter<LsOptions>() {
138                private final OptionSetConverter<LsOption> converter = new OptionSetConverter<LsOption>(LsOption.class);
139                @Override
140                public LsOptions convert(Object value) {
141                        final OptionSet<LsOption> set = converter.convert(value);
142                        return set == null ? null : new Default(set);
143                }
144        };
145}