Provides access to the standard input and output streams, and other system facilities. More...

#include <jem/base/System.h>

Public Types
typedef io::Writer	Writer
	A type representing a text output stream. More...

typedef io::Reader	Reader
	A type representing a text input stream. More...

Static Public Member Functions
static Writer &	err ()
	Returns the error output stream. More...

static Writer &	warn ()
	Returns the warning output stream. More...

static Writer &	out ()
	Returns the standard output stream. More...

static Writer &	info ()
	Returns the info output stream. More...

static Writer &	debug ()
	Returns the debug output stream. More...

static Reader &	in ()
	Returns the standard input stream. More...

static void	setErrStream (const Ref< Writer > &w)
	Sets the error output stream. More...

static void	setWarnStream (const Ref< Writer > &w)
	Sets the warning output stream. More...

static void	setOutStream (const Ref< Writer > &w)
	Sets the standard output stream. More...

static void	setInfoStream (const Ref< Writer > &w)
	Sets the info output stream. More...

static void	setDebugStream (const Ref< Writer > &w)
	Sets the debug output stream. More...

static void	setInStream (const Ref< Reader > &r)
	Sets the standard input stream. More...

static String	getProperty (const String &key, const String &defaultValue=String())
	Returns a system-level property. More...

static String	getenv (const String &name, const String &defaultValue=String())
	Returns the contents of a specific environment variable. More...

static int	exec (int(*func)())
	Calls a function and catches all exceptions thrown by that function. More...

static int	exec (int(func)(), int argc, char *argv)
	Calls a function and catches all exceptions thrown by that function. More...

static void	printException (Writer &out, const String &name, const String &where, const String &what)
	Prints a description of an exception. More...

Detailed Description

The System class provides access to various system-level facilities. It can be used to get and set the standard input and output streams; to get information about the system; to get the contents of environment variables; and to catch and print exceptions thrown by the main function of a program.

The System class provides one input stream and five output streams: one for writing error messages; one for writing warnings; one for writing normal output; one for writing non-essential information; and one for writing debugging information. All input and output streams are initialized when they are accessed for the first time.

The input and output streams can be accessed by calling the static member functions in(), err(), warn(), out(), info() and debug(). All these functions return a reference to a io::Reader or io::Writer object. Although these functions are reasonably fast, they may lower the speed of your program if you call them repeatedly within a loop. In these situations you should use a local reference to the input or output stream. Here is an example:

void printNumbers ()
{
  // Store a local reference to the standard output stream
  io::Writer& out = System::out ();
  
  int i;
  for ( i = 0; i < 1000000; i++ )
  {
    out << i << ", ";
  }
}

The input and output streams are local to each thread. That is, each thread may set its own input and output streams. If a thread spawns another thread, the child thread inherits the input and output streams from its parent thread. If the child or parent thread replaces one of these streams, the new stream will only be visible to that thread. The other thread will still `see' the original input and output streams.

All member functions of the System class are thread safe. The default input and output streams are also thread safe.

The System class contains only static members; it should be viewed as a sort of mini namespace.

Member Typedef Documentation

typedef io::Writer jem::System::Writer

The Writer type represents a text output stream. It is simply an alias for the class io::Writer.

typedef io::Reader jem::System::Reader

The Reader type represents a text input stream. It is simply an alias for the class io::Reader.

Member Function Documentation

static Writer& jem::System::err ( )

static

Returns a reference to the error output stream. This reference remains valid until the function setErrStream() is called. The error stream should be used to write messages that indicate critical error conditions.

The default error stream – that is created when this function is called for the first time – writes to the standard error stream provided by the system. This is usual the console from which the program has been started. The default error stream is not buffered.

Returns: A reference to the error stream.

See also: io::FileDescriptor::err()

Examples:: Properties.cpp.

static Writer& jem::System::warn ( )

static

Returns a reference to the warning output stream. This reference remains valid until the function setWarnStream() is called. The warning stream should be used to write messages that indicate non-critical error conditions.

The default warning stream – that is created when this function is called for the first time – is equal to the error stream. That is, warn() returns the same reference as err().

Returns: A reference to the warning stream.

See also: err()

static Writer& jem::System::out ( )

static

Returns a reference to the standard output stream. This reference remains valid until the function setOutStream() is called. The standard output should be used to write messages that should be read by the user of a program.

The default output stream – that is created when this function is called for the first time – writes to the standard output provided by the system. This is usual the console from which the program has been started. The default output stream is line buffered.

Returns: A reference to the standard output stream.

See also: io::FileDescriptor::out(), io::LineBufferedWriter

Examples:: Array.cpp, BitSet.cpp, Database.cpp, DataParser.cpp, Event.cpp, meshgen.cpp, Properties.cpp, String.cpp, System.cpp, and Tuple.cpp.

static Writer& jem::System::info ( )

static

Returns a reference to the info output stream. This reference remains valid until the function setInfoStream() is called. The info stream should be used to write non-essential information.

The default info stream – that is created when this function is called for the first time – simply discards all output. That is, it does not write anything at all.

Returns: A reference to the info stream.

See also: io::NullWriter

static Writer& jem::System::debug ( )

static

Returns a reference to the debug output stream. This reference remains valid until the function setDebugStream() is called. The debug stream should be used to write debugging information.

The default debug stream – that is created when this function is called for the first time – is equal to the default info stream. That is, debug() returns the same reference as info().

Returns: A reference to the debug stream.

See also: info()

static Reader& jem::System::in ( )

static

Returns a reference to the standard input stream. This reference remains valid until the function setInStream() is called.

The default input stream – that is created when this function is called for the first time – reads from the standard input provided by the system. This is usual the console from which the program has been started. The default input stream is synchronized with the default output stream. That is, each time data is read from the standard input stream, the standard output stream is flushed.

Returns: A reference to the standard input stream.

See also: io::FileDescriptor::in(), io::SynchronizedReader

Examples:: Properties.cpp, and System.cpp.

static void jem::System::setErrStream ( const Ref< Writer > & w )

static

Sets the error output stream to the writer w. The new error stream will only be visible to the current thread.

Parameters

w	- the new error output stream.

Precondition: w != NIL

Postcondition: & err() == w

static void jem::System::setWarnStream ( const Ref< Writer > & w )

static

Sets the warning output stream to the writer w. The new warning stream will only be visible to the current thread.

Parameters

w	- the new warning output stream.

Precondition: w != NIL

Postcondition: & warn() == w

static void jem::System::setOutStream ( const Ref< Writer > & w )

static

Sets the standard output stream to the writer w. The new standard output stream will only be visible to the current thread.

Parameters

w	- the new standard output stream.

Precondition: w != NIL

Postcondition: & out() == w

static void jem::System::setInfoStream ( const Ref< Writer > & w )

static

Sets the info output stream to the writer w. The new info stream will only be visible to the current thread.

Parameters

w	- the new info output stream.

Precondition: w != NIL

Postcondition: & info() == w

static void jem::System::setDebugStream ( const Ref< Writer > & w )

static

Sets the debug output stream to the writer w. The new debug stream will only be visible to the current thread.

Parameters

w	- the new debug output stream.

Precondition: w != NIL

Postcondition: & debug() == w

static void jem::System::setInStream ( const Ref< Reader > & r )

static

Sets the standard input stream to the reader r. The new standard input stream will only be visible to the current thread.

Parameters

r	- the new standard input stream.

Precondition: r != NIL

Postcondition: & in() == r

static String jem::System::getProperty	(	const String &	key,
		const String &	defaultValue = `String()`
	)

static

Returns a system-level property associated with the key key. If there is no property associated with the given key, the string defaultValue is returned.

A system-level property is a string that encodes some information about the system. Below is a list of the available properties. The quoted strings denote the keys that are associated with the properties.

"jem.version" - the current version of Jem.
"jem.date" - the date on which this version of Jem has been compiled.
"file.separator" - the character that separates the file name and the file suffix.
"path.separator" - the character that separates the directories in a path name.
"user.name" - the login name of the user that has started the current program.
"user.home" - the home directory of the user that has started the current program.
"host.name" - the name of the host computer.
"os.name" - the name of the operating system running on the host computer.
"os.machine" - a description of the host computer's hardware type.
"os.version" - the operating system version.

The following code fragment shows how to access one of the above properties.

int main ()
{
  System::out() << "Hello "
                << System::getProperty ( "user.name" )
                << ". Have a nice day.\n";
  return 0;
}

Parameters

key	- the key associated with a property.
defaultValue	- the string to be returned if there is no property with the specified key.

Returns: The property associated with the key key, or defaultValue if there is no such property defined.

Examples:: System.cpp.

static String jem::System::getenv	(	const String &	name,
		const String &	defaultValue = `String()`
	)

static

Returns the contents of the environment variable with name name. If there is no such environment variable defined, the string defaultValue is returned.

Parameters

name	- the name of an environment variable.
defaultValue	- the string that is returned if there is no environment variable with the specified name.

Returns: The contents of the environment variable with name name, or the string defaultValue if there is no such environment variable.

static int jem::System::exec ( int(*)() func )

static

Calls the function func and catches all exceptions thrown by that function. For each caught exception a consise report is written to the error output stream.

This function is typically used to call the main function of a program. See the overloaded version of this function for an example.

Parameters

func	- the function to be called.

Returns: If no exception has been caught, the return value of func is returned. Otherwise the value 1 is returned.

Examples:: Array.cpp, BitSet.cpp, Database.cpp, DataParser.cpp, game-of-life.cpp, GzipFileReader.cpp, GzipFileWriter.cpp, meshgen.cpp, Properties.cpp, String.cpp, System.cpp, TextInput.cpp, and Tuple.cpp.

static int jem::System::exec	(	int(*)()	func,
		int	argc,
		char **	argv
	)

static

Calls the function func with the arguments argc and argv, and catches all exceptions thrown by that function. For each caught exception a consise report is written to the error output stream.

This function is typically used to call the main function of a program. Here is an example:

int run ( int argc, char** argv )
{
  System::out() << "You started the program " << argv[0]
                << " with " << argc << " arguments.\n";
  throw Exception ( JEM_FUNC, "Bailing out!" );
  return 0;
}
int main ( int argc, char** argv )
{
  return System::exec ( & run, argc, argv );
}

Parameters

func	- the function to be called.
argc	- the number of command-line parameters.
argv	- the command-line parameters.

Returns: If no exception has been caught, the return value of func is returned. Otherwise the value 1 is returned.

static void jem::System::printException	(	Writer &	out,
		const String &	name,
		const String &	where,
		const String &	what
	)

static

Writes a description of an exception to the output stream out. The input arguments name, where, what specify the name (type) of the exception, the context in which the exception was thrown, and the reason why the exception was thrown, respectively.

Parameters

out	- a text output stream.
name	- the name/type of the exception.
where	- the context in which the exception was thrown.
what	- the reason why the exception was thrown.

See also: Throwable

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation