001package Torello.Java;
002
003import java.util.*;
004
005/**
006 * The class <CODE>'Q'</CODE> (Query) is an extremely simple debugging tool that is similar
007 * to an IDE's 'breakpoint' feature, but instead using terminal input.
008 * 
009 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=Q>
010 */
011@Torello.JavaDoc.StaticFunctional
012public class Q
013{
014    private Q() { }
015
016    /**
017     * <B STYLE='color:red;'><CODE>BP: Break Point</CODE></B>
018     * 
019     * <BR /><BR />Asks the user at the Command Line if Program Flow should continue.  If the user
020     * responds with 'no', then program execution is halted.
021     */
022    public static void BP()
023    { if (! YN("Continue ?")) System.exit(1); }
024
025    /**
026     * <B STYLE='color:red;'><CODE>BP: Break Point</CODE></B>
027     * 
028     * <BR /><BR />Asks the user at the Command Line if Program Flow should continue.  If the user
029     * responds with 'no', then program execution is halted.
030     * 
031     * @param message This is printed to terminal using {@code System.out.println(message)} before
032     * asking the user if he would like to continue.
033     */
034    public static void BP(String message)
035    {
036        System.out.println(message);
037
038        if (! YN("Continue ?")) System.exit(1);
039    }
040
041    /**
042     * {@code java.util.Scanner} is not the most memorable class, but still, pretty useful.
043     * This {@code static} method will repeatedly prompt the user using {@code System.out} until a
044     * {@code 'y'} or an {@code 'n'} has been pressed.
045     *
046     * @param yesOrNoQuestion This is output to the prompt each time the user fails to enter
047     * {@code 'y'} or {@code 'n'}.
048     *
049     * @return {@code TRUE} if the user pushed {@code 'y'} on a single input line, and {@code FALSE}
050     * if the user has pushed {@code 'n'} on a single input line.  The question asked will be
051     * repeated if neither of those has occurred.
052     */
053    public static boolean YN(String yesOrNoQuestion)
054    {
055        Scanner input = new Scanner(System.in);
056
057        while (true)
058        {
059            System.out.println(yesOrNoQuestion);
060            System.out.println("Please type the letter 'y' or the letter 'n' and [ENTER]");
061
062            String yesOrNo = input.nextLine().toLowerCase();
063
064            if (yesOrNo.equalsIgnoreCase("y")) return true;
065            if (yesOrNo.equalsIgnoreCase("n")) return false;
066        }
067    }
068
069    /**
070     * This will query a user for a valid input integer.  If the user fails to enter a valid
071     * integer, and the {@code Integer.parseInt(user-input);} throws an exception, the method
072     * will ask the user repeatedly until a valid integer has been provided.
073     *
074     * @return The integer version of the user's input.
075     */
076    public static int intNUM()
077    {
078        Scanner input = new Scanner(System.in);
079
080        while (true)
081        {
082            System.out.println("Please enter any valid integer, and then press [ENTER]");
083
084            String s = input.nextLine();
085
086            try
087                { int n = Integer.parseInt(s); return n; }
088
089            catch (Exception e)
090                { System.out.println("That was not a valid integer, try again."); }
091        }
092    }
093
094    /**
095     * Reads a single line of user input, and returns that line as a string.
096     * @return <SPAN STYLE="color: green;">return (new Scanner(System.in)).nextLine();</SPAN>
097     */
098    public static String readLine()
099    { return (new Scanner(System.in)).nextLine(); }
100}