package Torello.Java;

import java.io.*;
import java.util.*;
import java.util.regex.*;

import java.util.concurrent.CompletionException;
import java.util.function.Consumer;

import Torello.Java.*;
import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.Java.Additional.*;

/**
 * A great tool for working with a UNIX operating-system, and invoking common UNIX commands - this
 * class simply converts many of the old UNIX-BASH shell commands into a simple Java API.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=SHELL>
 * <EMBED ClASS='external-html' DATA-FILE-ID=OSC_WORA>
 * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_WILD_CARD_02>
 * <EMBED CLASS='external-html' DATA-CLASS=Shell DATA-VAR=shell DATA-FILE-ID=OSC_ALL_FIELDS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
 * 
 * @see OSCommands
 * @see OSResponse
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="OSC_INHERITORS")
public class Shell extends OSCommands implements Cloneable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_1> */
    public Shell() { super(); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_2>
     * @param outputAppendable <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
     * @see OSCommands#outputAppendable
     */
    public Shell(Appendable outputAppendable)
    { super(outputAppendable); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_3>
     * 
     * @param outputAppendable      <EMBED CLASS='external-html' DATA-FILE-ID=OSC_APPENDABLE_PARAM>
     * @param commandStrAppendable  <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CSA_PARAM>
     * @param standardOutput        <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
     * @param errorOutput           <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
     * @see OSCommands#outputAppendable
     * @see OSCommands#commandStrAppendable
     * @see OSCommands#standardOutput 
     * @see OSCommands#errorOutput 
     */
    public Shell(
            Appendable outputAppendable,
            Appendable commandStrAppendable,
            Appendable standardOutput,
            Appendable errorOutput
        )
    { super(outputAppendable, commandStrAppendable, standardOutput, errorOutput); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=OSC_CTOR_4>
     * 
     * @param standardOutput    <EMBED CLASS='external-html' DATA-FILE-ID=OSC_STND_OUT_PARAM>
     * @param errorOutput       <EMBED CLASS='external-html' DATA-FILE-ID=OSC_ERROR_OUT_PARAM>
     * @see OSCommands#standardOutput 
     * @see OSCommands#errorOutput 
     */
    public Shell(Appendable standardOutput, Appendable errorOutput)
    { super(standardOutput, errorOutput); }

    /**
     * Used by the method {@code clone()}.
     * @param other Another instance of this class.
     */
    protected Shell(Shell other) { super(other); }

    /** {@inheritDoc} */
    public Shell clone() { return new Shell(this); }



    // ********************************************************************************************
    // ********************************************************************************************
    // The Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * UNIX Shell Command: {@code Copy}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ cp <src> <target>
     * }</DIV>
     * 
     * @param src UNIX/Linux/BASH-Shell {@code 'cp'} command's "source" argument
     * @param target The {@code 'cp'} command "target" argument
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CP(String src, String target) throws IOException
    { 
        String[] command = { "cp", src, target };

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Copy}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ cp <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)> <target>
     * }</DIV>
     * 
     * @param src This may be a list of files to be copied to a target directory
     * @param target This is the target directory for the files listed.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CP(Vector<String> src, String target) throws IOException
    {
        String[] command = new String[src.size() + 2];
        command[0] = "cp";
        command[src.size() + 1] = target;

        for (int i=0; i < src.size(); i++) command[1 + i] = src.elementAt(i);

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Copy}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ cp <src[0]> <src[1]> ... <src[src.length-1]> <target>
     * }</DIV>
     * 
     * @param src This may be a list of files to be copied to a target directory
     * @param target This is the target directory for the files listed.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CP(String[] src, String target) throws IOException
    {
        String[] command = new String[src.length + 2];
        command[0] = "cp";
        command[src.length + 1] = target;

        for (int i=0; i < src.length; i++) command[1 + i] = src[i];

        return printAndRun(command);
    }	

    /**
     * UNIX Shell Command: {@code List}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ ls <fileOrDir>
     * }</DIV>
     * 
     * @param fileOrDir This is the file <B><I>OR</I></B> directory to be searched.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse LS(String fileOrDir) throws IOException
    { 
        String[] command = { "ls", fileOrDir };

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code List}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ ls <switches> <fileOrDir>
     * }</DIV>
     * 
     * @param fileOrDir This is the file <B><I>OR</I></B> directory to be searched.
     * @param switches These are switches that are added to the command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse LS(String fileOrDir, String switches)
        throws IOException
    { 
        String[] command = { "ls", switches, fileOrDir };

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Move}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ mv <src> <target>
     * }</DIV>
     * 
     * @param src The first {@code String} in a typical UNIX {@code 'move'} command. It is the
     * "source file"
     * 
     * @param target The second {@code String} for a "move."  This is the destination or target.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse MV(String src, String target) throws IOException
    { 
        String[] command = { "mv", src, target };

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Move}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ mv <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)> <target>
     * }</DIV>
     * 
     * @param src The first {@code String} in a typical UNIX {@code 'move'} command.
     * It is the "source file" - In this method, it is a list of files and expressions saved as a
     * {@code Vector}.
     * 
     * @param target The second {@code String} for a {@code 'move'} UNIX command, and it is the
     * target destination of the source-file.
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse MV(Vector<String> src, String target) throws IOException
    {
        String[] command = new String[src.size() + 2];
        command[0] = "mv";
        command[src.size() + 1] = target;

        for (int i=0; i < src.size(); i++) command[1 + i] = src.elementAt(i);

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Move}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ mv <src[0]> <src[1]> ... <src[src.length-1]> <target>
     * }</DIV>
     * 
     * @param src The first {@code String} in a typical UNIX {@code 'move'} command.
     * It is the "source file" - In this method, it is a list of files and expressions saved as an
     * array.
     * 
     * @param target The second {@code String} for a UNIX {@code 'move'} command, and it is the
     * target destination
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse MV(String[] src, String target) throws IOException
    {
        String[] command = new String[src.length + 2];
        command[0] = "mv";
        command[src.length + 1] = target;

        for (int i=0; i < src.length; i++) command[1 + i] = src[i];

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Remove}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ rm <s1>
     * }</DIV>
     * 
     * @param s1 The item to be removed, using a UNIX operating-system command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse RM(String s1) throws IOException
    { 
        String[] command = { "rm", s1 };

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Remove}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ rm <sArr[0]> <sArr[1]> ... <sArr[sArr.length-1]>
     * }</DIV>
     * 
     * @param sArr An {@code String[] array} which is added to the end of this UNIX command.
     * These will be the item(s) removed by the UNIX {@code 'RM'} command.
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse RM(String[] sArr) throws IOException
    {
        String[] command = new String[sArr.length + 1];
        command[0] = "rm";

        for (int i=0; i < sArr.length; i++) command[i + 1] = sArr[i];

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Remove}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ rm  <src.elementAt(0)> <src.elementAt(1)> ... <src.elementAt(src.size()-1)>
     * }</DIV>
     * 
     * @param v A {@code Vector<String>} that contains command-line-parameters which
     * are added, sequentially, to the end of this UNIX command.  The {@code String's} in
     * this {@code Vector} are the item(s) to be removed by the UNIX {@code 'RM'} command.
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse RM(Vector<String> v) throws IOException
    {
        String[] command = new String[v.size() + 1];
        command[0] = "rm";

        for (int i=0; i < v.size(); i++) command[i + 1] = v.elementAt(i);

        return printAndRun(command);
    }

    /**
     * UNIX Shell Command: {@code Remove}
     * 
     * <DIV CLASS="SHELL">{@code
     * $ rm <switches> <s1>
     * }</DIV>
     * 
     * @param s1 A file or directory parameter passed to {@code 'RM'}
     * @param switches These are switches (for-instance: {@code -R}, recursive).
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse RM(String s1, String switches) throws IOException
    { 
        String[] command = { "rm", switches, s1 };

        return printAndRun(command);
    }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code tar}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ tar <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse TAR(String... args) throws IOException
    { return ARGS_PLUS_ONE("tar", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code jar}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ jar <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse JAR(String... args) throws IOException
    { return ARGS_PLUS_ONE("jar", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code grep}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ grep <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse GREP(String... args) throws IOException
    { return ARGS_PLUS_ONE("grep", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code find}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ find <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse FIND(String... args) throws IOException
    { return ARGS_PLUS_ONE("find", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code du}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ du <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse DU(String... args) throws IOException
    { return ARGS_PLUS_ONE("du", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code df}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ df <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse DF(String... args) throws IOException
    { return ARGS_PLUS_ONE("df", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code sed}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ sed <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse SED(String... args) throws IOException
    { return ARGS_PLUS_ONE("sed", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code whatis}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ whatis <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse WHATIS(String... args) throws IOException
    { return ARGS_PLUS_ONE("whatis", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code whereis}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ whereis <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse WHEREIS(String... args) throws IOException
    { return ARGS_PLUS_ONE("whereis", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code vmstat}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ vmstat <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse VMSTAT(String... args) throws IOException
    { return ARGS_PLUS_ONE("vmstat", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code ps}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ ps <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse PS(String... args) throws IOException
    { return ARGS_PLUS_ONE("ps", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code diff}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ diff <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse DIFF(String... args) throws IOException
    { return ARGS_PLUS_ONE("diff", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code cmp}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ cmp <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CMP(String... args) throws IOException
    { return ARGS_PLUS_ONE("CMP", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code free}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ free <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse FREE(String... args) throws IOException
    { return ARGS_PLUS_ONE("free", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code chown}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ chown <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CHOWN(String... args) throws IOException
    { return ARGS_PLUS_ONE("chown", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code chmod}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ chmod <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse CHMOD(String... args) throws IOException
    { return ARGS_PLUS_ONE("chmod", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code unzip}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ unzip <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse UNZIP(String... args) throws IOException
    { return ARGS_PLUS_ONE("unzip", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code gzip}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ gzip <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse GZIP(String... args) throws IOException
    { return ARGS_PLUS_ONE("gzip", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code sort}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ sort <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse SORT(String... args) throws IOException
    { return ARGS_PLUS_ONE("sort", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code javac}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ javac <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse JAVAC(String... args) throws IOException
    { return ARGS_PLUS_ONE("javac", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code javadoc}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ javadoc <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse JAVADOC(String... args) throws IOException
    { return ARGS_PLUS_ONE("javadoc", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code java}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ java <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse JAVA(String... args) throws IOException
    { return ARGS_PLUS_ONE("java", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code time}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ time <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse TIME(String... args) throws IOException
    { return ARGS_PLUS_ONE("java", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code date}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ date <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public  OSResponse DATE(String... args) throws IOException
    { return ARGS_PLUS_ONE("java", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code traceroute}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ traceroute <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse TRACEROUTE(String... args) throws IOException
    { return ARGS_PLUS_ONE("traceroute", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code fsck}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ fsck <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse FSCK(String... args) throws IOException
    { return ARGS_PLUS_ONE("fsck", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code nslookup}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ nslookup <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse NSLOOKUP(String... args) throws IOException
    { return ARGS_PLUS_ONE("nslookup", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command: <B>{@code ping}</B>
     *
     * <DIV CLASS="SHELL">{@code
     * $ ping <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse PING(String... args) throws IOException
    { return ARGS_PLUS_ONE("ping", args); }

    /**
     * Runs the {@code UNIX / BASH / LINUX 'shell'} command named by the input parameter
     * {@code COMMAND_NAME}.
     *
     * <DIV CLASS="SHELL">{@code
     * $ COMMAND_NAME <args[0]> <args[1]> ... <args[args.length-1]>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=SH_COMMAND>
     *
     * @param COMMAND_NAME This is the name of any UNIX command not already listed inside this
     * class.
     * 
     * @param args Any set of switches and/or arguments to this BASH command.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @throws IOException If there are problems while invoking the operating-system command
     */
    public OSResponse COMMAND(String COMMAND_NAME, String... args) throws IOException
    { return ARGS_PLUS_ONE(COMMAND_NAME, args); }

    /**
     * This just appends the UNIX/BASH Shell command to the beginning of the {@code String[]}
     * (String...) of arguments, and then calls the execution of the comamnd.
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=OSRET>
     * @see OSCommands#printAndRun(String[])
     * @throws IOException If there are problems while invoking the operating-system command
     */
    private OSResponse ARGS_PLUS_ONE(String command, String... args)
        throws IOException 
    {
        String[] argsPlus1 = new String[args.length + 1];
        argsPlus1[0] = command;

        for (int i=0; i < args.length; i++) argsPlus1[1 + i] = args[i];

        return printAndRun(argsPlus1);
    }
}