Attention: In respect to the C++ Version of ALox, this manual is outdated. C++ Users, please visit ALib C++ Library.
The deep-link (we hope this still works, otherwise please quickly find it yourself from the above library link above) should be this.

Using ALox

01 - About ALox
02 - Features and Limitations
03 - Terminology and Key Concepts
04 - Log Domains
05 - Scopes in ALox
06 - Lox.Once()
07 - Prefix Logables
08 - Log Data (Debug Variables)
09 - Multi-Threaded Processes
10 - Differences of Debug- and Release-Logging
11 - Internal Logging
12 - External Configuration
13 - External Verbosity Configuration
14 - Trimming Source File Paths and Clickable IDE Output
15 - Log Domain Substitution
16 - Colorful Loggers

Reference Appendix

I - Configuration Variables
II - ALox Auto-Configuration and Orthogonality

Extending ALox

A - Loggers and Implementing Custom Types

Notes

This is the manual of the ALox Logging Ecosystem. This manual applies to all platforms and programming languages that ALox supports. By nature, the different implementations of ALox written in different programming languages, differ. Sometimes in details, sometimes differences are more than that.

As a matter of fact, this manual provides a more abstract and high level view on ALox. Such general understanding of the ALox architecture and design concepts, might be important to maximize the use of ALox.

If you have not worked with ALox, yet, and have not read one of the tutorials, we highly recommend to walk through one of the language specific tutorials found in the corresponding programming language specific documentation first. There, you also might find information on how to setup up ALox projects for the platform you are using. The language specific documentation is always reachable through the main menu of this book (above). They are:

Orthogonality of ALox and its API:
Reading this manual, you will see that some topics might become a little complex, maybe more complex than what you might expect from a logging framework that you probably just want to use for rather 'simple' debug-logging.
The good news is that ALox' features and API is design are to a high degree 'orthogonal'. Orthogonality in API design means that features that you do not use, do not know and that you might not be even interested in, are not even visible when using ALox. This is mainly reached by three things:

Simplified method invocations by omitting all optional parameters (in Java overloaded methods omitting these parameters)
Reasonable default values for optional parameters
Automatic internal prerequisites when ALox 'detects' that a feature is not used.

This way, you can use ALox in an extremely simple way, just as if ALox was extremely simple. And maybe just over time, you start reading this book and go into details that you need to conquer a next, more complex use case. For productively using ALox, the tutorials should do!

Differences of ALox for C++, C# and Java:
As ALox is available for C++, C# and Java, the class and member names within this document may vary a little per language. Fore example, class Log does not provide a mirrored version of the interface of class Lox in C++ as it has in C# and Java versions of ALox, where this is used for pruning exactly this interface out of release code. In contrast, in C++ the macros Log_xxx and Lox_xxx are used to provide pruned and non-pruned access to methods of class Lox. Which means an underscore in C++ '_' replaces a dot '.' in Java/C#.

Also, in Java, interface methods generally start with a non-capital letter, while in C# and C++ the same method starts with a capital one. Please remember, that such details are not an error in the user manual, but we have just decided not to hint to this fact all of the time.

Wherever reasonable, language specific differences are named and briefly explained.

Documentation of ALib:

General purpose classes (aka those that are not directly related to logging) are collected under the name ALib. As the standard C++ class library is far less complete than the .Net and Java class libraries, "ALib For C++" had to be much richer than the other language versions. Historically, a goal of the C++ version was to provide a sort of "compatibility layer", hence to mimic C# and Java classes in C++.

Since release version 1805 however, the C++ version of ALib has been launched as an own project. With this launch, "ALox for C++" became a part of "ALib for C++". It could be said, that the relationship between ALib and ALox has been reversed in that language version!

Consequently, all C++ source code including that of "ALox for C++" has been moved to this project which includes all reference documentation of ALib and ALox.

For C# and Java, underlying class library ALib does not provide an own project site and user manual. It is exclusively published as a part of the ALox project.

While for the C++ version, various Programmer's Manuals for ALib Modules exist, for C# and Java, only reference manuals are given. Those are:

[com::|cs::]aworx::lib (C#, Java)
[com::|cs::]aworx::lib::config (C#, Java)
[com::|cs::]aworx::lib::util (C#, Java)
[com::|cs::]aworx::lib::lang (C#, Java)
[com::|cs::]aworx::lib::strings (C#, Java)
[com::|cs::]aworx::lib::threads (C#, Java)
[com::|cs::]aworx::lib::time (C#, Java)

For advanced users of ALox, reading and understanding the types provided with namespaces config (C++, C#, Java) and strings (C++, C#, Java) is very recommended.