001package org.unix4j.unix; 002 003import org.unix4j.command.CommandInterface; 004 005import org.unix4j.unix.from.FromFactory; 006 007/** 008 * Non-instantiable module with inner types making up the <b>from</b> command. 009 * <p> 010 * <b>NAME</b> 011 * <p> 012 * from - a pseudo command used to redirect the standard input 013 * <p> 014 * <b>SYNOPSIS</b> 015 * <p> 016 * <table> 017 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromString <string>}</td></tr> 018 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromStrings <strings>}</td></tr> 019 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <lines>}</td></tr> 020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromFile <path>}</td></tr> 021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromFile <file>}</td></tr> 022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromResource <resource>}</td></tr> 023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <stream>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <reader>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <url>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <input>}</td></tr> 027 * </table> 028 * <p> 029 * See {@link Interface} for the corresponding command signature methods. 030 * <p> 031 * <b>DESCRIPTION</b> 032 * <p> 033 * <p>Pseudo-command used to redirect an input source into a command or command chain.</p> 034 * 035 * <p> 036 * <b>Options</b> 037 * <p> 038 * The command supports no options. 039 * <p> 040 * <b>OPERANDS</b> 041 * <p> 042 * The following operands are supported: 043 * <p> 044 * <table> 045 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <string>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>the string to use as input</td></tr> 046 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <strings>}</td><td> : </td><td nowrap="nowrap">{@code String...}</td><td> </td><td>the input lines</td></tr> 047 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <lines>}</td><td> : </td><td nowrap="nowrap">{@code java.util.Collection<? extends String>}</td><td> </td><td>collection with input lines</td></tr> 048 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <path>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>the file to use as input; wildcards * and ? are supported; relative 049 paths are resolved on the basis of the current working directory.</td></tr> 050 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <file>}</td><td> : </td><td nowrap="nowrap">{@code java.io.File}</td><td> </td><td>the file to use as input; relative paths are not resolved (use the 051 string path argument to enable relative path resolving based on the 052 current working directory).</td></tr> 053 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <resource>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>a path to the file to redirect to the next command. The will need 054 to be on the classpath. If the file is in the root directory, the 055 filename should be prefixed with a forward slash. e.g.: 056 {@code "/test-file.txt"} 057 <p> 058 If the file is in a package, then the package should be specified 059 prefixed with a forward slash, and with each dot "." replaced with a 060 forward slash. e.g.: 061 {@code "/org/company/mypackage/test-file.txt"}</td></tr> 062 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <stream>}</td><td> : </td><td nowrap="nowrap">{@code java.io.InputStream}</td><td> </td><td>the input stream to read from</td></tr> 063 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <reader>}</td><td> : </td><td nowrap="nowrap">{@code java.io.Reader}</td><td> </td><td>the reader used to read the input</td></tr> 064 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <url>}</td><td> : </td><td nowrap="nowrap">{@code java.net.URL}</td><td> </td><td>the URL to read from</td></tr> 065 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <input>}</td><td> : </td><td nowrap="nowrap">{@code org.unix4j.io.Input}</td><td> </td><td>the input object to read from</td></tr> 066 * </table> 067 */ 068public final class From { 069 /** 070 * The "from" command name. 071 */ 072 public static final String NAME = "from"; 073 074 /** 075 * Interface defining all method signatures for the "from" command. 076 * 077 * @param <R> 078 * the generic return type for all command signature methods 079 * to support different implementor types; the methods of a 080 * command factory for instance returns a command instance; 081 * command builders can also implement this interface, but their 082 * methods return the builder itself enabling for chained method 083 * invocation to create joined commands 084 */ 085 public static interface Interface<R> extends CommandInterface<R> { 086 /** 087 * Uses the given string as input for the next command. If the string 088 contains line ending codes (UNIX or DOS independent from the host 089 operating system), the string is split into multiple lines. 090 * 091 * @param string the string to use as input 092 * @return the generic type {@code <R>} defined by the implementing class; 093 * the command itself returns no value and writes its result to the 094 * standard output; see class level parameter comments for more 095 * details 096 */ 097 R fromString(String string); 098 /** 099 * Uses the given strings as input for the next command. Each string 100 usually represents a single line of the input; however, if any of 101 the strings contains line ending codes (UNIX or DOS independent from 102 the host operating system), it is split into multiple lines. 103 * 104 * @param strings the input lines 105 * @return the generic type {@code <R>} defined by the implementing class; 106 * the command itself returns no value and writes its result to the 107 * standard output; see class level parameter comments for more 108 * details 109 */ 110 R fromStrings(String... strings); 111 /** 112 * Uses the strings in the specified {@code input} collection as input 113 lines for the next command. Each string usually represents a single 114 line of the input; however, if any of the strings contains line 115 ending codes (UNIX or DOS independent from the host operating 116 system), it is split into multiple lines. 117 * 118 * @param lines collection with input lines 119 * @return the generic type {@code <R>} defined by the implementing class; 120 * the command itself returns no value and writes its result to the 121 * standard output; see class level parameter comments for more 122 * details 123 */ 124 R from(java.util.Collection<? extends String> lines); 125 /** 126 * Redirects the contents of the given file into the next command. This 127 is essentially equivalent to the following syntax in a unix command 128 shell: {@code path > ...} 129 * 130 * @param path the file to use as input; wildcards * and ? are supported; relative 131 paths are resolved on the basis of the current working directory. 132 * @return the generic type {@code <R>} defined by the implementing class; 133 * the command itself returns no value and writes its result to the 134 * standard output; see class level parameter comments for more 135 * details 136 */ 137 R fromFile(String path); 138 /** 139 * Redirects the contents of the given file into the next command. This 140 is essentially equivalent to the following syntax in a unix command 141 shell: {@code file > ...} 142 * 143 * @param file the file to use as input; relative paths are not resolved (use the 144 string path argument to enable relative path resolving based on the 145 current working directory). 146 * @return the generic type {@code <R>} defined by the implementing class; 147 * the command itself returns no value and writes its result to the 148 * standard output; see class level parameter comments for more 149 * details 150 */ 151 R fromFile(java.io.File file); 152 /** 153 * Reads from the given resource relative to the classpath and 154 redirects the contents into the next command. The resource is 155 usually a file or URL on the classpath. The resource is read using 156 {@link Class#getResourceAsStream(String)}. 157 * 158 * @param resource a path to the file to redirect to the next command. The will need 159 to be on the classpath. If the file is in the root directory, the 160 filename should be prefixed with a forward slash. e.g.: 161 {@code "/test-file.txt"} 162 <p> 163 If the file is in a package, then the package should be specified 164 prefixed with a forward slash, and with each dot "." replaced with a 165 forward slash. e.g.: 166 {@code "/org/company/mypackage/test-file.txt"} 167 * @return the generic type {@code <R>} defined by the implementing class; 168 * the command itself returns no value and writes its result to the 169 * standard output; see class level parameter comments for more 170 * details 171 */ 172 R fromResource(String resource); 173 /** 174 * Reads from the given input stream and redirects the contents into 175 the next command. 176 * 177 * @param stream the input stream to read from 178 * @return the generic type {@code <R>} defined by the implementing class; 179 * the command itself returns no value and writes its result to the 180 * standard output; see class level parameter comments for more 181 * details 182 */ 183 R from(java.io.InputStream stream); 184 /** 185 * Uses the given reader and redirects the read input into the next 186 command. 187 * 188 * @param reader the reader used to read the input 189 * @return the generic type {@code <R>} defined by the implementing class; 190 * the command itself returns no value and writes its result to the 191 * standard output; see class level parameter comments for more 192 * details 193 */ 194 R from(java.io.Reader reader); 195 /** 196 * Reads from the given URL and redirects the contents into the next 197 command. 198 * 199 * @param url the URL to read from 200 * @return the generic type {@code <R>} defined by the implementing class; 201 * the command itself returns no value and writes its result to the 202 * standard output; see class level parameter comments for more 203 * details 204 */ 205 R from(java.net.URL url); 206 /** 207 * Reads from the given input object and redirects the contents into 208 the next command. 209 * 210 * @param input the input object to read from 211 * @return the generic type {@code <R>} defined by the implementing class; 212 * the command itself returns no value and writes its result to the 213 * standard output; see class level parameter comments for more 214 * details 215 */ 216 R from(org.unix4j.io.Input input); 217 } 218 219 /** 220 * Singleton {@link FromFactory factory} instance for the "from" command. 221 */ 222 public static final FromFactory Factory = FromFactory.INSTANCE; 223 224 // no instances 225 private From() { 226 super(); 227 } 228}