001package org.unix4j.unix; 002 003import org.unix4j.command.CommandInterface; 004 005import org.unix4j.unix.xargs.XargsFactory; 006import org.unix4j.unix.xargs.XargsOption; 007import org.unix4j.unix.xargs.XargsOptions; 008import org.unix4j.unix.xargs.XargsOptionSets; 009 010/** 011 * Non-instantiable module with inner types making up the <b>xargs</b> command. 012 * <p> 013 * <b>NAME</b> 014 * <p> 015 * xargs - build and execute command lines from standard input 016 * <p> 017 * <b>SYNOPSIS</b> 018 * <p> 019 * <table> 020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs}</td></tr> 021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <args>}</td></tr> 022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <delimiter>}</td></tr> 023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <maxLines>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <maxArgs>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <maxLines> <maxArgs>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <delimiter> <maxLines>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <delimiter> <maxArgs>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <delimiter> <maxLines> <maxArgs>}</td></tr> 029 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs <delimiter> <eof> <maxLines> <maxArgs>}</td></tr> 030 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt]}</td></tr> 031 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <delimiter>}</td></tr> 032 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <maxLines>}</td></tr> 033 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <maxArgs>}</td></tr> 034 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <maxLines> <maxArgs>}</td></tr> 035 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <delimiter> <maxLines>}</td></tr> 036 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <delimiter> <maxArgs>}</td></tr> 037 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <delimiter> <maxLines> <maxArgs>}</td></tr> 038 * <tr><td width="10px"></td><td nowrap="nowrap">{@code xargs [-zxrt] <delimiter> <eof> <maxLines> <maxArgs>}</td></tr> 039 * </table> 040 * <p> 041 * See {@link Interface} for the corresponding command signature methods. 042 * <p> 043 * <b>DESCRIPTION</b> 044 * <p> 045 * <p>The xargs utility reads items from the standard input, delimited by blanks (which can be protected with double or single quotes or a backslash) or newlines, and executes the command (default is /bin/echo) one or more times withany initial arguments followed by items read from standard input. Blank lines onthe standard input are ignored.</p><p>Because Unix filenames can contain blanks and newlines, this default behaviour is often problematic; filenames containing blanks and/or newlines are incorrectly processed by xargs. In these situations it is better to use the --null option, which prevents such problems. When using this option you will need to ensure that the program which produces the input for xargs also uses a null character as a separator. If that program is find for example, the --print0 option does this for you.If any invocation of the command exits with a status of 255, xargs will stop immediately without reading any further input. An error messageis issued on stderr when this happens.</p> 046 * 047 * <p> 048 * <b>Options</b> 049 * <p> 050 * The following options are supported: 051 * <p> 052 * <table> 053 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -z}</td><td> </td><td nowrap="nowrap">{@code --delimiter0}</td><td> </td><td>Input items are terminated by a null character instead of by 054 whitespace, and the quotes and backslash are not special (every 055 character is taken literally). Disables the end of file string, 056 which is treated like any other argument. Useful when input items 057 might contain white space, quote marks, or backslashes. The find 058 --print0 option produces input suitable for this mode. 059 <p> 060 (This option is ignored if an explicit delimiter operand is specified).</td></tr> 061 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -x}</td><td> </td><td nowrap="nowrap">{@code --exactArgs}</td><td> </td><td>Terminate immediately if {@code maxArgs} is specified but the found 062 number of variable items is less than {@code maxArgs}. 063<p> 064 (This option is ignored if no {@code maxArgs} operand is specified).</td></tr> 065 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td> </td><td nowrap="nowrap">{@code --noRunIfEmpty}</td><td> </td><td>If the standard input does not contain any nonblanks, do not run the 066 command. Normally, the command is run once even if there is no 067 input.</td></tr> 068 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td> </td><td nowrap="nowrap">{@code --verbose}</td><td> </td><td>Print the command line on the standard error output before executing 069 it.</td></tr> 070 * </table> 071 * <p> 072 * <b>OPERANDS</b> 073 * <p> 074 * The following operands are supported: 075 * <p> 076 * <table> 077 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <delimiter>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>Input items are terminated by the specified characters.</td></tr> 078 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <eof>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>If the end of file string occurs as a line of input, the rest of the 079 input is ignored.</td></tr> 080 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <maxLines>}</td><td> : </td><td nowrap="nowrap">{@code long}</td><td> </td><td>Use at most maxLines nonblank input lines per command invocation.</td></tr> 081 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <maxArgs>}</td><td> : </td><td nowrap="nowrap">{@code int}</td><td> </td><td>Use at most maxArgs arguments per command invocation.</td></tr> 082 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <args>}</td><td> : </td><td nowrap="nowrap">{@code String...}</td><td> </td><td>String arguments defining the options and operands for the command. 083 Options can be specified by acronym (with a leading dash "-") or by 084 long name (with two leading dashes "--"). Operands other than the 085 default "--maxArgs" operand have to be prefixed with the operand 086 name (e.g. "--maxLines" for a subsequent line count operand value).</td></tr> 087 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td> : </td><td nowrap="nowrap">{@code XargsOptions}</td><td> </td><td>The options defining command behavior.</td></tr> 088 * </table> 089 */ 090public final class Xargs { 091 /** 092 * The "xargs" command name. 093 */ 094 public static final String NAME = "xargs"; 095 096 /** 097 * Interface defining all method signatures for the "xargs" command. 098 * 099 * @param <R> 100 * the generic return type for all command signature methods 101 * to support different implementor types; the methods of a 102 * command factory for instance returns a command instance; 103 * command builders can also implement this interface, but their 104 * methods return the builder itself enabling for chained method 105 * invocation to create joined commands 106 */ 107 public static interface Interface<R> extends CommandInterface<R> { 108 /** 109 * Reads items from the standard input, delimited by blanks (which can 110 be protected with double or single quotes or a backslash) or 111 newlines, and provides variables for the items read from the 112 standard input. The command following after xargs is executed once 113 for every input line; the item variables are usually passed to the 114 invoked command as arguments. 115 * 116 * @return the generic type {@code <R>} defined by the implementing class; 117 * the command itself returns no value and writes its result to the 118 * standard output; see class level parameter comments for more 119 * details 120 */ 121 R xargs(); 122 /** 123 * Reads items from the standard input, delimited by blanks and 124 newlines or a specified delimiter, and provides variables for the 125 items read from the standard input. The command following after 126 xargs is executed once for every input line (or for multiple lines 127 depending on the input options); the item variables are usually 128 passed to the invoked command as arguments. 129 <p> 130 Options can be specified by acronym (with a leading dash "-") or by 131 long name (with two leading dashes "--"). Operands other than the 132 default "--maxArgs" operand have to be prefixed with the operand 133 name. 134 * 135 * @param args String arguments defining the options and operands for the command. 136 Options can be specified by acronym (with a leading dash "-") or by 137 long name (with two leading dashes "--"). Operands other than the 138 default "--maxArgs" operand have to be prefixed with the operand 139 name (e.g. "--maxLines" for a subsequent line count operand value). 140 * @return the generic type {@code <R>} defined by the implementing class; 141 * the command itself returns no value and writes its result to the 142 * standard output; see class level parameter comments for more 143 * details 144 */ 145 R xargs(String... args); 146 /** 147 * Reads items from the standard input using the specified delimiter to 148 separate items, and provides variables for the items read from the 149 standard input. The command following after xargs is executed once 150 for every input line; the item variables are usually passed to the 151 invoked command as arguments. 152 * 153 * @param delimiter Input items are terminated by the specified characters. 154 * @return the generic type {@code <R>} defined by the implementing class; 155 * the command itself returns no value and writes its result to the 156 * standard output; see class level parameter comments for more 157 * details 158 */ 159 R xargs(String delimiter); 160 /** 161 * Reads items from the standard input, delimited by blanks (which can 162 be protected with double or single quotes or a backslash) or 163 newlines, and provides variables for the items read from the 164 standard input. The command following after xargs is executed once 165 for every {@code maxLines} nonblank input lines (or possibly fewer 166 for the last invocation with the remaining lines at the end of the 167 file). The item variables are usually passed to the invoked command 168 as arguments. 169 * 170 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 171 * @return the generic type {@code <R>} defined by the implementing class; 172 * the command itself returns no value and writes its result to the 173 * standard output; see class level parameter comments for more 174 * details 175 */ 176 R xargs(long maxLines); 177 /** 178 * Reads items from the standard input, delimited by blanks (which can 179 be protected with double or single quotes or a backslash) or 180 newlines, and provides variables for the items read from the 181 standard input. The command following after xargs is executed once 182 for every {@code maxArgs} items read from the standard input (or 183 possibly fewer for the last invocation with the remaining items at 184 the end of the file). The item variables are usually passed to the 185 invoked command as arguments. 186 * 187 * @param maxArgs Use at most maxArgs arguments per command invocation. 188 * @return the generic type {@code <R>} defined by the implementing class; 189 * the command itself returns no value and writes its result to the 190 * standard output; see class level parameter comments for more 191 * details 192 */ 193 R xargs(int maxArgs); 194 /** 195 * Reads items from the standard input, delimited by blanks (which can 196 be protected with double or single quotes or a backslash) or 197 newlines, and provides variables for the items read from the 198 standard input. The command following after xargs is executed once 199 for every {@code maxLines} nonblank input lines or {@code maxArgs} 200 items (whichever occurs first). Fewer lines or items may be used for 201 the last invocation with the remaining lines at the end of the file. 202 The item variables are usually passed to the invoked command as 203 arguments. 204 * 205 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 206 * @param maxArgs Use at most maxArgs arguments per command invocation. 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 xargs(long maxLines, int maxArgs); 213 /** 214 * Reads items from the standard input using the specified delimiter to 215 separate items, and provides variables for the items read from the 216 standard input. The command following after xargs is executed once 217 for every {@code maxLines} nonblank input lines (or possibly fewer 218 for the last invocation with the remaining lines at the end of the 219 file). The item variables are usually passed to the invoked command 220 as arguments. 221 * 222 * @param delimiter Input items are terminated by the specified characters. 223 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 224 * @return the generic type {@code <R>} defined by the implementing class; 225 * the command itself returns no value and writes its result to the 226 * standard output; see class level parameter comments for more 227 * details 228 */ 229 R xargs(String delimiter, long maxLines); 230 /** 231 * Reads items from the standard input using the specified delimiter to 232 separate items, and provides variables for the items read from the 233 standard input. The command following after xargs is executed once 234 for every {@code maxArgs} items read from the standard input (or 235 possibly fewer for the last invocation with the remaining items at 236 the end of the file). The item variables are usually passed to the 237 invoked command as arguments. 238 * 239 * @param delimiter Input items are terminated by the specified characters. 240 * @param maxArgs Use at most maxArgs arguments per command invocation. 241 * @return the generic type {@code <R>} defined by the implementing class; 242 * the command itself returns no value and writes its result to the 243 * standard output; see class level parameter comments for more 244 * details 245 */ 246 R xargs(String delimiter, int maxArgs); 247 /** 248 * Reads items from the standard input using the specified delimiter to 249 separate items, and provides variables for the items read from the 250 standard input. The command following after xargs is executed once 251 for every {@code maxLines} nonblank input lines or {@code maxArgs} 252 items (whichever occurs first). Fewer lines or items may be used for 253 the last invocation with the remaining lines at the end of the file. 254 The item variables are usually passed to the invoked command as 255 arguments. 256 * 257 * @param delimiter Input items are terminated by the specified characters. 258 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 259 * @param maxArgs Use at most maxArgs arguments per command invocation. 260 * @return the generic type {@code <R>} defined by the implementing class; 261 * the command itself returns no value and writes its result to the 262 * standard output; see class level parameter comments for more 263 * details 264 */ 265 R xargs(String delimiter, long maxLines, int maxArgs); 266 /** 267 * Reads items from the standard input using the specified delimiter to 268 separate items, and provides variables for the items read from the 269 standard input. If the {@code eof} string occurs as a line of input, 270 the rest of the input is ignored. The command following after xargs 271 is executed once for every {@code maxLines} nonblank input lines or 272 {@code maxArgs} items (whichever occurs first). Fewer lines or items 273 may be used for the last invocation with the remaining lines at the 274 end of the file. The item variables are usually passed to the 275 invoked command as arguments. 276 * 277 * @param delimiter Input items are terminated by the specified characters. 278 * @param eof If the end of file string occurs as a line of input, the rest of the 279 input is ignored. 280 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 281 * @param maxArgs Use at most maxArgs arguments per command invocation. 282 * @return the generic type {@code <R>} defined by the implementing class; 283 * the command itself returns no value and writes its result to the 284 * standard output; see class level parameter comments for more 285 * details 286 */ 287 R xargs(String delimiter, String eof, long maxLines, int maxArgs); 288 /** 289 * Reads items from the standard input, delimited by blanks (which can 290 be protected with double or single quotes or a backslash) or 291 newlines, and provides variables for the items read from the 292 standard input. The command following after xargs is executed once 293 for every input line; the item variables are usually passed to the 294 invoked command as arguments. 295 * 296 * @param options The options defining command behavior. 297 * @return the generic type {@code <R>} defined by the implementing class; 298 * the command itself returns no value and writes its result to the 299 * standard output; see class level parameter comments for more 300 * details 301 */ 302 R xargs(XargsOptions options); 303 /** 304 * Reads items from the standard input using the specified delimiter to 305 separate items, and provides variables for the items read from the 306 standard input. The command following after xargs is executed once 307 for every input line; the item variables are usually passed to the 308 invoked command as arguments. 309 * 310 * @param options The options defining command behavior. 311 * @param delimiter Input items are terminated by the specified characters. 312 * @return the generic type {@code <R>} defined by the implementing class; 313 * the command itself returns no value and writes its result to the 314 * standard output; see class level parameter comments for more 315 * details 316 */ 317 R xargs(XargsOptions options, String delimiter); 318 /** 319 * Reads items from the standard input, delimited by blanks (which can 320 be protected with double or single quotes or a backslash) or 321 newlines, and provides variables for the items read from the 322 standard input. The command following after xargs is executed once 323 for every {@code maxLines} nonblank input lines (or possibly fewer 324 for the last invocation with the remaining lines at the end of the 325 file). The item variables are usually passed to the invoked command 326 as arguments. 327 * 328 * @param options The options defining command behavior. 329 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 330 * @return the generic type {@code <R>} defined by the implementing class; 331 * the command itself returns no value and writes its result to the 332 * standard output; see class level parameter comments for more 333 * details 334 */ 335 R xargs(XargsOptions options, long maxLines); 336 /** 337 * Reads items from the standard input, delimited by blanks (which can 338 be protected with double or single quotes or a backslash) or 339 newlines, and provides variables for the items read from the 340 standard input. The command following after xargs is executed once 341 for every {@code maxArgs} items read from the standard input (or 342 possibly fewer for the last invocation with the remaining items at 343 the end of the file). The item variables are usually passed to the 344 invoked command as arguments. 345 * 346 * @param options The options defining command behavior. 347 * @param maxArgs Use at most maxArgs arguments per command invocation. 348 * @return the generic type {@code <R>} defined by the implementing class; 349 * the command itself returns no value and writes its result to the 350 * standard output; see class level parameter comments for more 351 * details 352 */ 353 R xargs(XargsOptions options, int maxArgs); 354 /** 355 * Reads items from the standard input, delimited by blanks (which can 356 be protected with double or single quotes or a backslash) or 357 newlines, and provides variables for the items read from the 358 standard input. The command following after xargs is executed once 359 for every {@code maxLines} nonblank input lines or {@code maxArgs} 360 items (whichever occurs first). Fewer lines or items may be used for 361 the last invocation with the remaining lines at the end of the file. 362 The item variables are usually passed to the invoked command as 363 arguments. 364 * 365 * @param options The options defining command behavior. 366 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 367 * @param maxArgs Use at most maxArgs arguments per command invocation. 368 * @return the generic type {@code <R>} defined by the implementing class; 369 * the command itself returns no value and writes its result to the 370 * standard output; see class level parameter comments for more 371 * details 372 */ 373 R xargs(XargsOptions options, long maxLines, int maxArgs); 374 /** 375 * Reads items from the standard input using the specified delimiter to 376 separate items, and provides variables for the items read from the 377 standard input. The command following after xargs is executed once 378 for every {@code maxLines} nonblank input lines (or possibly fewer 379 for the last invocation with the remaining lines at the end of the 380 file). The item variables are usually passed to the invoked command 381 as arguments. 382 * 383 * @param options The options defining command behavior. 384 * @param delimiter Input items are terminated by the specified characters. 385 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 386 * @return the generic type {@code <R>} defined by the implementing class; 387 * the command itself returns no value and writes its result to the 388 * standard output; see class level parameter comments for more 389 * details 390 */ 391 R xargs(XargsOptions options, String delimiter, long maxLines); 392 /** 393 * Reads items from the standard input using the specified delimiter to 394 separate items, and provides variables for the items read from the 395 standard input. The command following after xargs is executed once 396 for every {@code maxArgs} items read from the standard input (or 397 possibly fewer for the last invocation with the remaining items at 398 the end of the file). The item variables are usually passed to the 399 invoked command as arguments. 400 * 401 * @param options The options defining command behavior. 402 * @param delimiter Input items are terminated by the specified characters. 403 * @param maxArgs Use at most maxArgs arguments per command invocation. 404 * @return the generic type {@code <R>} defined by the implementing class; 405 * the command itself returns no value and writes its result to the 406 * standard output; see class level parameter comments for more 407 * details 408 */ 409 R xargs(XargsOptions options, String delimiter, int maxArgs); 410 /** 411 * Reads items from the standard input using the specified delimiter to 412 separate items, and provides variables for the items read from the 413 standard input. The command following after xargs is executed once 414 for every {@code maxLines} nonblank input lines or {@code maxArgs} 415 items (whichever occurs first). Fewer lines or items may be used for 416 the last invocation with the remaining lines at the end of the file. 417 The item variables are usually passed to the invoked command as 418 arguments. 419 * 420 * @param options The options defining command behavior. 421 * @param delimiter Input items are terminated by the specified characters. 422 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 423 * @param maxArgs Use at most maxArgs arguments per command invocation. 424 * @return the generic type {@code <R>} defined by the implementing class; 425 * the command itself returns no value and writes its result to the 426 * standard output; see class level parameter comments for more 427 * details 428 */ 429 R xargs(XargsOptions options, String delimiter, long maxLines, int maxArgs); 430 /** 431 * Reads items from the standard input using the specified delimiter to 432 separate items, and provides variables for the items read from the 433 standard input. If the {@code eof} string occurs as a line of input, 434 the rest of the input is ignored. The command following after xargs 435 is executed once for every {@code maxLines} nonblank input lines or 436 {@code maxArgs} items (whichever occurs first). Fewer lines or items 437 may be used for the last invocation with the remaining lines at the 438 end of the file. The item variables are usually passed to the 439 invoked command as arguments. 440 * 441 * @param options The options defining command behavior. 442 * @param delimiter Input items are terminated by the specified characters. 443 * @param eof If the end of file string occurs as a line of input, the rest of the 444 input is ignored. 445 * @param maxLines Use at most maxLines nonblank input lines per command invocation. 446 * @param maxArgs Use at most maxArgs arguments per command invocation. 447 * @return the generic type {@code <R>} defined by the implementing class; 448 * the command itself returns no value and writes its result to the 449 * standard output; see class level parameter comments for more 450 * details 451 */ 452 R xargs(XargsOptions options, String delimiter, String eof, long maxLines, int maxArgs); 453 } 454 455 /** 456 * Options for the "xargs" command: {@link XargsOption#delimiter0 z}, {@link XargsOption#exactArgs x}, {@link XargsOption#noRunIfEmpty r}, {@link XargsOption#verbose t}. 457 * <p> 458 * <table> 459 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -z}</td><td> </td><td nowrap="nowrap">{@code --delimiter0}</td><td> </td><td>Input items are terminated by a null character instead of by 460 whitespace, and the quotes and backslash are not special (every 461 character is taken literally). Disables the end of file string, 462 which is treated like any other argument. Useful when input items 463 might contain white space, quote marks, or backslashes. The find 464 --print0 option produces input suitable for this mode. 465 <p> 466 (This option is ignored if an explicit delimiter operand is specified).</td></tr> 467 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -x}</td><td> </td><td nowrap="nowrap">{@code --exactArgs}</td><td> </td><td>Terminate immediately if {@code maxArgs} is specified but the found 468 number of variable items is less than {@code maxArgs}. 469<p> 470 (This option is ignored if no {@code maxArgs} operand is specified).</td></tr> 471 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td> </td><td nowrap="nowrap">{@code --noRunIfEmpty}</td><td> </td><td>If the standard input does not contain any nonblanks, do not run the 472 command. Normally, the command is run once even if there is no 473 input.</td></tr> 474 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td> </td><td nowrap="nowrap">{@code --verbose}</td><td> </td><td>Print the command line on the standard error output before executing 475 it.</td></tr> 476 * </table> 477 */ 478 public static final XargsOptionSets Options = XargsOptionSets.INSTANCE; 479 480 /** 481 * Singleton {@link XargsFactory factory} instance for the "xargs" command. 482 */ 483 public static final XargsFactory Factory = XargsFactory.INSTANCE; 484 485 // no instances 486 private Xargs() { 487 super(); 488 } 489}