Using JHDLOutput

Overview

JHDLOutput is a class that is useful for handling messaging in JHDL.

Introduction

It is often desirable to redirect the location to which JHDL sends its messages. For this reason, using System.out and System.err to display messages can be cumbersome and inadequate. JHDLOutput is a global static class that contains two primary components that aid in controlling messaging:

• A static hashtable that can contain dynamic instances of the JHDLOutput class
• Various dynamic instances of the class JHDLPrintWriter, which extends PrintWriter

Usage

When using JHDLOutput in your code, determine the following:

• Which part of JHDL is calling JHDLOutput (i.e., jab, simulator, netlister, etc.)?
• With which types of messages will you be working (i.e., error messages, status messages, etc.)?
• Where would you like each type of message to go (i.e., console, file, nothing, user-provided OutputStream)?

To use JHDLOutput in your code, first obtain an instance of JHDLOutput that relates to the part of JHDL you are using. For example, if you are writing code for jab, you would retrieve the instance of JHDLOutput for jab with the following code (located in the scope of the entire class):

private static JHDLOutput jout = JHDLOutput.getJHDLOutput("jab");

Next, you will want to determine to where each JHDLPrintWriter's OutputStream will point. By default, they point to System.out.

The dynamic instances of JHDLPrintWriter contained in each JHDLOutput object are as follows:

• error
• warning
• notice
• status
• debug

To redirect the JHDLPrintWriter instance called error to the console, you would do so with the following code (usually best placed in the constructor or the main() method):

jout.setToConsole(JHDLOutput.ERROR);

Note that this only applies to the JHDLOutput object identified as "jab". If you wanted to redirect error that is in another JHDLOutput object to the console, you would specify the name of the JHDLOutput object in the method call to setToConsole():

jout.setToConsole("netlister",JHDLOutput.ERROR);

or

JHDLOutput.setToConsole("netlister",JHDLOutput.ERROR);

Note that since the instance of JHDLOutput called jout uses the same static components of the class called JHDLOutput, it does not matter which you use.

Once the JHDLPrintWriter's OutputStream is set, you can use the methods contained in PrintWriter to post your messages. For example:

jout.error.print("Too many splificans reticulated! Barring foo.\n");

Some Useful Examples

Quick-and-dirty Message Printing

Don't have time or patience for retrieving a JHDLOutput object, setting the JHDLPrintWriter OutputStream objects, and printing your message? Try the following:

JHDLOutput.getJHDLOutput().status.print("Alright already, just print this!\n");

Provided that the default JHDLOutput object has not already been tampered with by another part of the program, this will automatically create an instance of JHDLOutput named "default", set all the JDHLPrintWriter OutputStream objects to System.out, and then print the message.

The most straight-forward way to use JHDLOutput in a section of code is to do the following:

(in the scope of the entire class)
private static JHDLOutput jout = JHDLOutput.getJHDLOutput("jab");

(in the constructor or the main() method)
jout.setAllToConsole(); // Makes sure that all streams point to the console
jout.clearPrefixes(); // Optional; use if you don't want the standard prefixes placed before each message (this may be made the default case in the near future)

(anywhere in the class)
...
jout.status.print("The status of jab is that jab is currently printing its status.\n");
...
jout.error.print("Unable to make sense of your circuit design. Recommend removing yourself from the engineering pool. To safely erase the contents of your hard drive, go to your root directory and use the command 'rm -f -R *'\n");
...

Redirecting all JHDLPrintWriter objects of a JHDLOutput object to a specified OutputStream

To redirect all JHDLPrintWriter objects instantiated in a given JHDLOutput object (for this example, we'll use jout), use code similar to the following:

jout.setAllToFile("log.txt");

If you wish to redirect all JHDLPrintWriter objects in another JHDLOutput object, simply include its string identifier in the parameter list:

JHDLOutput.setAllToFile("netlister", "log.txt");

To redirect all output for all JHDLOutput objects, do something like this:

JHDLOutput.setAllJHDLOutputsToConsole();

To redirect the messages for all components of JHDL to your own OutputStream object, use the code:

JHDLOutput.redirectAllJHDLOutputs(myCustomOutputStream);

... and the list goes on. See the API documentation for JHDLOutput for a complete list of utility methods for redirecting the output of the JHDLOutput objects.