= Output =

== Description ==

In Orxonox, we don't use {{{std::cout}}} or {{{printf}}} for output, instead we use orxout(). orxout() is a function which can be used almost like std::cout, but adds a level and an optional context to the output. Each output message is then sent to the console, the log-file and the in-game-shell.

The user can set the desired maximal output levels for every device (console, logfile, shell) in the [wiki:howto/ConfigValue config file] in the "Output" section.

== Possible arguments ==

 * '''orxout()''': Acts like std::cout, used for debug output.
 * '''orxout('''''level''''')''': Defines a level for the output
 * '''orxout('''''level'', ''context''''')''': Defines a level and a context for the output

== Levels ==

Levels are used to define the meaning and the importance of an output message.

See the [https://www.orxonox.net/jenkins/view/Management/job/orxonox_doxygen_trunk/javadoc/namespaceorxonox_1_1level.html doxygen page] or util/OutputDefinitions.h for a list of all output levels.

Each level has a different meaning and a different priority. The {{{user_*}}} levels are used to provide the user with (sparse) information about the program's state. The {{{internal_*}}} levels are usually only visible in the log-file and are used by developers. The {{{verbose_*}}} levels are usually not visible (not even in the log-file) and are only activated in rare cases (debugging).

The {{{*_error}}} levels are used for (unrecoverable) errors, while {{{*_warning}}} levels are used for (solvable, but not breaking) problems. {{{*_status}}} levels are used to log the program's state and {{{*_info}}} provides some additional information about this state.

== Contexts ==

Contexts give additional information about the part of the program that generated the output message. Contexts are basically just strings, which means they are identified by their name. It's possible to activate verbose output of only one context which allows debugging of specific parts of the program without being flooded with thousands of unrelated output messages.

Most contexts are defined in [https://www.orxonox.net/jenkins/view/Management/job/orxonox_doxygen_trunk/javadoc/_output_definitions_8h.html util/OutputDefinitions.h], but there might exist more in different locations.

== Examples ==

{{{
#!cpp
#include "util/Output.h"

orxout(internal_info) << "Start executing the function..." << endl;

bool success = functionWithAMeaningfulReturnValue(params);

orxout(internal_info) << "...finished executing the function." << endl;


if (success)
    orxout(user_info) << "The execution of the function was successful." << endl;
else
    orxout(user_error) << "The execution of the function failed." << endl;
}}}

{{{
#!cpp
namespace
{
    REGISTER_OUTPUT_CONTEXT(test);
}

orxout(verbose, context::test) << "This is some verbose output with 'test' context" << endl;
}}}