Request feedback: aligning property values

[j-brooke]

I'm working on a change for version 5 to how object properties are handled for the "expanded" case. I'd like opinions from FracturedJson's users on how it should work: settings, defaults, etc.

Background

In version 4, if a collection is formatted as a table, the property values are already lined up, with the colons all in a row.

Example 1.1

{
    "Rect"   : { "position": {"x": -44, "y":  3.40        } },
    "Point"  : { "position": {          "y": 22.00, "z": 3} },
    "Oval"   : { "position": {"x": 140, "y":  0.04        } },
    "Polygon": { "position": null                           }
}

When they're written as "expanded" instead of table-formatted, they're not lined up. The values start immediately after the prop name and colon.

Example 1.2

{
    "type": "turret",
    "hp": 400,
    "loc": {"x": 47, "y": -4},
    "flags": ["stationary"]
}

Even when there's only one column, FracturedJson 4 will treat objects as tables if the values are all the same type, but will fall back to expanded behavior if the types are mixed. This sometimes leads to some visually unpleasant cases. For example, in the case below, Vera and Dave's property values are all aligned, but Chuck's aren't since his zipcode is a number instead of string.

Example 1.3

{
    "Vera": {
        "street" : "12 Madeup St.",
        "city"   : "Boston",
        "state"  : "MA",
        "zipcode": "02127"
    },
    "Chuck": {
        "street": "994 Fake Place",
        "unit": "102",
        "city": "Las Vegas",
        "state": "NV",
        "zipcode": 89102
    },
    "Dave": {
        "street": "1967 Void Rd.",
        "unit"  : "B",
        "city"  : "Athens",
        "state" : "GA"
    }
}

Proposed Change

The change I'm considering is to align the property values in the expanded case as well. In most cases this makes things look nicer.

Example 2.1

{
    "type" : "turret",
    "hp"   : 400,
    "loc"  : {"x": 47, "y": -4},
    "flags": ["stationary"]
}

Example 2.2

{
    "Vera" : {
        "street" : "12 Madeup St.",
        "city"   : "Boston",
        "state"  : "MA",
        "zipcode": "02127"
    },
    "Chuck": {
        "street" : "994 Fake Place",
        "unit"   : "102",
        "city"   : "Las Vegas",
        "state"  : "NV",
        "zipcode": 89102
    },
    "Dave" : {
        "street": "1967 Void Rd.",
        "unit"  : "B",
        "city"  : "Athens",
        "state" : "GA"
    }
}

Example 2.3

{
    "Elements": [
        {
            /*Carbon*/ "Symbol"  : "C",
                       "Number"  : 6,
                       "Isotopes": [11, 12, 13, 14]
        },
        {
            /*Oxygen*/ "Symbol"  : "O",
                       "Number"  : 8,
                       "Isotopes": [16, 18, 17]
        },
        {
            /*Hydrogen*/ "Symbol"  : "H",
                         "Number"  : 1,
                         "Isotopes": [1, 2, 3]
        },
        {
            /*Iron*/ "Symbol"  : "Fe",
                     "Number"  : 26,
                     "Isotopes": [56, 54, 57, 58]
        }
    ]
}

Complications

This approach starts to look ugly when the property names are long. Consider this case.

Example 3.1 (Old behavior, MaxTotalLineLength=80)

{
    "National Lampoon's Animal House": {
        "Year": 1978,
        "Director": "John Landis"
    },
    "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb": {
        "Year": 1964,
        "Director": "Stanley Kubrick"
    },
    "Repo Man": {"Year": 1984, "Director": "Alex Cox"}
}

Example 3.2 (Old behavior, MaxTotalLineLength=120)

{
    "National Lampoon's Animal House": {"Year": 1978, "Director": "John Landis"},
    "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb": {
        "Year": 1964,
        "Director": "Stanley Kubrick"
    },
    "Repo Man": {"Year": 1984, "Director": "Alex Cox"}
}

Example 3.3 (New behavior, MaxTotalLineLength=80)

{
    "National Lampoon's Animal House"                                     : {
        "Year"    : 1978,
        "Director": "John Landis"
    },
    "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb": {
        "Year"    : 1964,
        "Director": "Stanley Kubrick"
    },
    "Repo Man"                                                            : {
        "Year"    : 1984,
        "Director": "Alex Cox"
    }
}

Example 3.4 (New behavior, MaxTotalLineLength=120)

{
    "National Lampoon's Animal House"                                     : {"Year": 1978, "Director": "John Landis"},
    "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb": {
        "Year"    : 1964,
        "Director": "Stanley Kubrick"
    },
    "Repo Man"                                                            : {"Year": 1984, "Director": "Alex Cox"}
}

For this data, in my opinion, the old behavior (Example 3.1 & 3.2) looks best. And notice that the new behavior prevents inlining of the short Repo Man row in example 3.3.

Discussion

The only solution I can think of is to have a setting, AlignPropertiesMaxLabelSize (or something), and only try to line up the properties if the name is less than or equal to that size.

Instead of an absolute size, maybe the setting could look at the difference in size between the largest and smallest names, or between the largest and the average. I'm not sure that really helps much, though, and would probably confuse people.

One way or another, there probably needs to be a way to disable this feature. I assume someone will dislike it, somewhere.

Another question is where to put the colons: after the padding, next to the value (as in the examples above); or before the padding, next to the property name? (This is somewhat similar to the setting TableCommaPlacement introduced in 4.1 to control where to put commas relative to the padding.)

What are your thoughts? Are there edge cases I haven't thought of? What settings should control it? What defaults?

[alvintownsend]

It seems that all expanded cases in example 2.x are improvements for the expanded cases in 1.x.

For the complications expressed in 3.x, I'm not sure if there's a great universal solution (I certainly don't have one), but it seems that long property names will always be a potential problem. AlignPropertiesMaxLabelSize might be a solution to override some reasonable default (maybe a reasonable default is 25 or 50 or 80, dunno). But I do like the idea of FJ understanding the difference between the lengths of the property names, and then treating them all the same. Of all the examples in 3.x, I think avoiding 3.4 should be the priority. The others in 3.x are better. And even better would be this as a target, IMO:

{
    "National Lampoon's Animal House" : {
        "Year"     : 1978,
        "Director" : "John Landis"
    },
    "Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb" : {
        "Year"     : 1964,
        "Director" : "Stanley Kubrick"
    },
    "Repo Man" : {
        "Year"     : 1984,
        "Director" : "Alex Cox"
    }
}

(You can ignore my spacing preference around colons here.)

[ChrisMooreMGS]

Rather than a AlignPropertiesMaxLabelSize, how feasible is MaxSpaceWhenAligningFields? Set a maximum amount of tabs/spaces that can be inserted when aligning the columns, and if it would exceed that amount the field doesn't get aligned.

[j-brooke]

It's certainly feasible. Are you suggesting an all-or-nothing decision for the object as a whole, or per-property decisions? For instance, if the decision were made per-property, we might end up with Animal House being padded out to match Dr. Strangelove, but not Repo Man.

I certainly think the all-or-nothing approach has value. I'm not seeing the value of the per-property way though.

[ChrisMooreMGS]

All-or-nothing probably makes more sense, yeah.

There could also instead be a MaxAlignablePropertyLength. When doing the column aligning, the formatter will ignore any property that exceeds that length. Alternatively, it could be MaxAlignableLineLength to make it where all properties in a single line must be under a specified length to be aligned in columns.

[alvintownsend]

And thinking on this further - when looking over a formatted document, I think my strong preference is for consistency. Even if it's a little weird, it's better to be consistently weird. When scanning JSON knowing the pattern applied to the document makes finding the values and understanding the structure easier. So of any of the above examples, I always end up favoring the consistent ones.

This makes 1.1, 2.1, 2.2, 2.3, and 3.3 the most appealing, and I believe the behaviors there would be most useful as a default. Although for 1.1, I think doing this makes it easier to see what's going on (lining up colons with padding so it looks more table-ish):

{
    "Rect"    : { "position" : {"x" : -44, "y" :  3.40         } },
    "Point"   : { "position" : {           "y" : 22.00, "z" : 3} },
    "Oval"    : { "position" : {"x" : 140, "y" :  0.04         } },
    "Polygon" : { "position" : null                            }
}

Or maybe even ordering objects and object properties such that as many columns are moved to the front as possible, lining up as many as possible together, although I consider this a totally-optional-nice-to-have:

{
    "Rect"    : { "position" : {"y" :  3.40, "x" : -44         } },
    "Oval"    : { "position" : {"y" :  0.04, "x" : 140         } },
    "Point"   : { "position" : {"y" : 22.00,            "z" : 3} },
    "Polygon" : { "position" : null                            }
}

[j-brooke]

Or maybe even ordering objects and object properties such that as many columns are moved to the front as possible, lining up as many as possible together

I think the less reordering the better. Order is important for some applications. Even in the cases where the computer won't care about the order, it could be confusing to humans to rearrange rows. Obviously in some cases, columns need to be reordered to make table formatting work, but even that is a rare case, I think. Trying to come up with a general purpose algorithm to decide the best order of data you don't understand is just too hard to do right.

[j-brooke]

Implemented in version 5.