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 from <iterator>}</td></tr> 021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <stream>}</td></tr> 022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromFile <path>}</td></tr> 023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromFile <file>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromResource <resource>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code fromResource <base> <resource>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <in>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <reader>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <url>}</td></tr> 029 * <tr><td width="10px"></td><td nowrap="nowrap">{@code from <input>}</td></tr> 030 * </table> 031 * <p> 032 * See {@link Interface} for the corresponding command signature methods. 033 * <p> 034 * <b>DESCRIPTION</b> 035 * <p> 036 * <p>Pseudo-command used to redirect an input source into a command or command chain.</p> 037 * 038 * <p> 039 * <b>Options</b> 040 * <p> 041 * The command supports no options. 042 * <p> 043 * <b>OPERANDS</b> 044 * <p> 045 * The following operands are supported: 046 * <p> 047 * <table> 048 * <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> 049 * <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> 050 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <lines>}</td><td> : </td><td nowrap="nowrap">{@code Iterable<? extends String>}</td><td> </td><td>collection with input lines</td></tr> 051 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <iterator>}</td><td> : </td><td nowrap="nowrap">{@code java.util.Iterator<? extends String>}</td><td> </td><td>iterator returning input lines</td></tr> 052 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <stream>}</td><td> : </td><td nowrap="nowrap">{@code java.util.stream.Stream<? extends String>}</td><td> </td><td>stream of input lines</td></tr> 053 * <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 054 paths are resolved on the basis of the current working directory.</td></tr> 055 * <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 056 string path argument to enable relative path resolving based on the 057 current working directory).</td></tr> 058 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <base>}</td><td> : </td><td nowrap="nowrap">{@code Class<?>}</td><td> </td><td>base class for subsequent {@code resource} operand if relative paths are used.</td></tr> 059 * <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 resource needs 060 to be on the classpath. If the file is in the root directory, the 061 filename should be prefixed with a forward slash. e.g.: 062 {@code "/test-file.txt"}. 063 <p> 064 If the file is in a package, then the package should be specified 065 prefixed with a forward slash, and with each dot "." replaced with a 066 forward slash. e.g.: 067 {@code "/org/company/mypackage/test-file.txt"}. 068 A {@code base} class operand can be provided for relative paths; see 069 {@link java.lang.Class#getResourceAsStream(String)} for details about 070 resource loading.</td></tr> 071 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <in>}</td><td> : </td><td nowrap="nowrap">{@code java.io.InputStream}</td><td> </td><td>the input stream to read from</td></tr> 072 * <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> 073 * <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> 074 * <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> 075 * </table> 076 */ 077public final class From { 078 /** 079 * The "from" command name. 080 */ 081 public static final String NAME = "from"; 082 083 /** 084 * Interface defining all method signatures for the "from" command. 085 * 086 * @param <R> 087 * the generic return type for all command signature methods 088 * to support different implementor types; the methods of a 089 * command factory for instance returns a command instance; 090 * command builders can also implement this interface, but their 091 * methods return the builder itself enabling for chained method 092 * invocation to create joined commands 093 */ 094 public static interface Interface<R> extends CommandInterface<R> { 095 /** 096 * Uses the given string as input for the next command. If the string 097 contains line ending codes (UNIX or DOS independent from the host 098 operating system), the string is split into multiple lines. 099 * 100 * @param string the string to use as input 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 fromString(String string); 107 /** 108 * Uses the given strings as input for the next command. Each string 109 usually represents a single line of the input; however, if any of 110 the strings contains line ending codes (UNIX or DOS independent from 111 the host operating system), it is split into multiple lines. 112 * 113 * @param strings the input lines 114 * @return the generic type {@code <R>} defined by the implementing class; 115 * the command itself returns no value and writes its result to the 116 * standard output; see class level parameter comments for more 117 * details 118 */ 119 R fromStrings(String... strings); 120 /** 121 * Uses the strings in the specified {@code input} iterable as input 122 lines for the next command. Each string usually represents a single 123 line of the input; however, if any of the strings contains line 124 ending codes (UNIX or DOS independent from the host operating 125 system), it is split into multiple lines. 126 * 127 * @param lines collection with input lines 128 * @return the generic type {@code <R>} defined by the implementing class; 129 * the command itself returns no value and writes its result to the 130 * standard output; see class level parameter comments for more 131 * details 132 */ 133 R from(Iterable<? extends String> lines); 134 /** 135 * Uses the strings returned by the specified iterator as input 136 lines for the next command. Each string usually represents a single 137 line of the input; however, if any of the strings contains line 138 ending codes (UNIX or DOS independent from the host operating 139 system), it is split into multiple lines. 140 * 141 * @param iterator iterator returning input lines 142 * @return the generic type {@code <R>} defined by the implementing class; 143 * the command itself returns no value and writes its result to the 144 * standard output; see class level parameter comments for more 145 * details 146 */ 147 R from(java.util.Iterator<? extends String> iterator); 148 /** 149 * Uses the strings returned by the specified stream as input 150 lines for the next command. Each string usually represents a single 151 line of the input; however, if any of the strings contains line 152 ending codes (UNIX or DOS independent from the host operating 153 system), it is split into multiple lines. 154 * 155 * @param stream stream of input lines 156 * @return the generic type {@code <R>} defined by the implementing class; 157 * the command itself returns no value and writes its result to the 158 * standard output; see class level parameter comments for more 159 * details 160 */ 161 R from(java.util.stream.Stream<? extends String> stream); 162 /** 163 * Redirects the contents of the given file into the next command. This 164 is essentially equivalent to the following syntax in a unix command 165 shell: {@code path > ...} 166 * 167 * @param path the file to use as input; wildcards * and ? are supported; relative 168 paths are resolved on the basis of the current working directory. 169 * @return the generic type {@code <R>} defined by the implementing class; 170 * the command itself returns no value and writes its result to the 171 * standard output; see class level parameter comments for more 172 * details 173 */ 174 R fromFile(String path); 175 /** 176 * Redirects the contents of the given file into the next command. This 177 is essentially equivalent to the following syntax in a unix command 178 shell: {@code file > ...} 179 * 180 * @param file the file to use as input; relative paths are not resolved (use the 181 string path argument to enable relative path resolving based on the 182 current working directory). 183 * @return the generic type {@code <R>} defined by the implementing class; 184 * the command itself returns no value and writes its result to the 185 * standard output; see class level parameter comments for more 186 * details 187 */ 188 R fromFile(java.io.File file); 189 /** 190 * Reads from the given resource relative to the classpath and 191 redirects the contents into the next command. The resource is 192 usually a file or URL on the classpath. The resource is read using 193 {@link Class#getResourceAsStream(String)}. 194 * 195 * @param resource a path to the file to redirect to the next command. The resource needs 196 to be on the classpath. If the file is in the root directory, the 197 filename should be prefixed with a forward slash. e.g.: 198 {@code "/test-file.txt"}. 199 <p> 200 If the file is in a package, then the package should be specified 201 prefixed with a forward slash, and with each dot "." replaced with a 202 forward slash. e.g.: 203 {@code "/org/company/mypackage/test-file.txt"}. 204 A {@code base} class operand can be provided for relative paths; see 205 {@link java.lang.Class#getResourceAsStream(String)} for details about 206 resource loading. 207 * @return the generic type {@code <R>} defined by the implementing class; 208 * the command itself returns no value and writes its result to the 209 * standard output; see class level parameter comments for more 210 * details 211 */ 212 R fromResource(String resource); 213 /** 214 * Reads from the given resource relative to the classpath and 215 redirects the contents into the next command. The resource is 216 usually a file or URL on the classpath. The resource is read using 217 {@link Class#getResourceAsStream(String)}. 218 * 219 * @param base base class for subsequent {@code resource} operand if relative paths are used. 220 * @param resource a path to the file to redirect to the next command. The resource needs 221 to be on the classpath. If the file is in the root directory, the 222 filename should be prefixed with a forward slash. e.g.: 223 {@code "/test-file.txt"}. 224 <p> 225 If the file is in a package, then the package should be specified 226 prefixed with a forward slash, and with each dot "." replaced with a 227 forward slash. e.g.: 228 {@code "/org/company/mypackage/test-file.txt"}. 229 A {@code base} class operand can be provided for relative paths; see 230 {@link java.lang.Class#getResourceAsStream(String)} for details about 231 resource loading. 232 * @return the generic type {@code <R>} defined by the implementing class; 233 * the command itself returns no value and writes its result to the 234 * standard output; see class level parameter comments for more 235 * details 236 */ 237 R fromResource(Class<?> base, String resource); 238 /** 239 * Reads from the given input stream and redirects the contents into 240 the next command. 241 * 242 * @param in the input stream to read from 243 * @return the generic type {@code <R>} defined by the implementing class; 244 * the command itself returns no value and writes its result to the 245 * standard output; see class level parameter comments for more 246 * details 247 */ 248 R from(java.io.InputStream in); 249 /** 250 * Uses the given reader and redirects the read input into the next 251 command. 252 * 253 * @param reader the reader used to read the input 254 * @return the generic type {@code <R>} defined by the implementing class; 255 * the command itself returns no value and writes its result to the 256 * standard output; see class level parameter comments for more 257 * details 258 */ 259 R from(java.io.Reader reader); 260 /** 261 * Reads from the given URL and redirects the contents into the next 262 command. 263 * 264 * @param url the URL to read from 265 * @return the generic type {@code <R>} defined by the implementing class; 266 * the command itself returns no value and writes its result to the 267 * standard output; see class level parameter comments for more 268 * details 269 */ 270 R from(java.net.URL url); 271 /** 272 * Reads from the given input object and redirects the contents into 273 the next command. 274 * 275 * @param input the input object to read from 276 * @return the generic type {@code <R>} defined by the implementing class; 277 * the command itself returns no value and writes its result to the 278 * standard output; see class level parameter comments for more 279 * details 280 */ 281 R from(org.unix4j.io.Input input); 282 } 283 284 /** 285 * Singleton {@link FromFactory factory} instance for the "from" command. 286 */ 287 public static final FromFactory Factory = FromFactory.INSTANCE; 288 289 // no instances 290 private From() { 291 super(); 292 } 293}