Skip to main content

jlf_core/format/
mod.rs

1use smallvec::SmallVec;
2
3use crate::{json::MarkupStyles, Json};
4
5mod log;
6pub mod parse;
7
8pub use log::FormattedLog;
9pub use owo_colors::{OwoColorize as Colorize, Style};
10
11type Arg = (FieldOptions, Format);
12type FieldOptions = SmallVec<[Field; 2]>;
13type FieldNames = SmallVec<[FieldType; 2]>;
14
15#[derive(Debug, Clone, PartialEq)]
16pub enum Field {
17    Names(FieldNames),
18    Whole,
19    Rest,
20    /// A quoted literal (`${"text":mods}`): constant text rendered with the
21    /// arg's modifiers, so raw text can be styled/escaped like a value.
22    Literal(String),
23    /// `$value` inside a `$( … )` repetition: the current entry's value.
24    ColValue,
25    /// `${value.path}` inside a repetition: a sub-path of the entry's value.
26    ColValuePath(FieldNames),
27    /// `$key` inside a `$( … )` repetition: the current entry's key/name.
28    ColKey,
29}
30
31/// The source a `$( … )` repetition iterates over.
32#[derive(Debug, Clone, PartialEq)]
33pub enum RepSource {
34    /// Bare `$( … )`: iterate the current record's top-level fields.
35    Record,
36    /// `$cols( … )`: iterate the CLI-selected columns (`-f`/args).
37    Columns,
38    /// `$path( … )`: iterate the object/array at `path` in the record.
39    Path(Field),
40}
41
42/// A column: a display `name` plus the parsed accessor used to pull its value.
43#[derive(Debug, Clone)]
44pub struct Column {
45    name: String,
46    field: Field,
47}
48
49/// Build a [`Column`] from a field name/path (e.g. `ts`, `user.id`).
50pub fn column(name: impl Into<String>) -> Column {
51    let name = name.into();
52    let field = parse::parse_field(&name).unwrap_or(Field::Whole);
53    Column { name, field }
54}
55
56#[derive(Debug, Clone)]
57pub struct Formatter {
58    pieces: Vec<Piece>,
59    args: Vec<Arg>,
60    /// Whether any arg is an optional `{?field}` — gates the (slightly
61    /// costlier) whitespace-collapsing render path so plain templates pay
62    /// nothing.
63    has_optional: bool,
64    /// Columns for bare `$( … )` repetition (from `-f`/args); empty otherwise.
65    columns: Vec<Column>,
66}
67
68impl Formatter {
69    pub fn new(
70        input: &str,
71        no_color: bool,
72        compact: bool,
73    ) -> Result<Formatter, parse::FormatError> {
74        let mut pieces = Vec::new();
75        let mut args = Vec::new();
76
77        parse::crunch_input(&mut pieces, &mut args, input, no_color, compact)?;
78
79        let has_optional = args.iter().any(|(_, fmt)| fmt.optional);
80
81        Ok(Formatter {
82            pieces,
83            args,
84            has_optional,
85            columns: Vec::new(),
86        })
87    }
88
89    /// Apply an escape (e.g. HTML) to every interpolated value — used by custom
90    /// output formats so their body template is safe.
91    pub fn with_escape(mut self, escape: Escape) -> Self {
92        for (_, fmt) in &mut self.args {
93            fmt.escape = escape;
94        }
95        self
96    }
97
98    /// Set the columns iterated by a bare `$( … )` repetition.
99    pub fn with_columns(mut self, columns: Vec<Column>) -> Self {
100        self.columns = columns;
101        self
102    }
103
104    pub fn as_log<'a>(&'a self, json: &'a Json<'a>) -> FormattedLog<'a> {
105        FormattedLog {
106            formatter: self,
107            json,
108        }
109    }
110}
111
112#[derive(Debug, Clone, PartialEq)]
113pub enum Piece {
114    Literal(String),
115    // arg index
116    Arg(usize),
117    CondStart(Cond, usize),
118    ElseCond(Cond, usize),
119    Else,
120    CondEnd,
121    /// Start of a `${match path}` block: `path` is the subject arg. The
122    /// subject's value is bound to `$value` for the arms in between, up to
123    /// `MatchEnd`.
124    MatchStart(usize),
125    /// End of a `${match … }` block.
126    MatchEnd,
127    /// Start of a `$( … )sep op` repetition: what to iterate, the separator
128    /// emitted between iterations, and the repetition operator.
129    RepStart(RepSource, String, RepOp),
130    /// End of a `$( … )` repetition.
131    RepEnd,
132}
133
134/// The repetition operator on a `$( … )` group: `*` (zero or more), `+` (one or
135/// more), `?` (zero or one). All iterate the selected column list; the operator
136/// documents intent (kept for parity with `macro_rules!`).
137#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138pub enum RepOp {
139    Star,
140    Plus,
141    Question,
142}
143
144#[derive(Debug, Clone, PartialEq)]
145pub enum Cond {
146    If,
147    Has,
148    IfConfig(bool),
149    /// `$if(field OP literal => …)` — compare the field's scalar value against
150    /// a literal. Numeric when both sides parse as numbers, else
151    /// lexicographic.
152    Cmp(CmpOp, String),
153    /// A `${match}` arm: matches when the bound subject (`$value`) satisfies
154    /// any of the listed tests. An empty list is the `_` wildcard — it
155    /// matches any present (non-null) value, so a missing subject renders
156    /// nothing.
157    Arm(Vec<ArmTest>),
158}
159
160/// One alternative in a `${match}` arm pattern (`a | b | …`).
161#[derive(Debug, Clone, PartialEq)]
162pub enum ArmTest {
163    /// A comparison against the subject, e.g. `>= 500` or `== "GET"`.
164    Cmp(CmpOp, String),
165    /// A numeric range, e.g. `400..500` (half-open) or `500..` (from). `hi` is
166    /// inclusive only for `..=` forms.
167    Range {
168        lo: Option<f64>,
169        hi: Option<f64>,
170        hi_inclusive: bool,
171    },
172}
173
174/// Comparison operator for an `$if(field OP literal => …)` condition.
175#[derive(Debug, Clone, Copy, PartialEq, Eq)]
176pub enum CmpOp {
177    Eq,
178    Ne,
179    Gt,
180    Ge,
181    Lt,
182    Le,
183}
184
185#[derive(Debug, Clone, PartialEq)]
186pub enum FieldType {
187    Name(String),
188    Index(usize),
189}
190
191#[derive(Debug, Default, Clone, Copy, PartialEq)]
192pub struct Format {
193    pub style: Option<Style>,
194    pub compact: bool,
195    pub is_json: bool,
196    pub indent: usize,
197    // `{?field}`: when this field renders empty, collapse one adjacent space
198    // so an absent field leaves no stray gap.
199    pub optional: bool,
200    // escape applied to interpolated values (custom output formats), e.g.
201    // HTML.
202    pub escape: Escape,
203    pub markup_styles: MarkupStyles,
204}
205
206/// How interpolated field values are escaped for the surrounding output format.
207/// `Html` makes values safe in HTML; `Csv`/`Tsv`/`Md` quote or clean cells for
208/// those table dialects. This single enum replaces the old split between a
209/// framed-format `Escape` and a table `Quote`.
210#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
211pub enum Escape {
212    #[default]
213    None,
214    Html,
215    /// RFC-4180 CSV: wrap in quotes when the cell contains `"`, a newline, or
216    /// a comma; double any inner quotes.
217    Csv,
218    /// TSV: replace tabs and newlines with spaces.
219    Tsv,
220    /// Markdown table cell: escape `|` and turn newlines into `<br>`.
221    Md,
222}
223
224impl Escape {
225    /// Parse an `escape`/modifier name. Returns `None` for unknown names.
226    pub fn from_name(name: &str) -> Option<Escape> {
227        match name {
228            "" | "none" => Some(Escape::None),
229            "html" => Some(Escape::Html),
230            "csv" => Some(Escape::Csv),
231            "tsv" => Some(Escape::Tsv),
232            "md" => Some(Escape::Md),
233            _ => None,
234        }
235    }
236}
237
238#[cfg(test)]
239mod dsl_tests {
240    use super::*;
241    use crate::{column, expanded_format, Json};
242
243    fn render(tpl: &str, cols: &[&str], json_str: &str) -> String {
244        let cols: Vec<_> = cols.iter().map(|c| column(*c)).collect();
245        let f = Formatter::new(tpl, true, false).unwrap().with_columns(cols);
246        let mut j = Json::Null;
247        j.parse_replace(json_str).unwrap();
248        let mut out = String::new();
249        f.as_log(&j).write_fmt(&mut out).unwrap();
250        out
251    }
252
253    #[test]
254    fn bare_field_and_path() {
255        assert_eq!(
256            render("$level $ts", &[], r#"{"level":"INFO","ts":"1"}"#),
257            "INFO 1"
258        );
259        assert_eq!(render("${user.id}", &[], r#"{"user":{"id":"7"}}"#), "7");
260    }
261
262    #[test]
263    fn flattened_dotted_key_falls_back() {
264        // A literal dotted key resolves when there's no matching nesting.
265        assert_eq!(
266            render(
267                "${fields.log.file}",
268                &[],
269                r#"{"fields":{"log.file":"/p"}}"#
270            ),
271            "/p"
272        );
273        // A top-level flattened key too.
274        assert_eq!(render("${a.b}", &[], r#"{"a.b":"flat"}"#), "flat");
275        // Real nesting still wins over a same-named flattened key.
276        assert_eq!(
277            render("${a.b}", &[], r#"{"a":{"b":"nested"},"a.b":"flat"}"#),
278            "nested"
279        );
280    }
281
282    #[test]
283    fn used_flattened_key_is_excluded_from_repetition() {
284        // A flattened key rendered up top must be dropped from a later
285        // `$fields( … )` breakdown (not double-shown).
286        assert_eq!(
287            render(
288                r#"${fields.log.file} $fields( ${key}=${value} )" "*"#,
289                &[],
290                r#"{"fields":{"log.file":"/p","other":"x"}}"#,
291            ),
292            "/p other=x"
293        );
294    }
295
296    #[test]
297    fn malformed_repetition_errors_and_is_not_swallowed() {
298        // An operator-less `$name( … )` must error even when a valid repetition
299        // follows on the next line — previously the bare-separator scan
300        // absorbed the following block, silently rendering nothing.
301        assert!(
302            Formatter::new("$key(a => b)\n$fields( $key )*", true, false)
303                .is_err()
304        );
305        // A real bare separator right after `)` still parses.
306        assert!(Formatter::new("$cols( $key ),*", true, false).is_ok());
307    }
308
309    #[test]
310    fn column_rep_csv() {
311        assert_eq!(
312            render(
313                r#"$cols( $key ),*"#,
314                &["ts", "level"],
315                r#"{"ts":"1","level":"INFO"}"#
316            ),
317            "ts,level"
318        );
319        assert_eq!(
320            render(
321                r#"$cols( ${value:csv} ),*"#,
322                &["ts", "level"],
323                r#"{"ts":"1","level":"a,b"}"#
324            ),
325            "1,\"a,b\""
326        );
327    }
328
329    #[test]
330    fn object_cell_is_compact_and_escaped() {
331        // A nested object in a table cell must stay on one line and be quoted
332        // for the dialect — never pretty-printed across rows.
333        assert_eq!(
334            render(
335                r#"$cols( ${value:csv} ),*"#,
336                &["fields"],
337                r#"{"fields":{"m":"a,b","n":5}}"#
338            ),
339            r#""{""m"":""a,b"",""n"":5}""#
340        );
341        assert_eq!(
342            render(
343                r#"$cols( ${value:md} )" | "*"#,
344                &["fields"],
345                r#"{"fields":{"m":"x"}}"#
346            ),
347            r#"{"m":"x"}"#
348        );
349        assert_eq!(
350            render(
351                r#"$cols( ${value:tsv} )\t*"#,
352                &["fields"],
353                r#"{"fields":{"m":"x"}}"#
354            ),
355            r#"{"m":"x"}"#
356        );
357    }
358
359    #[test]
360    fn record_rep_flattens_root() {
361        assert_eq!(
362            render(r#"$( $key=$value )" "*"#, &[], r#"{"a":"1","b":"2"}"#),
363            "a=1 b=2"
364        );
365    }
366
367    #[test]
368    fn md_row_with_quoted_sep() {
369        assert_eq!(
370            render(
371                r#"| $cols( ${value:md} )" | "* |"#,
372                &["a", "b"],
373                r#"{"a":"x","b":"y"}"#
374            ),
375            "| x | y |"
376        );
377    }
378
379    #[test]
380    fn path_rep_flatten_fields() {
381        assert_eq!(
382            render(
383                r#"$fields( $key=$value )" "*"#,
384                &[],
385                r#"{"fields":{"dir":"/d","n":5}}"#
386            ),
387            "dir=/d n=5"
388        );
389    }
390
391    #[test]
392    fn conditional_and_optional() {
393        assert_eq!(
394            render("$if(warn => W)$else(ok)", &[], r#"{"warn":true}"#),
395            "W"
396        );
397        assert_eq!(render("a${?missing} b", &[], r#"{}"#), "ab");
398    }
399
400    #[test]
401    fn if_comparison_numeric() {
402        let t = "$if(status >= 500 => 5xx)$elif(status >= 400 => 4xx)$else(ok)";
403        assert_eq!(render(t, &[], r#"{"status":200}"#), "ok");
404        assert_eq!(render(t, &[], r#"{"status":429}"#), "4xx");
405        assert_eq!(render(t, &[], r#"{"status":503}"#), "5xx");
406    }
407
408    #[test]
409    fn if_comparison_operators() {
410        assert_eq!(
411            render("$if(n == 200 => y)$else(n)", &[], r#"{"n":200}"#),
412            "y"
413        );
414        assert_eq!(
415            render("$if(n != 200 => y)$else(n)", &[], r#"{"n":201}"#),
416            "y"
417        );
418        assert_eq!(render("$if(n <= 3 => y)$else(n)", &[], r#"{"n":3}"#), "y");
419        assert_eq!(render("$if(n < 3 => y)$else(n)", &[], r#"{"n":3}"#), "n");
420    }
421
422    #[test]
423    fn if_comparison_string_literal() {
424        let t = r#"$if(method == "GET" => read)$else(write)"#;
425        assert_eq!(render(t, &[], r#"{"method":"GET"}"#), "read");
426        assert_eq!(render(t, &[], r#"{"method":"POST"}"#), "write");
427    }
428
429    #[test]
430    fn if_comparison_missing_field_is_false() {
431        // an absent or non-scalar field never satisfies a comparison
432        assert_eq!(render("$if(n >= 1 => y)$else(n)", &[], r#"{}"#), "n");
433    }
434
435    #[test]
436    fn has_vs_if_and_config() {
437        // `$has` tests existence, `$if` truthiness — so a present `0` differs
438        assert_eq!(
439            render("$has(body => has)$else(no)", &[], r#"{"body":0}"#),
440            "has"
441        );
442        assert_eq!(
443            render("$if(body => yes)$else(no)", &[], r#"{"body":0}"#),
444            "no"
445        );
446        // an all-whitespace branch body is kept as an intentional separator
447        assert_eq!(
448            render("a$config(compact =>  )$else(\n)b", &[], r#"{}"#),
449            "a\nb"
450        );
451    }
452
453    #[test]
454    fn match_ranges() {
455        let t = "$match(status $when(500.. => 5xx) $when(400..500 => 4xx) \
456                 $else(ok))";
457        assert_eq!(render(t, &[], r#"{"status":200}"#), "ok");
458        assert_eq!(render(t, &[], r#"{"status":404}"#), "4xx");
459        assert_eq!(render(t, &[], r#"{"status":503}"#), "5xx");
460        // a missing subject matches no arm — not even `$else`
461        assert_eq!(render(t, &[], r#"{}"#), "");
462    }
463
464    #[test]
465    fn match_value_binding_and_alternation() {
466        let t = r#"$match(method $when("GET"|"HEAD" => read:$value) $else(other:$value))"#;
467        assert_eq!(render(t, &[], r#"{"method":"GET"}"#), "read:GET");
468        assert_eq!(render(t, &[], r#"{"method":"HEAD"}"#), "read:HEAD");
469        assert_eq!(render(t, &[], r#"{"method":"POST"}"#), "other:POST");
470    }
471
472    #[test]
473    fn match_subject_fallback() {
474        let t = r#"$match(lvl|level $when("ERR" => !) $else($value))"#;
475        assert_eq!(render(t, &[], r#"{"level":"info"}"#), "info");
476        assert_eq!(render(t, &[], r#"{"lvl":"ERR"}"#), "!");
477    }
478
479    #[test]
480    fn match_multiline_layout() {
481        // decorative line breaks + indentation around arms are dropped
482        let t = "$match(lvl\n  $when(\"INFO\" => info)\n  $when(\"ERROR\" => \
483                 err)\n)";
484        assert_eq!(render(t, &[], r#"{"lvl":"INFO"}"#), "info");
485        assert_eq!(render(t, &[], r#"{"lvl":"ERROR"}"#), "err");
486    }
487
488    #[test]
489    fn match_on_repetition_value() {
490        // `$match(value …)` inside `$( … )` dispatches on each entry's value
491        let t =
492            r#"$( $key=$match(value $when(>=100 => big) $else(small)) )" "*"#;
493        assert_eq!(render(t, &[], r#"{"a":5,"b":500}"#), "a=small b=big");
494    }
495
496    #[test]
497    fn nested_match() {
498        let t = "$match(s $when(>=500 => $match(value $when(==503 => down) \
499                 $else(5xx))) $else(ok))";
500        assert_eq!(render(t, &[], r#"{"s":200}"#), "ok");
501        assert_eq!(render(t, &[], r#"{"s":500}"#), "5xx");
502        assert_eq!(render(t, &[], r#"{"s":503}"#), "down");
503    }
504
505    #[test]
506    fn include_expands() {
507        let vars = vec![("lvl".to_string(), "${level:dimmed}".to_string())];
508        let expanded = expanded_format("[${@lvl}]", &vars);
509        assert_eq!(expanded, "[${level:dimmed}]");
510    }
511    #[test]
512    fn value_path_in_array_rep() {
513        assert_eq!(
514            render(
515                r#"$spans( [${value.name}] )" "*"#,
516                &[],
517                r#"{"spans":[{"name":"a"},{"name":"b"}]}"#
518            ),
519            "[a] [b]"
520        );
521    }
522    #[test]
523    fn rep_skips_consumed_key() {
524        // referencing fields.message first drops it from the $fields flatten
525        assert_eq!(
526            render(
527                r#"${fields.message} | $fields( $key=$value )" "*"#,
528                &[],
529                r#"{"fields":{"message":"hi","a":"1","b":"2"}}"#
530            ),
531            "hi | a=1 b=2"
532        );
533    }
534
535    #[test]
536    fn rep_body_keeps_newlines() {
537        assert_eq!(
538            render("head$( \n  $key )*", &[], r#"{"a":"1","b":"2"}"#),
539            "head\n  a\n  b"
540        );
541    }
542    #[test]
543    fn if_guard_block() {
544        let t = r#"${level}$if(span.method => -> ${span.method})"#;
545        assert_eq!(
546            render(t, &[], r#"{"level":"INFO","span":{"method":"GET"}}"#),
547            "INFO-> GET"
548        );
549        assert_eq!(render(t, &[], r#"{"level":"WARN"}"#), "WARN");
550    }
551    #[test]
552    fn quoted_literal_renders_constant_text() {
553        // A quoted hole is literal text, not a field lookup.
554        assert_eq!(
555            render(r#"${"hi"} ${x}"#, &[], r#"{"x":"there"}"#),
556            "hi there"
557        );
558        // Modifiers apply to it (escaping is observable without color).
559        assert_eq!(render(r#"${"a,b":csv}"#, &[], r#"{}"#), "\"a,b\"");
560        // A colon inside the literal is not a modifier separator.
561        assert_eq!(render(r#"${"a:b"}"#, &[], r#"{}"#), "a:b");
562        // Escapes: \t, \", and a literal backslash.
563        assert_eq!(render(r#"${"x\ty\"z"}"#, &[], r#"{}"#), "x\ty\"z");
564        // Single-quoted literals work too.
565        assert_eq!(render(r#"${'lit'}"#, &[], r#"{}"#), "lit");
566    }
567
568    #[test]
569    fn quoted_literal_errors() {
570        let bad = |t: &str| Formatter::new(t, true, false).is_err();
571        assert!(bad(r#"${"oops}"#)); // unterminated
572        assert!(bad(r#"${"x" foo}"#)); // trailing junk after the literal
573    }
574
575    #[test]
576    fn ordering_comparisons_tolerate_unit_suffixes() {
577        // A numeric value with a unit suffix must compare by magnitude, not
578        // lexicographically. `$when(<150)` and a `$if` ordering op both apply.
579        let arm = r#"$match(fields.latency $when(<150 => lo) $else(hi))"#;
580        let lo = |v: &str| {
581            render(arm, &[], &format!(r#"{{"fields":{{"latency":"{v}"}}}}"#))
582        };
583        assert_eq!(lo("17.881 ms"), "lo"); // was "hi" (lexicographic bug)
584        assert_eq!(lo("8.972 ms"), "lo"); // was "hi"
585        assert_eq!(lo("144.306 ms"), "lo");
586        assert_eq!(lo("236.643 ms"), "hi");
587        // Ranges tolerate the suffix too.
588        let rng = r#"$match(fields.latency $when(0..150 => lo) $else(hi))"#;
589        assert_eq!(
590            render(rng, &[], r#"{"fields":{"latency":"17.881 ms"}}"#),
591            "lo"
592        );
593        // `$if` ordering op.
594        let cond = r#"$if(d > 100 => big)$else(small)"#;
595        assert_eq!(render(cond, &[], r#"{"d":"17.881 ms"}"#), "small");
596        assert_eq!(render(cond, &[], r#"{"d":"236.6 ms"}"#), "big");
597    }
598
599    #[test]
600    fn equality_stays_a_string_compare() {
601        // Equality must not go numeric on values that merely start with digits,
602        // or "2xx" would wrongly equal "2yy".
603        let t = r#"$if(code == "2xx" => match)$else(no)"#;
604        assert_eq!(render(t, &[], r#"{"code":"2xx"}"#), "match");
605        assert_eq!(render(t, &[], r#"{"code":"2yy"}"#), "no");
606    }
607}