{"id":20155952,"url":"https://github.com/minecrell/terminalconsoleappender","last_synced_at":"2025-04-09T22:20:38.989Z","repository":{"id":48638609,"uuid":"87849570","full_name":"Minecrell/TerminalConsoleAppender","owner":"Minecrell","description":"JLine 3 appender for Log4j2, allows extending command line apps using colors and command completion","archived":false,"fork":false,"pushed_at":"2023-11-18T00:55:27.000Z","size":320,"stargazers_count":75,"open_issues_count":3,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-24T00:12:03.232Z","etag":null,"topics":["ansi-colors","command-history","console","jline","log4j","log4j2","log4j2-appender","terminal"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Minecrell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-10T19:27:50.000Z","updated_at":"2025-03-12T08:04:02.000Z","dependencies_parsed_at":"2022-09-07T23:52:02.138Z","dependency_job_id":null,"html_url":"https://github.com/Minecrell/TerminalConsoleAppender","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Minecrell%2FTerminalConsoleAppender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Minecrell%2FTerminalConsoleAppender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Minecrell%2FTerminalConsoleAppender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Minecrell%2FTerminalConsoleAppender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Minecrell","download_url":"https://codeload.github.com/Minecrell/TerminalConsoleAppender/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248120018,"owners_count":21050876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi-colors","command-history","console","jline","log4j","log4j2","log4j2-appender","terminal"],"created_at":"2024-11-13T23:36:53.558Z","updated_at":"2025-04-09T22:20:38.964Z","avatar_url":"https://github.com/Minecrell.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TerminalConsoleAppender\nTerminalConsoleAppender is a custom [Log4j2 Appender] that prints all messages to a [JLine 3 Terminal]. JLine can be\nused to extend the regular console using ANSI colors as well as command history or command completion.\n\n## Supported environments\nNot all environments can support all the features. By default, TerminalConsoleAppender only enables JLine output and\nconsole colors when running in an environment with an attached terminal session (so usually only when starting the\napplication from an interactive console session). It will automatically disable the features if the console output is\nredirected to a file or to another application (e.g. in web control panels).\n\nSome unsupported environments may still support a subset of the features (e.g. ANSI console colors). In these cases,\nextra system properties exist to override the default behaviour. They can be added on the command line or in the\napplication itself:\n\n| Name | Description |\n| ---- | ----------- |\n| `-Dterminal.jline=\u003ctrue/false\u003e` | Enables/disables the extended JLine input (persistent input line, command completion) |\n| `-Dterminal.ansi=\u003ctrue/false\u003e` | Enables/disables the output of ANSI escapes codes (used for colors) |\n| `-Dterminal.keepMinecraftFormatting=true` | Output raw Minecraft formatting codes to the console output. |\n\n## Usage\n1. Add a dependency on TerminalConsoleAppender:\n\n    ```\n    net.minecrell:terminalconsoleappender:1.3.0\n    ```\n\n    If you package all dependencies into a single JAR file, ensure that all transitive dependencies are included:\n\n    ```\n    org.jline:jline-terminal\n    org.jline:jline-reader\n    ```\n\n    JLine 3 provides different native terminal implementations that are required for Windows support and extend the terminal\n    with some advanced features on Linux. You can choose between [JNA] and [Jansi]. There should be no functional difference,\n    so it is mostly a matter of preference.\n\n    For full functionality, you need to add an explicit dependency on one of the terminal implementations:\n\n    |      | [Jansi]  | [JNA]     |\n    | ---: | ------ | ------- |\n    | **Dependencies** | `org.jline:jline-terminal-jansi:3.20.0` | `org.jline:jline-terminal-jna:3.20.0` |\n    | | (`org.fusesource.jansi:jansi`) | (`net.java.dev.jna:jna`) |\n    | **Size** | ~280KB | ~1400KB |\n\n2. Configure `TerminalConsoleAppender` in your Log4j configuration:\n\n    ```xml\n    \u003cTerminalConsole name=\"Console\"\u003e\n        \u003cPatternLayout pattern=\"[%d{HH:mm:ss} %level]: %msg%n\"/\u003e\n    \u003c/TerminalConsole\u003e\n    ```\n\n    The `TerminalConsole` appender replaces the regular `Console` appender in your configuration file.\n\n    **Note:** To avoid JLine from blocking your application in some edge cases, it is recommended that you make use of\n    [Async Loggers](https://logging.apache.org/log4j/2.x/manual/async.html) or\n    [Async Appenders](https://logging.apache.org/log4j/2.x/manual/appenders.html#AsyncAppender) to write messages\n    asynchronously.\n\n### Console input\nThe appender is designed to be used in an application with simultaneous input and output. JLine can extend your console\nwith a persistent input line as well as command history and command completion.\n\nTerminalConsoleAppender includes `SimpleTerminalConsole` as a base class handling console input\nwith opinionated defaults. It also serves as a reference implementation if you would like to\nhave a custom implementation.\n\nTo use it, extend `SimpleTerminalConsole` and implement the methods:\n\n```java\npublic class ExampleConsole extends SimpleTerminalConsole {\n\n    @Override\n    protected boolean isRunning() {\n        // TODO: Return true if your application is still running\n    }\n\n    @Override\n    protected void runCommand(String command) {\n        // TODO: Run command\n    }\n\n    @Override\n    protected void shutdown() {\n        // TODO: Shutdown your application cleanly (e.g. because CTRL+C was pressed)\n    }\n    \n}\n```\n\nYou can then start reading commands. Note that this method won't return unless your application\nis stopping or an error occurred, so you should start it in a separate console thread.\n\n```java\nnew ExampleConsole().start();\n```\n\nThis setup will automatically handle the persistent input line and command history for you. If you'd like to use\ncommand completion you need to implement JLine's `Completer` interface (or use one of the builtin completers).\nYou can then set it using `.completer(Completer)` when building the `LineReader`.\n\nOverride the `buildReader` method in your `ExampleConsole` to set additional options:\n\n```java\n    @Override\n    protected LineReader buildReader(LineReaderBuilder builder) {\n        return super.buildReader(builder\n                .appName(\"Example\") // TODO: Replace with your application name\n                .completer(new ExampleCommandCompleter())\n        );\n    }\n```\n\nIf you'd like to use a custom console input implementation, take a look at the\n[source code of `SimpleTerminalConsole`](https://github.com/Minecrell/TerminalConsoleAppender/blob/master/src/main/java/net/minecrell/terminalconsole/SimpleTerminalConsole.java)\nto see how it works (as the name says, it's pretty simple!).\n\n### Colorizing console output\nJLine will automatically render ANSI color escape codes in supported terminals under Windows, Mac and Linux.\nTo use them, you need to instruct Log4j to insert them into log messages:\n\n- You can use the [patterns included in Log4j](https://logging.apache.org/log4j/2.x/manual/layouts.html#Patterns)\n  in your `PatternLayout`, e.g. `%highlight` or `%style`. It is recommended to use the `disableAnsi` option\n  together with the `${tca:disableAnsi}` variable. This will ensure that ANSI colors are disabled automatically in\n  unsupported environments or with the system properties mentioned above:\n\n  ```xml\n  \u003cTerminalConsole\u003e\n      \u003cPatternLayout pattern=\"%highlight{[%d{HH:mm:ss} %level]: %msg%n%xEx}\" disableAnsi=\"${tca:disableAnsi}\"/\u003e\n  \u003c/TerminalConsole\u003e\n  ```\n\n- You can use the simplified `%highlightError` pattern bundled with TerminalConsoleAppender. It will only mark\n  errors red and warnings yellow and keep all other messages as-is. It will automatically disable itself\n  in unsupported environments.\n\n  ```xml\n  \u003cTerminalConsole\u003e\n      \u003cPatternLayout pattern=\"%highlightError{[%d{HH:mm:ss} %level]: %msg%n%xEx}\"/\u003e\n  \u003c/TerminalConsole\u003e\n  ```\n\n- You can [implement custom `PatternConverter`s](https://logging.apache.org/log4j/2.x/manual/extending.html#PatternConverters)\n  that add colors to the logging output. TerminalConsoleAppender contains \n  [an example implementation](https://github.com/Minecrell/TerminalConsoleAppender/blob/master/src/main/java/net/minecrell/terminalconsole/MinecraftFormattingConverter.java)\n  for [Minecraft formatting codes](http://minecraft.gamepedia.com/Formatting_codes) that replaces them with appropriate\n  ANSI colors:\n\n  ```xml\n  \u003cTerminalConsole\u003e\n      \u003cPatternLayout pattern=\"[%d{HH:mm:ss} %level]: %minecraftFormatting{%msg}%n\"/\u003e\n  \u003c/TerminalConsole\u003e\n  ```\n\n  It can be also configured with the `strip` option to strip all formatting codes instead (e.g. for the log file):\n\n  ```xml\n  \u003cTerminalConsole\u003e\n      \u003cPatternLayout pattern=\"[%d{HH:mm:ss} %level]: %minecraftFormatting{%msg}{strip}%n\"/\u003e\n  \u003c/TerminalConsole\u003e\n  ```\n  \n  **NOTE:** The MinecraftFormattingConverter is deprecated and may be removed in future versions of\n  TerminalConsoleAppender. There are no plans to extend it with new features like RGB color codes.\n  Please see [issue #18](https://github.com/Minecrell/TerminalConsoleAppender/issues/18) for details.\n\n[Log4j2 Appender]: https://logging.apache.org/log4j/2.x/manual/appenders.html\n[JLine 3 Terminal]: https://github.com/jline/jline3\n[JNA]: https://github.com/java-native-access/jna\n[Jansi]: https://github.com/fusesource/jansi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminecrell%2Fterminalconsoleappender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminecrell%2Fterminalconsoleappender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminecrell%2Fterminalconsoleappender/lists"}