/**
\defgroup fcpptlog fcppt.log
\ingroup fcpptmain
\brief Logging classes and functions

<b>Link to <code>${fcppt_log_TARGET}</code>,
or to <code>fcppt_log_interface</code> if you only need the headers.</b>

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref log_introduction</li>
		<ul>
			<li>\ref log_simple_example</li>
		</ul>
	<li>\ref log_formatting_and_sinks</li>
	<li>\ref log_hierarchy</li>
		<ul>
			<li>\ref log_hierarchy_design</li>
			<li>\ref log_hierarchy_example</li>
		</ul>
	<li>\ref log_threads</li>
	<li>\ref log_headers</li>
</ul>

</td>
</tr>
</table>

\section log_introduction Introduction

The following list highlights the main features of fcppt's logging library:

<dl>
<dt>Configuration of enabled output:</dt>

<dd>The library assigns <em>log levels</em> to <em>log locations</em>, which is
stored by a <em>log context</em>. Log levels are, for example, <code>debug,
warning, error</code> and log locations are lists of strings.
</dd>

<dt>Formatting and direction of messages:</dt>

<dd>A <em>log context</em> also assigns to each <em>log level</em> a <em>level
stream</em>, which dictates where to log to, e.g. to <code>std::clog</code>,
and how messages are formatted.
</dd>

</dl>

\subsection log_simple_example A simple example

The class that does actual logging is called #fcppt::log::object. It
refers to an #fcppt::log::location in a #fcppt::log::context.
The following example illustrates the use of a simple log object:

\snippet log/helloworld.cpp helloworld

Logging is done via the #fcppt::log::object::log  element
function. The macro #FCPPT_LOG_DEBUG is a short-hand for logging
only if the debug log level is enabled. This is important because the
construction of the log message is avoided altogether when debug is not
enabled.

#fcppt::log::out  is an object that basically acts like
a <code>std::basic_ostream</code>. This is used to
create a whole message in a thread-safe manner. If you log in multiple pieces
instead, the log message might end up interleaved with other messages.

\section log_formatting_and_sinks Formatting and sinks

A log context contains an #fcppt::log::level_stream for every
log level. Each of them controls where output is written to and how it is
formatted.

\section log_hierarchy Log hierarchy

Controlling at runtime which messages are logged is very important. Under
normal circumstances, you probably want to only log serious problems, while in
a debug scenario a lot of debug messages should be logged.

\subsection log_hierarchy_design Log hierarchy design

A location is a list of <code>fcppt::log::name</code> values, e.g.
<code>{"my_lib", "my_subsystem"}</code>.
An #fcppt::log::context  associates locations with
#fcppt::log::optional_level values. These can be configured through
the #fcppt::log::context::set function, even before any log objects
are created. This is useful, for example, for specifying log levels on the
command line.

Each log object refers to a location of a given context.
In its constructor, it gets a name, and in addition to that, it gets either
<ul>
<li>a log context, in which case its location is its name,</li>
<li>a log context and a location, in which case its location is the given location plus its name, or</li>
<li>a parent log object, in which case its location is the parent's location plus its own name.</li>
</ul>

\subsection log_hierarchy_example Log hierarchy example

The next example shows how log objects, contexts and locations can be used
together.

The log context gets a single #fcppt::log::optional_level as its
parameter, which is used as a default for every location, unless changed.

\snippet log/context.cpp declare_context

We declare a root object with name <code>"root"</code>. Its location will be
<code>{"root"}</code>.

\snippet log/context.cpp declare_root_logger

The child object gets the name <code>"child"</code> and the root object passed
to its constructor, thus its location is <code>{"root", "child"}</code>.

\snippet log/context.cpp declare_child_logger

As mentioned earlier, the locations inherit the root level of the context, so
every log object currently has the debug level and all levels above enabled: The
log location given to a log object implicitly changes how its output is formatted:

\snippet log/context.cpp log_debug

The first statement will print <code>root: warning: Print from root.</code> and
the second statement will print <code>root: child: warning: Print from
child.</code>

The #fcppt::log::context::set function can be used to change the
level of a location at runtime.

\snippet log/context.cpp context_set

Here we change the child location to only have the warning level and every
level above enabled, so the following output is not printed:

\snippet log/context.cpp log_info

Note that changing the level at a location also changes the levels below
it. We can change the root level back to debug which will also affect the child
level:

\snippet log/context.cpp context_set2

Passing an empty optional log level disables all levels.

\section log_threads Thread safety

The log context contains a mutex to protect its internal structure from race conditions.
Therefore, calling element functions of a log context from multiple threads is safe.
Log objects can be used in different threads than the log context. However, sharing
a log object between different threads is not safe.

\section log_headers Header files
All headers are relative to the log subdirectory.

\subsection log_headers_essential Essential header files
<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>out.hpp</code></td>
<td>Contains #fcppt::log::out .</td>
</tr>
<tr>
<td><code>context_fwd.hpp</code></td>
<td>Contains #fcppt::log::context 's declaration.</td>
</tr>
<tr>
<td><code>context.hpp</code></td>
<td>Contains #fcppt::log::context 's definition.</td>
</tr>
<tr>
<td><code>debug.hpp</code></td>
<td>Contains the #FCPPT_LOG_DEBUG macro.</td>
</tr>
<tr>
<td><code>error.hpp</code></td>
<td>Contains the #FCPPT_LOG_ERROR macro.</td>
</tr>
<tr>
<td><code>fatal.hpp</code></td>
<td>Contains the #FCPPT_LOG_FATAL macro.</td>
</tr>
<tr>
<td><code>info.hpp</code></td>
<td>Contains the #FCPPT_LOG_INFO macro.</td>
</tr>
<tr>
<td><code>level.hpp</code></td>
<td>Contains the #fcppt::log::level  enumeration.</td>
</tr>
<tr>
<td><code>location_fwd.hpp</code></td>
<td>Contains #fcppt::log::location 's declaration.</td>
</tr>
<tr>
<td><code>location.hpp</code></td>
<td>Contains #fcppt::log::location 's definition.</td>
</tr>
<tr>
<td><code>name_fwd.hpp</code></td>
<td>Contains <code>fcppt::log::name</code>'s declaration.</td>
</tr>
<tr>
<td><code>name.hpp</code></td>
<td>Contains <code>fcppt::log::name</code>'s definition.</td>
</tr>
<tr>
<td><code>object_fwd.hpp</code></td>
<td>Contains #fcppt::log::object 's declaration.</td>
</tr>
<tr>
<td><code>object.hpp</code></td>
<td>Contains #fcppt::log::object 's defintiion.</td>
</tr>
<tr>
<td><code>verbose.hpp</code></td>
<td>Contains the #FCPPT_LOG_VERBOSE macro.</td>
</tr>
<tr>
<td><code>warning.hpp</code></td>
<td>Contains the #FCPPT_LOG_WARNING macro.</td>
</tr>
</table>

\subsection log_headers_helpers Other header files

<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>default_level_streams.hpp</code></td>
<td>Contains #fcppt::log::default_level_streams for construction of all level stream defaults.</td>
</tr>
<tr>
<td><code>default_stream.hpp</code></td>
<td>Contains the #fcppt::log::default_stream function.</td>
</tr>
<tr>
<td><code>level_from_string.hpp</code></td>
<td>Contains #fcppt::log::level_from_string .</td>
</tr>
<tr>
<td><code>level_stream_array.hpp</code></td>
<td>Contains the #fcppt::log::level_stream_array typedef.</td>
</tr>
<tr>
<td><code>level_stream_fwd.hpp</code></td>
<td>Contains #fcppt::log::level_stream 's declaration.</td>
</tr>
<tr>
<td><code>level_stream.hpp</code></td>
<td>Contains #fcppt::log::level_stream 's definition.</td>
</tr>
<tr>
<td><code>level_to_string.hpp</code></td>
<td>Contains #fcppt::log::level_to_string .</td>
</tr>
<tr>
<td><code>optional_level_fwd.hpp</code></td>
<td>Contains the #fcppt::log::optional_level typedef.</td>
</tr>
<tr>
<td><code>optional_level.hpp</code></td>
<td>Includes <code>optional_level_fwd.hpp</code> and optional headers.</td>
</tr>
</table>

*/

namespace fcppt
{
/**
\brief Logging classes and functions
*/
namespace log
{
}
}
