name: Console

synopsis:

g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_system.a

#include <Console.h>

static boolean open(const SysString& filename, MODE mode = File::APPEND_ONLY);
static boolean broadcast(const unichar* str);
static boolean close();

quick start:

Console::put(L"this is output to stdout");
Console::open(L"out.txt");
Console::put(L"this is appended to the file out.txt");
Console::broadcast(L"this is output to both stdout and the out.txt");
Console::close();

description:

The Console class controls messages (errors and debugging information) which programmers might want to send to stdout. Everything in this class is static, so there is only one way to handle screen output per program. Modularity of this class allows the user to control debugging of higher and lower level class with separate consoles. The user can send the error and debugging messages of different program components to separate log files for extensive debugging.

dependencies:

File

public constants:

define the class name:

static const SysString CLASS_NAME = L"Console";

define an upper limit on the stack of console file pointers:
```
static const long MAX_STACK_SIZE = 32;
```

define the number of characters used for automatic line wrapping:

static const long NO_WRAP = -1;

static const long DEF_LINE_WRAP = NO_WRAP;

define a default stream:

static const STREAM DEF_STREAM = File::OUT;

error codes:

error code indicating console class general error:
```
static const long ERR = 1400;
```
error code indicating too many open consoles:
```
static const long ERR_OPENMAX = 1401;
```

protected data:

define the current console:
```
static File cons_d;
```

define a stack of other consoles

static File stack_d[];

static long size_d;

static long stack_size_d;

declare a variable for initialization of line-wrapping:
```
static boolean initialized_wrap_d;
```
declare a static debug level:
```
static Integral::DEBUG debug_level_d;
```

required public methods:

static methods:

static const SysString& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

static boolean setDebug(Integral::DEBUG level);

static boolean debug(const unichar* message);

destructor/constructor(s):

the constructors and destructor are private so that Console objects cannot be instantiated

assign methods:

these methods are omitted because Console objects can not be instantiated

operator= methods:

these methods are omitted because Console objects can not be instantiated

i/o methods:

these methods are omitted because Console objects can not be instantiated

equality methods:

these methods are omitted because Console objects can not be instantiated

memory management methods:

these methods are omitted because Console objects can not be instantiated

class-specific public methods

open methods: automatically push the old console down the stack

static boolean open(const unichar* filename, MODE mode = File::APPEND_ONLY);

static boolean open(const SysString& filename, MODE mode = File::APPEND_ONLY);

static boolean open(STREAM stream = DEF_STREAM);

close methods: close one or all consoles in the stack
```
static boolean close();
```
```
static boolean closeStack();
```

put methods: display a message to the console

static boolean put(const unichar* str);

static boolean put(const SysString& str);

put methods: display a message to the console without line wrapping

static boolean putNoWrap(const unichar* str);

static boolean putNoWrap(const SysString& str);

broadcast methods: display a message to ALL open consoles

static boolean broadcast(const unichar* str);

static boolean broadcast(const SysString& str);

increase/decrease indention level

static boolean increaseIndention();

static boolean decreaseIndention();

line wrapping

static boolean setLineWrap(long num_cols);

static long getLineLength();

static long getLineWrap();

private methods:

declare the destructor/constructor(s): these are private so the class cannot be instantiated

~Console();

Console();

Console(const Console& arg);

stack operation methods: these methods manipulate the console stack
```
static boolean push(File& arg);
```
```
static boolean pop(File& arg);
```

examples:

This example shows how to output messages to Console and change the indention:

#include <Console.h>

int main() {
  
  // set the line wrap and output a message
  //
  Console::setLineWrap(50);
  Console::put(L"Start");
  
  // increase the indentation and output a message
  //
  Console::increaseIndention();       
  Console::put(L"after indentation");
 
  // set it back to no indention and output a message
  //
  Console::decreaseIndention();
  Console::put(L"End");
  
  // exit gracefully
  //
  Integral::exit();
}

notes:

Generally, the debug method is non-static, but here it *must* be static so that the class can be called without being instantiated. There are also no memory management or i/o methods for this class.
When the open method is called, a new console is opened and this will automatically push all old consoles down the stack. The put method is commonly used for quick dispersal of information about the program flow to the standard output device.