001package org.unix4j.unix;
002
003import org.unix4j.command.CommandInterface;
004
005import org.unix4j.unix.cd.CdFactory;
006
007/**
008 * Non-instantiable module with inner types making up the <b>cd</b> command.
009 * <p>
010 * <b>NAME</b>
011 * <p>
012 * cd - change the working directory 
013 * <p>
014 * <b>SYNOPSIS</b>
015 * <p>
016 * <table>
017 * <tr><td width="10px"></td><td nowrap="nowrap">{@code cd}</td></tr>
018 * <tr><td width="10px"></td><td nowrap="nowrap">{@code cd <file>}</td></tr>
019 * <tr><td width="10px"></td><td nowrap="nowrap">{@code cd <path>}</td></tr>
020 * </table>
021 * <p>
022 * See {@link Interface} for the corresponding command signature methods.
023 * <p>
024 * <b>DESCRIPTION</b>
025 * <p>
026 * <p>The cd utility changes the working directory of the current command execution. If no directory operand is given, the cd utility changes to the user home directory as defined by the execution context (usually the directory specified by the {@code "user.home"} system property).  If the cd argument is a {@link java.io.File File} and it is a directory, the current working directory is changed to the given file (relative paths are not resolved with the current working directory). If a string argument is passed to the cd utility, it is treated as a file argument and relative paths are resolved on the basis of the (old) current working directory. Wildcards are possible if the first matching file represents a directory. If the specified file or path argument does not represent a valid directory, an exception is thrown.</p><p>See also:<ul>        <li>{@link java.lang.System#getProperties()}</li></ul></p>
027 * 
028 * <p>
029 * <b>Options</b>
030 * <p>
031 * The command supports no options.
032 * <p>
033 * <b>OPERANDS</b>
034 * <p>
035 * The following operands are supported:
036 * <p>
037 * <table>
038 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <file>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code java.io.File}</td><td>&nbsp;</td><td>the file to use as input; relative paths are not resolved (use the
039                        string path argument to enable relative path resolving based on the
040                        current working directory).</td></tr>
041 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <path>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>the directory to become the new current working directory; 
042                        wildcards * and ? are supported; relative paths are resolved on the
043            basis of the current working directory.</td></tr>
044 * </table>
045 */
046public final class Cd {
047        /**
048         * The "cd" command name.
049         */
050        public static final String NAME = "cd";
051
052        /**
053         * Interface defining all method signatures for the "cd" command.
054         * 
055         * @param <R>
056         *            the generic return type for all command signature methods
057         *            to support different implementor types; the methods of a 
058         *            command factory for instance returns a command instance; 
059         *            command builders can also implement this interface, but their
060         *            methods return the builder itself enabling for chained method
061         *            invocation to create joined commands
062         */
063        public static interface Interface<R> extends CommandInterface<R> {
064                /**
065                 * Changes the current directory to the user home directory as defined 
066                        by the execution context (usually the directory specified by the 
067                        {@code "user.home"} system property).
068                 *
069                 * @return the generic type {@code <R>} defined by the implementing class;
070                 *         the command itself returns no value and writes its result to the
071                 *         standard output; see class level parameter comments for more 
072                 *         details
073                 */
074                R cd();
075                /**
076                 * The current working directory is changed to the given file. If the 
077                        specified file argument does not represent a valid directory, an 
078                        exception is thrown. Note that relative paths are not resolved with 
079                        the (old) current working directory. Use the String path to enable 
080                        relative path resolving and wildcards.
081                 *
082                 * @param file the file to use as input; relative paths are not resolved (use the
083                        string path argument to enable relative path resolving based on the
084                        current working directory).
085                 * @return the generic type {@code <R>} defined by the implementing class;
086                 *         the command itself returns no value and writes its result to the
087                 *         standard output; see class level parameter comments for more 
088                 *         details
089                 */
090                R cd(java.io.File file);
091                /**
092                 * The current working directory is changed to the given file. Relative
093                        paths are resolved on the basis of the (old) current working 
094                        directory. Wildcards are possible if the first matching file 
095                        represents a directory. If the first file specified by the given 
096                        path argument is not a valid directory, an exception is thrown.
097                 *
098                 * @param path the directory to become the new current working directory; 
099                        wildcards * and ? are supported; relative paths are resolved on the
100            basis of the current working directory.
101                 * @return the generic type {@code <R>} defined by the implementing class;
102                 *         the command itself returns no value and writes its result to the
103                 *         standard output; see class level parameter comments for more 
104                 *         details
105                 */
106                R cd(String path);
107        }
108
109        /**
110         * Singleton {@link CdFactory factory} instance for the "cd" command.
111         */
112        public static final CdFactory Factory = CdFactory.INSTANCE;
113
114        // no instances
115        private Cd() {
116                super();
117        }
118}