<commit_before>/*! @page iodoc mlpack Input and Output

@section iointro Introduction

mlpack provides the following:

 - mlpack::Log, for debugging / informational / warning / fatal output
 - mlpack::CLI, for parsing command line options

Each of those classes are well-documented, and that documentation should be
consulted for further reference.

@section simplelog Simple Logging Example

mlpack has four logging levels:

 - Log::Debug
 - Log::Info
 - Log::Warn
 - Log::Fatal

Output to Log::Debug does not show (and has no performance penalty) when mlpack 
is compiled without debugging symbols.  Output to Log::Info is only shown when
the program is run with the --verbose (or -v) flag.  Log::Warn is always shown,
and Log::Fatal will throw a std::runtime_error exception, when a newline is sent
to it only. If mlpack was compiled with debugging symbols, Log::Fatal will
always throw a std::runtime_error exception and print backtrace.

Here is a simple example, and its output:

@code
#include <mlpack/core.hpp>

using namespace mlpack;

int main(int argc, char** argv)
{
  CLI::ParseCommandLine(argc, argv);

  Log::Debug << "Compiled with debugging symbols." << std::endl;

  Log::Info << "Some test informational output." << std::endl;

  Log::Warn << "A warning!" << std::endl;

  Log::Fatal << "Program has crashed." << std::endl;

  Log::Warn << "Made it!" << std::endl;
}
@endcode

With debugging output--verbose, the following is shown:

@code
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] [bt]: (1) /absolute/path/to/file/example.cpp:main:6
[FATAL] Program has crashed.
terminate called after throwing an instance of 'std::runtime_error'
  what():  fatal error; see Log::Fatal output
Aborted
@endcode

With debugging output, compilation flags -g -rdynamic and --verbose,
the following is shown:

@code
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] Cannot give backtrace because program was compiled without: -g -rdynamic
[FATAL] For a backtrace, recompile with: -g -rdynamic.
[FATAL] Program has crashed.
terminate called after throwing an instance of 'std::runtime_error'
  what():  fatal error; see Log::Fatal output
Aborted
@endcode

The last warning is not reached, because Log::Fatal terminates the program.

Without debugging symbols and without --verbose, the following is shown:

@code
$ ./main
[WARN ] A warning!
[FATAL] Program has crashed.<commit_msg>Change order in printing backtrace<commit_after>/*! @page iodoc mlpack Input and Output

@section iointro Introduction

mlpack provides the following:

 - mlpack::Log, for debugging / informational / warning / fatal output
 - mlpack::CLI, for parsing command line options

Each of those classes are well-documented, and that documentation should be
consulted for further reference.

@section simplelog Simple Logging Example

mlpack has four logging levels:

 - Log::Debug
 - Log::Info
 - Log::Warn
 - Log::Fatal

Output to Log::Debug does not show (and has no performance penalty) when mlpack 
is compiled without debugging symbols.  Output to Log::Info is only shown when
the program is run with the --verbose (or -v) flag.  Log::Warn is always shown,
and Log::Fatal will throw a std::runtime_error exception, when a newline is sent
to it only. If mlpack was compiled with debugging symbols, Log::Fatal will
always throw a std::runtime_error exception and print backtrace.

Here is a simple example, and its output:

@code
#include <mlpack/core.hpp>

using namespace mlpack;

int main(int argc, char** argv)
{
  CLI::ParseCommandLine(argc, argv);

  Log::Debug << "Compiled with debugging symbols." << std::endl;

  Log::Info << "Some test informational output." << std::endl;

  Log::Warn << "A warning!" << std::endl;

  Log::Fatal << "Program has crashed." << std::endl;

  Log::Warn << "Made it!" << std::endl;
}
@endcode

With debugging output--verbose, the following is shown:

@code
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] [bt]: (1) /absolute/path/to/file/example.cpp:6: function()
[FATAL] Program has crashed.
terminate called after throwing an instance of 'std::runtime_error'
  what():  fatal error; see Log::Fatal output
Aborted
@endcode

With debugging output, compilation flags -g -rdynamic and --verbose,
the following is shown:

@code
[DEBUG] Compiled with debugging symbols.
[INFO ] Some test informational output.
[WARN ] A warning!
[FATAL] Cannot give backtrace because program was compiled without: -g -rdynamic
[FATAL] For a backtrace, recompile with: -g -rdynamic.
[FATAL] Program has crashed.
terminate called after throwing an instance of 'std::runtime_error'
  what():  fatal error; see Log::Fatal output
Aborted
@endcode

The last warning is not reached, because Log::Fatal terminates the program.

Without debugging symbols and without --verbose, the following is shown:

@code
$ ./main
[WARN ] A warning!
[FATAL] Program has crashed.
{'fraction_non_alphanumeric': 0.10055643879173291, 'fraction_numerical': 0.000794912559618442, 'mean_word_length': 4.6171875, 'pattern_counts': {'":': 0, '<': 45, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4780832', 'n_tokens_mistral': 1482, 'n_tokens_neox': 1427, 'n_words': 636}