smjg.libs.util.console

The smjg.libs.util.console module provides a means of communicating with the standard input and output streams.

It is designed to provide the following benefits over stream classes in Phobos:

* At this time of writing, programs compiled with DMD2 don't run under Win9x, but the code of relevance is still there just in case.

The application programmer would use this module by means of the cIn, cOut and cErr objects.

This is not intended to be a sophisticated text I/O library.

Any application that uses this module should use it consistently throughout if possible. This ensures that the EOF fix works correctly and prevents buffering conflicts between different I/O libraries/APIs.

Since:
0.03
Todo:
implement error checking (not sure how much is needed)
class ConsoleInput;

The ConsoleInput class is used to receive text from the standard input.

This class buffers input on a line-by-line basis.

dchar readChar();

Reads a single Unicode character from the input stream.

Returns:
the character retrieved, or dchar.init on EOF.
void discardLine();

Discards the currently buffered line of input.

The next call to readChar, readLine or eof will therefore wait for a line of input from the user and use it.

If no text is waiting in the buffer, this function has no effect.
@property size_t bytesInBuffer();

The number of UTF-8 bytes currently waiting in the internal buffer.

For as long as this property returns non-zero, input operations will be non-blocking.

@property size_t bytesInLine();

The number of UTF-8 bytes remaining on the current line of input.

This differs from bytesInBuffer in that the count doesn't include any terminating newline. But it isn't equivalent to bytesInBuffer - 1: if the buffer is empty, or the input stream has been buffered to EOF without a final newline, then both properties will return the same value.

@property size_t charsInBuffer();

The number of characters currently waiting in the internal buffer.

@property size_t charsInLine();

The number of characters remaining on the current line of input.

char[] readLine(bool withNewLine = false);

Reads a line of text from the input stream.

Params:
bool withNewLine whether to include in the returned string the terminating newline if it is present.
Returns:
the line retrieved, or \c null on EOF.
@property bool eof();

Determines whether EOF of the input stream has been reached.

This function also reads a line of input into the buffer if it is empty and there is any input to read. Therefore, it will wait for the user to input a line if one isn't already available.

Returns:
true if the end of the input has been reached and the buffer is empty, otherwise false.
class ConsoleOutput;

The ConsoleOutput class used to write out text to the standard output and error streams.

This class buffers any incomplete UTF-8 characters that are passed into it. This makes it suited to applications that transmit UTF-8 text one byte at a time, or in chunks whose boundaries may not coincide with character boundaries. It is the application's responsibility to ensure that the sequence of strings written constitutes well-formed UTF-8 text.

void write(dchar c);

Writes out the Unicode character c.

Precondition:
There must be no partial UTF-8 characters remaining in the buffer.
void write(const(char)[] c);

Writes out the string c.

void writeLine(const(char)[] c);

Writes out the string c followed by a newline.

void writef(S...)(S args);
void writefln(S...)(S args);

Performs formatted output on the stream.

deprecated void writefx(TypeInfo[] arguments, void* argptr, bool newline = false);
Deprecated:
designed for the old std.string.doFormat way of doing things; use writef/writefln instead.
void flush();

Makes sure all pending output has actually been output.

ConsoleInput cIn;

The standard input stream.

ConsoleOutput cOut;

The standard output stream.

ConsoleOutput cErr;

The standard error stream.

class ConsoleException: object.Exception;

Exception thrown when a console I/O operation fails.

Page generated by Ddoc.