Skip to content

JBFL_DOCS.md

Latest commit

 

History

History
181 lines (143 loc) · 11.6 KB

JBFL_DOCS.md

File metadata and controls

181 lines (143 loc) · 11.6 KB
Raw

Configuration documentation: value formatting rules

This documentation describes the rule-based system for formatting values inside JBeam. It explains how to use pattern matching to target specific nodes and apply formatting settings during export.

Overview

This configuration system allows users to define formatting rules for values inside nested objects and arrays. Rules consist of:

  • Patterns: that specify which data elements to match.
  • Properties: that define how matched values are formatted.

Typical use cases include:

  • Fixed-width data export
  • Consistent floating-point number formatting
  • Flattening nested arrays for output

Pattern Syntax

Pattern Description
.* Matches any key at the current object level, regardless of name.
[*] Matches all elements in a list (1D array).
[*][*] Matches all elements in the innermost lists of 2D arrays (arrays of arrays).
.test Matches the value with key test in an object.
.test* Matches any key that starts with test (prefix match).
.0 Matches the object child at positional index 0 (by order, ignoring key name).
[4] Matches the value at index 4 in an array.

Properties Overview

Setting Name Description Applies To
PadDecimals Guarantees a minimum number of decimal digits, adding trailing zeros when the fraction is shorter and trimming them back when it is longer. Significant digits are never cut, so 0.12000 becomes 0.120 and 0.12345 stays as it is. Numeric values
PadAmount Fills the value out with trailing spaces to the given total length, so a column lines up. Does not change the value itself. Any scalar except for comments
AutoPad Aligns values in array rows into columns by padding each cell to the maximum width in that column. Applies to the array it is set on (e.g. nodes, beams). Arrays of arrays
AlignObjectKeys Pads object keys so that : separators align vertically across all entries in the same object. Objects
AutoPadSubObjects Aligns values within sibling inline objects by treating matching sub-keys as columns. Useful for glowMap-style structures. Objects with inline sub-objects
ComplexNewLine Controls multiline formatting for complex structures. None disables it (inline output). Force always enables it. Replaces the deprecated NoComplexNewLine and ForceComplexNewLine properties. Any complex data structure
PreserveNumberFormat Outputs numbers exactly as written in the source file instead of normalizing them. Useful for preserving intentional formatting like +1 or 0.002 vs 2.0e-3. Numeric values
Indent Controls the amount of indentation. Defaults to 4 spaces. Any complex data structure
TrailingComma Controls trailing commas. Preserve keeps the source value (default). Force always adds one. None always removes them. Resolved at the child level, so .* covers root. Arrays and objects

How Matching Works

  • Patterns traverse nested objects and arrays.
  • .* matches all keys at the current level.
  • .foo* matches any key starting with foo (e.g. .deformGroups_oilPan* matches deformGroups_oilPanFront, deformGroups_oilPanRear, etc.).
  • [*] matches all elements of an array.
  • Combinations like .*.nodes[*][*] match all elements inside inner lists under nodes keys.
  • Properties apply to each matched value individually.
  • Matching is agnostic to the data type; however, settings may behave differently based on type.
  • ComplexNewLine: Force ensures that matched complex structures are always output in multiline format with indentation.
  • ComplexNewLine: None keeps structures inline even when they contain nested arrays or objects.
  • The deprecated NoComplexNewLine: true and ForceComplexNewLine: true are still accepted for backward compatibility.
  • TrailingComma: None strips trailing commas. Force always adds them. Preserve (default) keeps whatever the source file had.
  • TrailingComma is resolved at the child level, so .* { TrailingComma: None; } also strips the trailing comma in the root object.

How far a property reaches

A pattern names one level. Some properties then apply only to what sits exactly there, and others also apply to everything nested below it, so a rule on .* can still decide how a value five levels down is printed.

Reaches Properties
The matched value only AutoPad, AlignObjectKeys, AutoPadSubObjects
The matched value and below PadDecimals, PadAmount, Indent, ComplexNewLine, TrailingComma, PreserveNumberFormat

The three in the first row all describe how one array or object lays out its own children, so inheriting them would align structures the rule never mentioned.

This is why .* { Indent: 2; } indents the whole file while .* { AutoPad: true; } only pads the root object, and why the shipped minimal.jbfl can set PadDecimals on .*.nodes[*][*] or on a parent and get the same result.

Detailed Rules Examples

Pattern: .*.nodes[*][*]

.*.nodes[*][*] {
    PadDecimals: 3;
    PadAmount: 8;
    ComplexNewLine: None;
    Indent: 4;
}
  • Matches all values in the innermost arrays under the key nodes, where:
    • The top-level element is an object with arbitrary keys.
    • Each key references an object containing a key named nodes.
    • The value of nodes is a 2D array (array of arrays).
    • The rule applies to all numeric values in the innermost arrays of this 2D array.
  • Properties:
    • PadDecimals: 3
    • PadAmount: 8
    • ComplexNewLine: None
    • Indent: 4
  • Behavior: Give the fraction at least 3 digits by adding zeros, then pad the whole value to 8 characters with spaces so the column lines up, keeping nested arrays inline with 4-space indentation.

Examples

Original Value Initial width Exported String
1.2 3 1.200
3.14 3 3.140
12.0 3 12.000

Pattern: .*.beams[*][*]

.*.beams[*][*] {
    PadAmount: 8;
}
  • Matches values in the innermost arrays under the key beams.
  • Properties:
    • PadAmount: 8
  • Behavior: Format floats as fixed-width strings of length 8, filled out with trailing spaces so the column lines up.

Examples:

Original Value Initial width Exported String
5.0 3 5.0
0.1234 6 0.1234
7.89 4 7.89

Padding Behavior on Scalar Values

  • Padding applies to all scalar types (numbers, strings, booleans).
  • If the length of the representation of the scalar is less than PadAmount, the value is padded:
    • With trailing zeros only if the fractional part has fewer digits than PadDecimals. Existing extra decimals are left intact. This guarantees a minimum number of decimal digits.
    • With leading spaces otherwise.
  • If the length is equal to or greater than PadAmount, no padding or truncation occurs; the full string is output as-is.

Examples

Value Initial width PadDecimals PadAmount Output
3.14 3 3 8 3.140
3.14 3 0 8 3.14 with 4 spaces before
"abc" 5 3 8 "abc" with 3 spaces before
"abc" 5 0 8 "abc" with 3 spaces before
true 4 0 6 true with 2 spaces before
123456789.0 11 0 5 123456789.0

Summary Table

Pattern Targeted Data Properties Padding Behavior
.*.nodes[*][*] Innermost float values in nodes PadDecimals: 3 Trailing zeros so fractional part is at least 3 digits
.*.beams[*][*] Innermost float values in beams PadAmount: 8 Leading spaces

Notes and Tips

  • Patterns are powerful and flexible; combine .*, [*], and object keys to precisely target values.
  • PadDecimals applies only to numbers, while PadAmount applies to all non-comment scalar values.
  • String values receive space padding regardless of PadDecimals.
  • Use ComplexNewLine: None to simplify output layout when working with complex structures like lists and objects.
  • Use ComplexNewLine: Force to ensure nested structures always use multiline formatting.