001package Torello.Java;
002
003import java.io.*;
004import java.util.*;
005import java.util.regex.*;
006
007import java.util.concurrent.CompletionException;
008import java.util.function.Consumer;
009
010import Torello.Java.*;
011import Torello.HTML.*;
012import Torello.HTML.NodeSearch.*;
013import Torello.Java.Additional.*;
014
015/**
016 * A great tool for working with a UNIX operating-system, and invoking common UNIX commands - this
017 * class simply converts many of the old UNIX-BASH shell commands into a simple Java API.
018 * 
019 * <EMBED CLASS='external-html' DATA-FILE-ID=SHELL>
020 * <EMBED ClASS='external-html' DATA-FILE-ID=OSC_WORA>
021 * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_WILD_CARD_02>
022 * <EMBED CLASS='external-html' DATA-CLASS=Shell DATA-VAR=shell DATA-FILE-ID=OSC_ALL_FIELDS>
023 * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
024 * 
025 * @see OSCommands
026 * @see OSResponse
027 */
028@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="OSC_INHERITORS")
029public class Shell extends OSCommands implements Cloneable
030{
031    // ********************************************************************************************
032    // ********************************************************************************************
033    // Constructors
034    // ********************************************************************************************
035    // ********************************************************************************************
036
037
038    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_1> */
039    public Shell() { super(); }
040
041    /**
042     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_2>
043     * @param outputAppendable <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
044     * @see OSCommands#outputAppendable
045     */
046    public Shell(Appendable outputAppendable)
047    { super(outputAppendable); }
048
049    /**
050     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_3>
051     * 
052     * @param outputAppendable      <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
053     * @param commandStrAppendable  <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CSA_PARAM>
054     * @param standardOutput        <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
055     * @param errorOutput           <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
056     * @see OSCommands#outputAppendable
057     * @see OSCommands#commandStrAppendable
058     * @see OSCommands#standardOutput 
059     * @see OSCommands#errorOutput 
060     */
061    public Shell(
062            Appendable outputAppendable,
063            Appendable commandStrAppendable,
064            Appendable standardOutput,
065            Appendable errorOutput
066        )
067    { super(outputAppendable, commandStrAppendable, standardOutput, errorOutput); }
068
069    /**
070     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_4>
071     * 
072     * @param standardOutput    <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
073     * @param errorOutput       <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
074     * @see OSCommands#standardOutput 
075     * @see OSCommands#errorOutput 
076     */
077    public Shell(Appendable standardOutput, Appendable errorOutput)
078    { super(standardOutput, errorOutput); }
079
080    /**
081     * Used by the method {@code clone()}.
082     * @param other Another instance of this class.
083     */
084    protected Shell(Shell other) { super(other); }
085
086    /** {@inheritDoc} */
087    public Shell clone() { return new Shell(this); }
088
089
090
091    // ********************************************************************************************
092    // ********************************************************************************************
093    // The Methods
094    // ********************************************************************************************
095    // ********************************************************************************************
096
097
098    /**
099     * UNIX Shell Command: {@code Copy}
100     * 
101     * <DIV CLASS="SHELL">{@code
102     * $ cp <src> <target>
103     * }</DIV>
104     * 
105     * @param src UNIX/Linux/BASH-Shell {@code 'cp'} command's "source" argument
106     * @param target The {@code 'cp'} command "target" argument
107     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
108     * @see OSCommands#printAndRun(String[])
109     * @throws IOException If there are problems while invoking the operating-system command
110     */
111    public OSResponse CP(String src, String target) throws IOException
112    { 
113        String[] command = { "cp", src, target };
114
115        return printAndRun(command);
116    }
117
118    /**
119     * UNIX Shell Command: {@code Copy}
120     * 
121     * <DIV CLASS="SHELL">{@code
122     * $ cp <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)> <target>
123     * }</DIV>
124     * 
125     * @param src This may be a list of files to be copied to a target directory
126     * @param target This is the target directory for the files listed.
127     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
128     * @see OSCommands#printAndRun(String[])
129     * @throws IOException If there are problems while invoking the operating-system command
130     */
131    public OSResponse CP(Vector<String> src, String target) throws IOException
132    {
133        String[] command = new String[src.size() + 2];
134        command[0] = "cp";
135        command[src.size() + 1] = target;
136
137        for (int i=0; i < src.size(); i++) command[1 + i] = src.elementAt(i);
138
139        return printAndRun(command);
140    }
141
142    /**
143     * UNIX Shell Command: {@code Copy}
144     * 
145     * <DIV CLASS="SHELL">{@code
146     * $ cp <src[0]> <src[1]> ... <src[src.length-1]> <target>
147     * }</DIV>
148     * 
149     * @param src This may be a list of files to be copied to a target directory
150     * @param target This is the target directory for the files listed.
151     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
152     * @see OSCommands#printAndRun(String[])
153     * @throws IOException If there are problems while invoking the operating-system command
154     */
155    public OSResponse CP(String[] src, String target) throws IOException
156    {
157        String[] command = new String[src.length + 2];
158        command[0] = "cp";
159        command[src.length + 1] = target;
160
161        for (int i=0; i < src.length; i++) command[1 + i] = src[i];
162
163        return printAndRun(command);
164    }   
165
166    /**
167     * UNIX Shell Command: {@code List}
168     * 
169     * <DIV CLASS="SHELL">{@code
170     * $ ls <fileOrDir>
171     * }</DIV>
172     * 
173     * @param fileOrDir This is the file <B><I>OR</I></B> directory to be searched.
174     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
175     * @see OSCommands#printAndRun(String[])
176     * @throws IOException If there are problems while invoking the operating-system command
177     */
178    public OSResponse LS(String fileOrDir) throws IOException
179    { 
180        String[] command = { "ls", fileOrDir };
181
182        return printAndRun(command);
183    }
184
185    /**
186     * UNIX Shell Command: {@code List}
187     * 
188     * <DIV CLASS="SHELL">{@code
189     * $ ls <switches> <fileOrDir>
190     * }</DIV>
191     * 
192     * @param fileOrDir This is the file <B><I>OR</I></B> directory to be searched.
193     * @param switches These are switches that are added to the command.
194     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
195     * @see OSCommands#printAndRun(String[])
196     * @throws IOException If there are problems while invoking the operating-system command
197     */
198    public OSResponse LS(String fileOrDir, String switches)
199        throws IOException
200    { 
201        String[] command = { "ls", switches, fileOrDir };
202
203        return printAndRun(command);
204    }
205
206    /**
207     * UNIX Shell Command: {@code Move}
208     * 
209     * <DIV CLASS="SHELL">{@code
210     * $ mv <src> <target>
211     * }</DIV>
212     * 
213     * @param src The first {@code String} in a typical UNIX {@code 'move'} command. It is the
214     * "source file"
215     * 
216     * @param target The second {@code String} for a "move."  This is the destination or target.
217     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
218     * @see OSCommands#printAndRun(String[])
219     * @throws IOException If there are problems while invoking the operating-system command
220     */
221    public OSResponse MV(String src, String target) throws IOException
222    { 
223        String[] command = { "mv", src, target };
224
225        return printAndRun(command);
226    }
227
228    /**
229     * UNIX Shell Command: {@code Move}
230     * 
231     * <DIV CLASS="SHELL">{@code
232     * $ mv <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)> <target>
233     * }</DIV>
234     * 
235     * @param src The first {@code String} in a typical UNIX {@code 'move'} command.
236     * It is the "source file" - In this method, it is a list of files and expressions saved as a
237     * {@code Vector}.
238     * 
239     * @param target The second {@code String} for a {@code 'move'} UNIX command, and it is the
240     * target destination of the source-file.
241     * 
242     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
243     * @see OSCommands#printAndRun(String[])
244     * @throws IOException If there are problems while invoking the operating-system command
245     */
246    public OSResponse MV(Vector<String> src, String target) throws IOException
247    {
248        String[] command = new String[src.size() + 2];
249        command[0] = "mv";
250        command[src.size() + 1] = target;
251
252        for (int i=0; i < src.size(); i++) command[1 + i] = src.elementAt(i);
253
254        return printAndRun(command);
255    }
256
257    /**
258     * UNIX Shell Command: {@code Move}
259     * 
260     * <DIV CLASS="SHELL">{@code
261     * $ mv <src[0]> <src[1]> ... <src[src.length-1]> <target>
262     * }</DIV>
263     * 
264     * @param src The first {@code String} in a typical UNIX {@code 'move'} command.
265     * It is the "source file" - In this method, it is a list of files and expressions saved as an
266     * array.
267     * 
268     * @param target The second {@code String} for a UNIX {@code 'move'} command, and it is the
269     * target destination
270     * 
271     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
272     * @see OSCommands#printAndRun(String[])
273     * @throws IOException If there are problems while invoking the operating-system command
274     */
275    public OSResponse MV(String[] src, String target) throws IOException
276    {
277        String[] command = new String[src.length + 2];
278        command[0] = "mv";
279        command[src.length + 1] = target;
280
281        for (int i=0; i < src.length; i++) command[1 + i] = src[i];
282
283        return printAndRun(command);
284    }
285
286    /**
287     * UNIX Shell Command: {@code Remove}
288     * 
289     * <DIV CLASS="SHELL">{@code
290     * $ rm <s1>
291     * }</DIV>
292     * 
293     * @param s1 The item to be removed, using a UNIX operating-system command.
294     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
295     * @see OSCommands#printAndRun(String[])
296     * @throws IOException If there are problems while invoking the operating-system command
297     */
298    public OSResponse RM(String s1) throws IOException
299    { 
300        String[] command = { "rm", s1 };
301
302        return printAndRun(command);
303    }
304
305    /**
306     * UNIX Shell Command: {@code Remove}
307     * 
308     * <DIV CLASS="SHELL">{@code
309     * $ rm <sArr[0]> <sArr[1]> ... <sArr[sArr.length-1]>
310     * }</DIV>
311     * 
312     * @param sArr An {@code String[] array} which is added to the end of this UNIX command.
313     * These will be the item(s) removed by the UNIX {@code 'RM'} command.
314     * 
315     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
316     * @see OSCommands#printAndRun(String[])
317     * @throws IOException If there are problems while invoking the operating-system command
318     */
319    public OSResponse RM(String[] sArr) throws IOException
320    {
321        String[] command = new String[sArr.length + 1];
322        command[0] = "rm";
323
324        for (int i=0; i < sArr.length; i++) command[i + 1] = sArr[i];
325
326        return printAndRun(command);
327    }
328
329    /**
330     * UNIX Shell Command: {@code Remove}
331     * 
332     * <DIV CLASS="SHELL">{@code
333     * $ rm  <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)>
334     * }</DIV>
335     * 
336     * @param v A {@code Vector<String>} that contains command-line-parameters which
337     * are added, sequentially, to the end of this UNIX command.  The {@code String's} in
338     * this {@code Vector} are the item(s) to be removed by the UNIX {@code 'RM'} command.
339     * 
340     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
341     * @see OSCommands#printAndRun(String[])
342     * @throws IOException If there are problems while invoking the operating-system command
343     */
344    public OSResponse RM(Vector<String> v) throws IOException
345    {
346        String[] command = new String[v.size() + 1];
347        command[0] = "rm";
348
349        for (int i=0; i < v.size(); i++) command[i + 1] = v.elementAt(i);
350
351        return printAndRun(command);
352    }
353
354    /**
355     * UNIX Shell Command: {@code Remove}
356     * 
357     * <DIV CLASS="SHELL">{@code
358     * $ rm <switches> <s1>
359     * }</DIV>
360     * 
361     * @param s1 A file or directory parameter passed to {@code 'RM'}
362     * @param switches These are switches (for-instance: {@code -R}, recursive).
363     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
364     * @see OSCommands#printAndRun(String[])
365     * @throws IOException If there are problems while invoking the operating-system command
366     */
367    public OSResponse RM(String s1, String switches) throws IOException
368    { 
369        String[] command = { "rm", switches, s1 };
370
371        return printAndRun(command);
372    }
373
374    /**
375     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code tar}</B>
376     *
377     * <DIV CLASS="SHELL">{@code
378     * $ tar <args[0]> <args[1]> ... <args[args.length-1]>
379     * }</DIV>
380     * 
381     * @param args Any set of switches and/or arguments to this BASH command.
382     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
383     * @throws IOException If there are problems while invoking the operating-system command
384     */
385    public OSResponse TAR(String... args) throws IOException
386    { return ARGS_PLUS_ONE("tar", args); }
387
388    /**
389     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code jar}</B>
390     *
391     * <DIV CLASS="SHELL">{@code
392     * $ jar <args[0]> <args[1]> ... <args[args.length-1]>
393     * }</DIV>
394     * 
395     * @param args Any set of switches and/or arguments to this BASH command.
396     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
397     * @throws IOException If there are problems while invoking the operating-system command
398     */
399    public OSResponse JAR(String... args) throws IOException
400    { return ARGS_PLUS_ONE("jar", args); }
401
402    /**
403     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code grep}</B>
404     *
405     * <DIV CLASS="SHELL">{@code
406     * $ grep <args[0]> <args[1]> ... <args[args.length-1]>
407     * }</DIV>
408     * 
409     * @param args Any set of switches and/or arguments to this BASH command.
410     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
411     * @throws IOException If there are problems while invoking the operating-system command
412     */
413    public OSResponse GREP(String... args) throws IOException
414    { return ARGS_PLUS_ONE("grep", args); }
415
416    /**
417     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code find}</B>
418     *
419     * <DIV CLASS="SHELL">{@code
420     * $ find <args[0]> <args[1]> ... <args[args.length-1]>
421     * }</DIV>
422     * 
423     * @param args Any set of switches and/or arguments to this BASH command.
424     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
425     * @throws IOException If there are problems while invoking the operating-system command
426     */
427    public OSResponse FIND(String... args) throws IOException
428    { return ARGS_PLUS_ONE("find", args); }
429
430    /**
431     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code du}</B>
432     *
433     * <DIV CLASS="SHELL">{@code
434     * $ du <args[0]> <args[1]> ... <args[args.length-1]>
435     * }</DIV>
436     * 
437     * @param args Any set of switches and/or arguments to this BASH command.
438     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
439     * @throws IOException If there are problems while invoking the operating-system command
440     */
441    public OSResponse DU(String... args) throws IOException
442    { return ARGS_PLUS_ONE("du", args); }
443
444    /**
445     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code df}</B>
446     *
447     * <DIV CLASS="SHELL">{@code
448     * $ df <args[0]> <args[1]> ... <args[args.length-1]>
449     * }</DIV>
450     * 
451     * @param args Any set of switches and/or arguments to this BASH command.
452     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
453     * @throws IOException If there are problems while invoking the operating-system command
454     */
455    public OSResponse DF(String... args) throws IOException
456    { return ARGS_PLUS_ONE("df", args); }
457
458    /**
459     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code sed}</B>
460     *
461     * <DIV CLASS="SHELL">{@code
462     * $ sed <args[0]> <args[1]> ... <args[args.length-1]>
463     * }</DIV>
464     * 
465     * @param args Any set of switches and/or arguments to this BASH command.
466     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
467     * @throws IOException If there are problems while invoking the operating-system command
468     */
469    public OSResponse SED(String... args) throws IOException
470    { return ARGS_PLUS_ONE("sed", args); }
471
472    /**
473     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code whatis}</B>
474     *
475     * <DIV CLASS="SHELL">{@code
476     * $ whatis <args[0]> <args[1]> ... <args[args.length-1]>
477     * }</DIV>
478     * 
479     * @param args Any set of switches and/or arguments to this BASH command.
480     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
481     * @throws IOException If there are problems while invoking the operating-system command
482     */
483    public OSResponse WHATIS(String... args) throws IOException
484    { return ARGS_PLUS_ONE("whatis", args); }
485
486    /**
487     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code whereis}</B>
488     *
489     * <DIV CLASS="SHELL">{@code
490     * $ whereis <args[0]> <args[1]> ... <args[args.length-1]>
491     * }</DIV>
492     * 
493     * @param args Any set of switches and/or arguments to this BASH command.
494     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
495     * @throws IOException If there are problems while invoking the operating-system command
496     */
497    public OSResponse WHEREIS(String... args) throws IOException
498    { return ARGS_PLUS_ONE("whereis", args); }
499
500    /**
501     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code vmstat}</B>
502     *
503     * <DIV CLASS="SHELL">{@code
504     * $ vmstat <args[0]> <args[1]> ... <args[args.length-1]>
505     * }</DIV>
506     * 
507     * @param args Any set of switches and/or arguments to this BASH command.
508     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
509     * @throws IOException If there are problems while invoking the operating-system command
510     */
511    public OSResponse VMSTAT(String... args) throws IOException
512    { return ARGS_PLUS_ONE("vmstat", args); }
513
514    /**
515     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code ps}</B>
516     *
517     * <DIV CLASS="SHELL">{@code
518     * $ ps <args[0]> <args[1]> ... <args[args.length-1]>
519     * }</DIV>
520     * 
521     * @param args Any set of switches and/or arguments to this BASH command.
522     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
523     * @throws IOException If there are problems while invoking the operating-system command
524     */
525    public OSResponse PS(String... args) throws IOException
526    { return ARGS_PLUS_ONE("ps", args); }
527
528    /**
529     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code diff}</B>
530     *
531     * <DIV CLASS="SHELL">{@code
532     * $ diff <args[0]> <args[1]> ... <args[args.length-1]>
533     * }</DIV>
534     * 
535     * @param args Any set of switches and/or arguments to this BASH command.
536     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
537     * @throws IOException If there are problems while invoking the operating-system command
538     */
539    public OSResponse DIFF(String... args) throws IOException
540    { return ARGS_PLUS_ONE("diff", args); }
541
542    /**
543     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code cmp}</B>
544     *
545     * <DIV CLASS="SHELL">{@code
546     * $ cmp <args[0]> <args[1]> ... <args[args.length-1]>
547     * }</DIV>
548     * 
549     * @param args Any set of switches and/or arguments to this BASH command.
550     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
551     * @throws IOException If there are problems while invoking the operating-system command
552     */
553    public OSResponse CMP(String... args) throws IOException
554    { return ARGS_PLUS_ONE("CMP", args); }
555
556    /**
557     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code free}</B>
558     *
559     * <DIV CLASS="SHELL">{@code
560     * $ free <args[0]> <args[1]> ... <args[args.length-1]>
561     * }</DIV>
562     * 
563     * @param args Any set of switches and/or arguments to this BASH command.
564     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
565     * @throws IOException If there are problems while invoking the operating-system command
566     */
567    public OSResponse FREE(String... args) throws IOException
568    { return ARGS_PLUS_ONE("free", args); }
569
570    /**
571     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code chown}</B>
572     *
573     * <DIV CLASS="SHELL">{@code
574     * $ chown <args[0]> <args[1]> ... <args[args.length-1]>
575     * }</DIV>
576     * 
577     * @param args Any set of switches and/or arguments to this BASH command.
578     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
579     * @throws IOException If there are problems while invoking the operating-system command
580     */
581    public OSResponse CHOWN(String... args) throws IOException
582    { return ARGS_PLUS_ONE("chown", args); }
583
584    /**
585     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code chmod}</B>
586     *
587     * <DIV CLASS="SHELL">{@code
588     * $ chmod <args[0]> <args[1]> ... <args[args.length-1]>
589     * }</DIV>
590     * 
591     * @param args Any set of switches and/or arguments to this BASH command.
592     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
593     * @throws IOException If there are problems while invoking the operating-system command
594     */
595    public OSResponse CHMOD(String... args) throws IOException
596    { return ARGS_PLUS_ONE("chmod", args); }
597
598    /**
599     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code unzip}</B>
600     *
601     * <DIV CLASS="SHELL">{@code
602     * $ unzip <args[0]> <args[1]> ... <args[args.length-1]>
603     * }</DIV>
604     * 
605     * @param args Any set of switches and/or arguments to this BASH command.
606     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
607     * @throws IOException If there are problems while invoking the operating-system command
608     */
609    public OSResponse UNZIP(String... args) throws IOException
610    { return ARGS_PLUS_ONE("unzip", args); }
611
612    /**
613     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code gzip}</B>
614     *
615     * <DIV CLASS="SHELL">{@code
616     * $ gzip <args[0]> <args[1]> ... <args[args.length-1]>
617     * }</DIV>
618     * 
619     * @param args Any set of switches and/or arguments to this BASH command.
620     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
621     * @throws IOException If there are problems while invoking the operating-system command
622     */
623    public OSResponse GZIP(String... args) throws IOException
624    { return ARGS_PLUS_ONE("gzip", args); }
625
626    /**
627     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code sort}</B>
628     *
629     * <DIV CLASS="SHELL">{@code
630     * $ sort <args[0]> <args[1]> ... <args[args.length-1]>
631     * }</DIV>
632     * 
633     * @param args Any set of switches and/or arguments to this BASH command.
634     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
635     * @throws IOException If there are problems while invoking the operating-system command
636     */
637    public OSResponse SORT(String... args) throws IOException
638    { return ARGS_PLUS_ONE("sort", args); }
639
640    /**
641     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code javac}</B>
642     *
643     * <DIV CLASS="SHELL">{@code
644     * $ javac <args[0]> <args[1]> ... <args[args.length-1]>
645     * }</DIV>
646     * 
647     * @param args Any set of switches and/or arguments to this BASH command.
648     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
649     * @throws IOException If there are problems while invoking the operating-system command
650     */
651    public OSResponse JAVAC(String... args) throws IOException
652    { return ARGS_PLUS_ONE("javac", args); }
653
654    /**
655     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code javadoc}</B>
656     *
657     * <DIV CLASS="SHELL">{@code
658     * $ javadoc <args[0]> <args[1]> ... <args[args.length-1]>
659     * }</DIV>
660     * 
661     * @param args Any set of switches and/or arguments to this BASH command.
662     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
663     * @throws IOException If there are problems while invoking the operating-system command
664     */
665    public OSResponse JAVADOC(String... args) throws IOException
666    { return ARGS_PLUS_ONE("javadoc", args); }
667
668    /**
669     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code java}</B>
670     *
671     * <DIV CLASS="SHELL">{@code
672     * $ java <args[0]> <args[1]> ... <args[args.length-1]>
673     * }</DIV>
674     * 
675     * @param args Any set of switches and/or arguments to this BASH command.
676     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
677     * @throws IOException If there are problems while invoking the operating-system command
678     */
679    public OSResponse JAVA(String... args) throws IOException
680    { return ARGS_PLUS_ONE("java", args); }
681
682    /**
683     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code time}</B>
684     *
685     * <DIV CLASS="SHELL">{@code
686     * $ time <args[0]> <args[1]> ... <args[args.length-1]>
687     * }</DIV>
688     * 
689     * @param args Any set of switches and/or arguments to this BASH command.
690     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
691     * @throws IOException If there are problems while invoking the operating-system command
692     */
693    public OSResponse TIME(String... args) throws IOException
694    { return ARGS_PLUS_ONE("java", args); }
695
696    /**
697     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code date}</B>
698     *
699     * <DIV CLASS="SHELL">{@code
700     * $ date <args[0]> <args[1]> ... <args[args.length-1]>
701     * }</DIV>
702     * 
703     * @param args Any set of switches and/or arguments to this BASH command.
704     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
705     * @throws IOException If there are problems while invoking the operating-system command
706     */
707    public  OSResponse DATE(String... args) throws IOException
708    { return ARGS_PLUS_ONE("java", args); }
709
710    /**
711     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code traceroute}</B>
712     *
713     * <DIV CLASS="SHELL">{@code
714     * $ traceroute <args[0]> <args[1]> ... <args[args.length-1]>
715     * }</DIV>
716     * 
717     * @param args Any set of switches and/or arguments to this BASH command.
718     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
719     * @throws IOException If there are problems while invoking the operating-system command
720     */
721    public OSResponse TRACEROUTE(String... args) throws IOException
722    { return ARGS_PLUS_ONE("traceroute", args); }
723
724    /**
725     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code fsck}</B>
726     *
727     * <DIV CLASS="SHELL">{@code
728     * $ fsck <args[0]> <args[1]> ... <args[args.length-1]>
729     * }</DIV>
730     * 
731     * @param args Any set of switches and/or arguments to this BASH command.
732     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
733     * @throws IOException If there are problems while invoking the operating-system command
734     */
735    public OSResponse FSCK(String... args) throws IOException
736    { return ARGS_PLUS_ONE("fsck", args); }
737
738    /**
739     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code nslookup}</B>
740     *
741     * <DIV CLASS="SHELL">{@code
742     * $ nslookup <args[0]> <args[1]> ... <args[args.length-1]>
743     * }</DIV>
744     * 
745     * @param args Any set of switches and/or arguments to this BASH command.
746     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
747     * @throws IOException If there are problems while invoking the operating-system command
748     */
749    public OSResponse NSLOOKUP(String... args) throws IOException
750    { return ARGS_PLUS_ONE("nslookup", args); }
751
752    /**
753     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code ping}</B>
754     *
755     * <DIV CLASS="SHELL">{@code
756     * $ ping <args[0]> <args[1]> ... <args[args.length-1]>
757     * }</DIV>
758     * 
759     * @param args Any set of switches and/or arguments to this BASH command.
760     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
761     * @throws IOException If there are problems while invoking the operating-system command
762     */
763    public OSResponse PING(String... args) throws IOException
764    { return ARGS_PLUS_ONE("ping", args); }
765
766    /**
767     * Runs the {@code UNIX / BASH / LINUX 'shell'} command named by the input parameter
768     * {@code COMMAND_NAME}.
769     *
770     * <DIV CLASS="SHELL">{@code
771     * $ COMMAND_NAME <args[0]> <args[1]> ... <args[args.length-1]>
772     * }</DIV>
773     * 
774     * <EMBED CLASS='external-html' DATA-FILE-ID=SH_COMMAND>
775     *
776     * @param COMMAND_NAME This is the name of any UNIX command not already listed inside this
777     * class.
778     * 
779     * @param args Any set of switches and/or arguments to this BASH command.
780     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
781     * @throws IOException If there are problems while invoking the operating-system command
782     */
783    public OSResponse COMMAND(String COMMAND_NAME, String... args) throws IOException
784    { return ARGS_PLUS_ONE(COMMAND_NAME, args); }
785
786    /**
787     * This just appends the UNIX/BASH Shell command to the beginning of the {@code String[]}
788     * (String...) of arguments, and then calls the execution of the comamnd.
789     * 
790     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
791     * @see OSCommands#printAndRun(String[])
792     * @throws IOException If there are problems while invoking the operating-system command
793     */
794    private OSResponse ARGS_PLUS_ONE(String command, String... args)
795        throws IOException 
796    {
797        String[] argsPlus1 = new String[args.length + 1];
798        argsPlus1[0] = command;
799
800        for (int i=0; i < args.length; i++) argsPlus1[1 + i] = args[i];
801
802        return printAndRun(argsPlus1);
803    }
804}