001package io.jstach.rainbowgum.format;
002
003import io.jstach.rainbowgum.LogFormatter;
004import io.jstach.rainbowgum.LogFormatter.LevelFormatter;
005import io.jstach.rainbowgum.LogFormatter.TimestampFormatter;
006import io.jstach.rainbowgum.annotation.CaseChanging;
007import io.jstach.rainbowgum.annotation.EnumAlias;
008
009/**
010 * The choices for each part of the TTLL (Time, Thread, Level, Logger) format, the default
011 * text format, configured with {@link TTLLFormatterBuilder} or properties of the
012 * {@value #SCHEMA} encoder. Property values are the lowercase constant names, for
013 * example: <pre>
014 * logging.appender.console.encoder.ttll.time=iso
015 * logging.appender.console.encoder.ttll.keyValues=json5
016 * </pre> The defaults produce the classic layout with the event's key values, percent
017 * encoded, in braces after the logger name:
018 * <code>12:00:00.123 [main] INFO  com.example.App {requestId=42} - hello</code>. When an
019 * event has no key values the braces are left out, or written as <code>{}</code>,
020 * according to {@link KeyValuesWhenEmpty}, and {@link KeyValuesFormat#NONE} leaves the
021 * key values out entirely.
022 * <p>
023 * Every part also accepts <code>default</code>, which restores its default without naming
024 * it, and <code>true</code> and <code>false</code> to show or hide it; the
025 * {@link io.jstach.rainbowgum.annotation.EnumAlias} on each constant lists them.
026 */
027public sealed interface TTLL permits TTLLFormatter {
028
029        /**
030         * URI scheme of the TTLL encoder, the default encoder when no other is configured.
031         */
032        String SCHEMA = "ttll";
033
034        /**
035         * Time part. A property value that is not one of these names is used as a
036         * {@link java.time.format.DateTimeFormatter} pattern in UTC, like slf4j-simple's
037         * <code>dateTimeFormat</code>.
038         */
039        @CaseChanging
040        enum TimestampFormat {
041
042                /**
043                 * <code>HH:mm:ss.SSS</code> in UTC. The default.
044                 */
045                @EnumAlias({ "default", "true" })
046                TTLL {
047                        @Override
048                        public LogFormatter formatter() {
049                                return TimestampFormatter.of();
050                        }
051                },
052                /**
053                 * ISO 8601 UTC instant with milliseconds, <code>2026-10-05T12:00:00.123Z</code>.
054                 */
055                ISO {
056                        @Override
057                        public LogFormatter formatter() {
058                                return TimestampFormatter.ofISO();
059                        }
060                },
061                /**
062                 * No time.
063                 */
064                @EnumAlias("false")
065                NONE {
066                        @Override
067                        public LogFormatter formatter() {
068                                return LogFormatter.noop();
069                        }
070                };
071
072                /**
073                 * The formatter for this choice.
074                 * @return formatter.
075                 */
076                public abstract LogFormatter formatter();
077
078                static TimestampFormat parse(String value) {
079                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
080                                case "default", "true" -> TTLL;
081                                case "false" -> NONE;
082                                default -> io.jstach.rainbowgum.LogProperty.enumValue(TimestampFormat.class, value, "true", "false",
083                                                "default");
084                        };
085                }
086
087        }
088
089        /**
090         * Thread part, written in square brackets.
091         */
092        @CaseChanging
093        enum ThreadFormat {
094
095                /**
096                 * Thread name. The default.
097                 */
098                @EnumAlias({ "default", "true" })
099                NAME {
100                        @Override
101                        public LogFormatter formatter() {
102                                return LogFormatter.builder().threadName().build();
103                        }
104                },
105                /**
106                 * Thread id.
107                 */
108                ID {
109                        @Override
110                        public LogFormatter formatter() {
111                                return LogFormatter.builder().threadId().build();
112                        }
113                },
114                /**
115                 * Thread name, or the thread id when the name is empty, as it usually is for a
116                 * virtual thread: <code>[main]</code> or <code>[7]</code>.
117                 */
118                NAME_OR_ID {
119                        @Override
120                        public LogFormatter formatter() {
121                                return (LogFormatter.EventFormatter) (output, event) -> {
122                                        String name = event.threadName();
123                                        if (name.isEmpty()) {
124                                                output.append(event.threadId());
125                                        }
126                                        else {
127                                                output.append(name);
128                                        }
129                                };
130                        }
131                },
132                /**
133                 * Thread id and name, each in its own square brackets: <code>[7][main]</code>.
134                 * The closing and opening bracket between them are part of this formatter, since
135                 * the thread part adds the outer ones.
136                 */
137                BOTH {
138                        @Override
139                        public LogFormatter formatter() {
140                                return LogFormatter.builder().threadId().text("][").threadName().build();
141                        }
142                },
143                /**
144                 * No thread.
145                 */
146                @EnumAlias("false")
147                NONE {
148                        @Override
149                        public LogFormatter formatter() {
150                                return LogFormatter.noop();
151                        }
152                };
153
154                /**
155                 * The formatter for this choice.
156                 * @return formatter.
157                 */
158                public abstract LogFormatter formatter();
159
160                static ThreadFormat parse(String value) {
161                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
162                                case "default", "true" -> NAME;
163                                case "false" -> NONE;
164                                default ->
165                                        io.jstach.rainbowgum.LogProperty.enumValue(ThreadFormat.class, value, "true", "false", "default");
166                        };
167                }
168
169        }
170
171        /**
172         * Level part.
173         */
174        @CaseChanging
175        enum LevelFormat {
176
177                /**
178                 * Upper case, right padded to five characters so messages line up. The default.
179                 */
180                @EnumAlias({ "default", "true" })
181                PADDED {
182                        @Override
183                        public LogFormatter formatter() {
184                                return LevelFormatter.ofRightPadded();
185                        }
186                },
187                /**
188                 * Upper case without padding.
189                 */
190                PLAIN {
191                        @Override
192                        public LogFormatter formatter() {
193                                return LevelFormatter.of();
194                        }
195                },
196                /**
197                 * Upper case in square brackets, like slf4j-simple's
198                 * <code>levelInBrackets</code>: <code>[INFO]</code>.
199                 */
200                BRACKETED {
201                        @Override
202                        public LogFormatter formatter() {
203                                return LogFormatter.builder().text("[").add(LevelFormatter.of()).text("]").build();
204                        }
205                },
206                /**
207                 * No level.
208                 */
209                @EnumAlias("false")
210                NONE {
211                        @Override
212                        public LogFormatter formatter() {
213                                return LogFormatter.noop();
214                        }
215                };
216
217                /**
218                 * The formatter for this choice.
219                 * @return formatter.
220                 */
221                public abstract LogFormatter formatter();
222
223                static LevelFormat parse(String value) {
224                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
225                                case "default", "true" -> PADDED;
226                                case "false" -> NONE;
227                                default ->
228                                        io.jstach.rainbowgum.LogProperty.enumValue(LevelFormat.class, value, "true", "false", "default");
229                        };
230                }
231
232        }
233
234        /**
235         * Logger name part.
236         */
237        @CaseChanging
238        enum LoggerFormat {
239
240                /**
241                 * Full logger name. The default.
242                 */
243                @EnumAlias({ "default", "true" })
244                FULL {
245                        @Override
246                        public LogFormatter formatter() {
247                                return LogFormatter.builder().loggerName().build();
248                        }
249                },
250                /**
251                 * Only the last component of the name, like slf4j-simple's
252                 * <code>showShortLogName</code>: <code>App</code> for
253                 * <code>com.example.App</code>.
254                 */
255                SHORT {
256                        @Override
257                        public LogFormatter formatter() {
258                                return ShortLoggerNameFormatter.INSTANCE;
259                        }
260                },
261                /**
262                 * No logger name.
263                 */
264                @EnumAlias("false")
265                NONE {
266                        @Override
267                        public LogFormatter formatter() {
268                                return LogFormatter.noop();
269                        }
270                };
271
272                /**
273                 * The formatter for this choice.
274                 * @return formatter.
275                 */
276                public abstract LogFormatter formatter();
277
278                static LoggerFormat parse(String value) {
279                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
280                                case "default", "true" -> FULL;
281                                case "false" -> NONE;
282                                default ->
283                                        io.jstach.rainbowgum.LogProperty.enumValue(LoggerFormat.class, value, "true", "false", "default");
284                        };
285                }
286
287        }
288
289        /**
290         * Key values part, written in braces after the logger name; see
291         * {@link KeyValuesWhenEmpty} for events with no key values. {@link #NONE} leaves out
292         * the key values and their braces.
293         */
294        @CaseChanging
295        enum KeyValuesFormat {
296
297                /**
298                 * Key values and their braces are left out.
299                 */
300                @EnumAlias("false")
301                NONE {
302                        @Override
303                        public LogFormatter formatter() {
304                                return LogFormatter.noop();
305                        }
306                },
307                /**
308                 * Percent encoded like a URI query:
309                 * <code>requestId=42&amp;user=Ada%20Lovelace</code>. The default.
310                 */
311                @EnumAlias({ "true", "default" })
312                PERCENT {
313                        @Override
314                        public LogFormatter formatter() {
315                                return new KeyValuesFormatterBuilder().format(KeyValuesFormatterBuilder.Format.PERCENT).build();
316                        }
317                },
318                /**
319                 * JSON: <code>{"requestId":"42","user":"Ada Lovelace"}</code>. Null values are
320                 * written as {@code null}.
321                 */
322                JSON {
323                        @Override
324                        public LogFormatter formatter() {
325                                return new KeyValuesFormatterBuilder().format(KeyValuesFormatterBuilder.Format.JSON).buildUnbraced();
326                        }
327                },
328                /**
329                 * JSON5, with valid identifier keys left unquoted:
330                 * <code>{requestId:"42",user:"Ada Lovelace"}</code>. Null values are written as
331                 * {@code null}.
332                 */
333                JSON5 {
334                        @Override
335                        public LogFormatter formatter() {
336                                return new KeyValuesFormatterBuilder().format(KeyValuesFormatterBuilder.Format.JSON5).buildUnbraced();
337                        }
338                };
339
340                /**
341                 * The formatter for this choice, without the enclosing braces supplied by TTLL.
342                 * @return formatter.
343                 */
344                public abstract LogFormatter formatter();
345
346                static KeyValuesFormat parse(String value) {
347                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
348                                case "true", "default" -> PERCENT;
349                                case "false" -> NONE;
350                                default -> io.jstach.rainbowgum.LogProperty.enumValue(KeyValuesFormat.class, value, "true", "false",
351                                                "default");
352                        };
353                }
354
355        }
356
357        /**
358         * Whether the key values braces are written when an event has no key values.
359         */
360        @CaseChanging
361        enum KeyValuesWhenEmpty {
362
363                /**
364                 * Left out for percent encoding and JSON5; <code>{}</code> for JSON, since
365                 * whatever reads JSON key values expects an object on every line. The default.
366                 */
367                @EnumAlias("default")
368                AUTO,
369                /**
370                 * Left out. Not allowed with {@link KeyValuesFormat#JSON}, whose readers expect
371                 * an object on every line.
372                 */
373                @EnumAlias("false")
374                OMIT,
375                /**
376                 * Always written, <code>{}</code> when there are no key values.
377                 */
378                @EnumAlias("true")
379                SHOW;
380
381                static KeyValuesWhenEmpty parse(String value) {
382                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
383                                case "default" -> AUTO;
384                                case "false" -> OMIT;
385                                case "true" -> SHOW;
386                                default -> io.jstach.rainbowgum.LogProperty.enumValue(KeyValuesWhenEmpty.class, value, "true", "false",
387                                                "default");
388                        };
389                }
390
391        }
392
393        /**
394         * Whether to color, see {@link ColorTheme} for which colors. Color detection uses
395         * {@link AnsiSupport#isAnsiSupported()}, which only knows about the console, so the
396         * default encoder of outputs that are not a console is {@link #OFF} unless set. As a
397         * property <code>true</code> and <code>false</code> are aliases for
398         * <code>default</code> and <code>off</code>.
399         */
400        @CaseChanging
401        enum ColorMode {
402
403                /**
404                 * No color.
405                 */
406                @EnumAlias("false")
407                OFF,
408                /**
409                 * The theme, or {@link ColorTheme#RAINBOWGUM} when no theme is set, if ANSI is
410                 * detected. The default.
411                 */
412                @EnumAlias("true")
413                DEFAULT,
414                /**
415                 * The theme if one is set and ANSI is detected; no color without a theme.
416                 */
417                DETECT,
418                /**
419                 * The theme, or {@link ColorTheme#RAINBOWGUM} when no theme is set, regardless of
420                 * ANSI detection.
421                 */
422                FORCE;
423
424                static ColorMode parse(String value) {
425                        return switch (value.strip().toLowerCase(java.util.Locale.ROOT)) {
426                                case "true" -> DEFAULT;
427                                case "false" -> OFF;
428                                default -> io.jstach.rainbowgum.LogProperty.enumValue(ColorMode.class, value, "true", "false");
429                        };
430                }
431
432        }
433
434        /**
435         * ANSI color theme, the colors used when {@link ColorMode} decides to color. The
436         * built in themes are the constants of this interface; others are made with
437         * {@link #builder(String)}. A theme put in the
438         * {@link io.jstach.rainbowgum.ServiceRegistry} as a {@code ColorTheme} under its name
439         * can be chosen by name with the theme property.
440         */
441        sealed interface ColorTheme permits PaletteColorTheme, NamedColorTheme {
442
443                /**
444                 * The Rainbow Gum colors, the same as the pattern encoder's default: cyan time,
445                 * faint thread and key values, level highlighted (error and warn bold red, info
446                 * bold blue) and magenta logger name. Used when no theme is set. Property value
447                 * <code>rainbowgum</code> or <code>default</code>.
448                 */
449                ColorTheme RAINBOWGUM = PaletteColorTheme.RAINBOWGUM;
450
451                /**
452                 * Spring Boot's console colors: faint time and thread, level colored by severity
453                 * (error red, warn yellow, the rest green) and cyan logger name. Property value
454                 * <code>spring</code>.
455                 */
456                ColorTheme SPRING = PaletteColorTheme.SPRING;
457
458                /**
459                 * Atom One Dark's colors in 24 bit color, so they show the same in any terminal
460                 * that supports it: cyan time, gray thread and key values, magenta logger name,
461                 * and level bold red, yellow, or blue (error, warn, info) with debug and trace
462                 * gray. Meant for a dark terminal background. Property value
463                 * <code>one_dark</code>.
464                 */
465                ColorTheme ONE_DARK = PaletteColorTheme.ONE_DARK;
466
467                /**
468                 * IntelliJ Darcula's colors in 24 bit color: blue time, gray thread and key
469                 * values, orange logger name, and level bold red, yellow, or green (error, warn,
470                 * info) with debug and trace gray. Meant for a dark terminal background. Property
471                 * value <code>darcula</code>.
472                 */
473                ColorTheme DARCULA = PaletteColorTheme.DARCULA;
474
475                /**
476                 * The theme's name, which is its property value.
477                 * @return name like <code>one_dark</code>.
478                 */
479                String name();
480
481                /**
482                 * Starts a theme. Parts not set are not colored.
483                 * @param name theme name: lowercase letters, digits, and underscores, starting
484                 * with a letter, and not the name of a built in theme or <code>default</code>.
485                 * @return builder.
486                 * @throws IllegalArgumentException if the name is not allowed.
487                 */
488                static Builder builder(String name) {
489                        return new Builder(PaletteColorTheme.requireThemeName(name));
490                }
491
492                /**
493                 * Builds a {@link ColorTheme}. Colors are ANSI SGR parameters, the part of an
494                 * escape sequence between <code>ESC[</code> and <code>m</code>, such as
495                 * <code>36</code> for cyan, <code>1;31</code> for bold red, or
496                 * <code>38;2;198;120;221</code> for a 24 bit color.
497                 */
498                final class Builder {
499
500                        private final String name;
501
502                        private String timestamp = "";
503
504                        private String thread = "";
505
506                        private String logger = "";
507
508                        private String keyValues = "";
509
510                        private String error = "";
511
512                        private String warn = "";
513
514                        private String info = "";
515
516                        private String debug = "";
517
518                        private String trace = "";
519
520                        private Builder(String name) {
521                                this.name = name;
522                        }
523
524                        /**
525                         * Starts from another theme's colors.
526                         * @param theme theme to copy.
527                         * @return this.
528                         */
529                        public Builder from(ColorTheme theme) {
530                                var p = PaletteColorTheme.paletteOf(theme);
531                                this.timestamp = p.timestamp();
532                                this.thread = p.thread();
533                                this.logger = p.logger();
534                                this.keyValues = p.keyValues();
535                                this.error = p.error();
536                                this.warn = p.warn();
537                                this.info = p.info();
538                                this.debug = p.debug();
539                                this.trace = p.trace();
540                                return this;
541                        }
542
543                        /**
544                         * Timestamp color.
545                         * @param color SGR parameters.
546                         * @return this.
547                         */
548                        public Builder timestamp(String color) {
549                                this.timestamp = color;
550                                return this;
551                        }
552
553                        /**
554                         * Thread color.
555                         * @param color SGR parameters.
556                         * @return this.
557                         */
558                        public Builder thread(String color) {
559                                this.thread = color;
560                                return this;
561                        }
562
563                        /**
564                         * Logger name color.
565                         * @param color SGR parameters.
566                         * @return this.
567                         */
568                        public Builder logger(String color) {
569                                this.logger = color;
570                                return this;
571                        }
572
573                        /**
574                         * Key values color.
575                         * @param color SGR parameters.
576                         * @return this.
577                         */
578                        public Builder keyValues(String color) {
579                                this.keyValues = color;
580                                return this;
581                        }
582
583                        /**
584                         * Color of a level.
585                         * @param level error, warning, info, debug, or trace.
586                         * @param color SGR parameters.
587                         * @return this.
588                         * @throws IllegalArgumentException for any other level.
589                         */
590                        public Builder level(System.Logger.Level level, String color) {
591                                switch (level) {
592                                        case ERROR -> this.error = color;
593                                        case WARNING -> this.warn = color;
594                                        case INFO -> this.info = color;
595                                        case DEBUG -> this.debug = color;
596                                        case TRACE -> this.trace = color;
597                                        default -> throw new IllegalArgumentException(
598                                                        "Level " + level + " has no color. Use error, warning, info, debug, or trace.");
599                                }
600                                return this;
601                        }
602
603                        /**
604                         * Builds the theme.
605                         * @return theme.
606                         */
607                        public ColorTheme build() {
608                                return new PaletteColorTheme(name,
609                                                new Palette(timestamp, thread, logger, keyValues, error, warn, info, debug, trace));
610                        }
611
612                }
613
614        }
615
616}