[#1471] API Add programmatic way to configure TraceLevel

* add static method CommandLine.tracer()
* make nested enum TraceLevel public, add javadoc
* make nested class Tracer public, add javadoc
* replace calls to `new Tracer()` with `CommandLine.tracer()`
* internally add trailing newline after trace message
* remove trailing newline from caller sites
* update RELEASE-NOTES
* update user manual

Closes #1471

RELEASE-NOTES.md

@@ -18,8 +18,35 @@ Artifacts in this release are signed by Remko Popma (6601 E5C0 8DCC BB96).
 
 ## <a name="4.7.0-new"></a> New and Noteworthy
 
+### Tracing API
+From picocli 4.7.0, applications can programmatically set the trace level, and use tracing in custom components.
+
+In addition to setting system property `picocli.trace`, applications can now change the trace level via the `Tracer::setLevel` method. For example:
+
+```java
+CommandLine.tracer().setLevel(CommandLine.TraceLevel.INFO);
+```
+
+The new public method `CommandLine.tracer()` returns the singleton `Tracer` object that is used internally by picocli, and can also be used by custom component implementations to do tracing. For example:
+
+```java
+class MyIntConverter implements ITypeConverter<Integer> {
+    public Integer convert(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException ex) {
+            CommandLine.tracer().info(
+                    "Could not convert %s to Integer, returning default value -1", value);
+            return -1;
+        }
+    }
+}
+```
+
+
 
 ## <a name="4.7.0-fixes"></a> Fixed issues
+* [#1471] API: Provide a programmatic way to configure Picocli's `TraceLevel`. Thanks to [ekinano](https://github.com/ekinano) for raising this.
 * [#1396][#1401] API: Support generic types in containers (e.g. List, Map). Thanks to [Michał Górniewski](https://github.com/mgorniew) for the pull request.
 * [#1380][#1505] API, bugfix: `requiredOptionMarker` should not be displayed on `ArgGroup` options. Thanks to [Ahmed El Khalifa](https://github.com/ahmede41) for the pull request.
 * [#1563] API: Add constructor to `PicocliSpringFactory` to allow custom fallback `IFactory`. Thanks to [Andrew Holland](https://github.com/a1dutch) for raising this.

docs/index.adoc

@@ -12057,18 +12057,21 @@ From 4.0, the picocli JAR is an OSGi bundle with `Bundle-Name: picocli` and othe
 == Tracing
 Picocli 1.0 introduced support for parser tracing to facilitate troubleshooting.
 
-System property `picocli.trace` controls the trace level. Supported levels are `OFF`, `WARN`, `INFO`, and `DEBUG`. The default trace level is `WARN`.
-
-Specifying system property `-Dpicocli.trace` without a value will set the trace level to `INFO`.
+Supported levels are `OFF`, `WARN`, `INFO`, and `DEBUG`. The default trace level is `WARN`.
 
 * DEBUG: Shows details of the decisions made by the parser during command line parsing.
 * INFO: Shows a high-level overview of what happens during command line parsing.
 * WARN: The default. Shows warnings instead of errors when lenient parsing is enabled:
- when single-value options were specified multiple times (and `CommandLine.overwrittenOptionsAllowed` is `true`),
- or when command line arguments could not be matched as an option or positional parameter
- (and `CommandLine.unmatchedArgumentsAllowed` is `true`).
+when single-value options were specified multiple times (and `CommandLine.overwrittenOptionsAllowed` is `true`),
+or when command line arguments could not be matched as an option or positional parameter
+(and `CommandLine.unmatchedArgumentsAllowed` is `true`).
 * OFF: Suppresses all tracing including warnings.
 
+=== Trace Level via System Property
+System property `picocli.trace` can be used to control the trace level.
+
+Specifying system property `-Dpicocli.trace` without a value will set the trace level to `INFO`.
+
 Example:
 
 [source,bash]
@@ -12094,6 +12097,33 @@ Output:
 [picocli INFO] Adding [src3.java] to List<String> field 'GitCommit.files' for args[0..*]
 ----
 
+=== Tracer API
+
+From picocli 4.7.0, applications can programmatically set the trace level, and use tracing in custom components.
+
+In addition to setting system property `picocli.trace`, applications can now change the trace level via the `Tracer::setLevel` method. For example:
+
+```java
+CommandLine.tracer().setLevel(CommandLine.TraceLevel.INFO);
+```
+
+The new public method `CommandLine.tracer()` returns the singleton `Tracer` object that is used internally by picocli, and can also be used by custom component implementations to do tracing. For example:
+
+```java
+class MyIntConverter implements ITypeConverter<Integer> {
+    public Integer convert(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException ex) {
+            CommandLine.tracer().info(
+                    "Could not convert %s to Integer, returning default value -1", value);
+            return -1;
+        }
+    }
+}
+```
+
+
 == TAB Autocomplete
 Picocli-based applications can now have command line completion in Bash or Zsh Unix shells.
 See the link:autocomplete.html[Autocomplete for Java Command Line Applications] manual for how to generate an autocompletion script tailored to your application.