Options - j-brooke/FracturedJson GitHub Wiki
This page covers the settings for version 4.x. Please see other pages for version 3.x, version 2.x or version 1.x.
Quick Reference
Most Important Settings
- Use MaxTotalLineLength to adjust horizontal space.
- Use MaxInlineComplexity, MaxCompactArrayComplexity, and MaxTableRowComplexity to control how much stuff can be put on one line. Set them to
-1to disable that sort of layout. (In particular, setMaxTableRowComplexity=-1to disable table formatting.) - Use NumberListAlignment to control how columns/lists of numbers are written.
Reordering and Rewriting
There are some cases where FracturedJson is allowed to rewrite the non-whitespace parts of the document. For most users that's harmless, but if you need to ensure that only spaces, tabs, and newlines are adjusted, there are a few settings you should know about.
- When table formatting is enabled (i.e.,
MaxTableRowComplexityhas any value>=0), object properties might be reordered to match the order of other rows. - When
NumberListAlignmentisNormalize, numbers in a row will be rewritten to all have the same number of digits after the decimal point. In some cases, they'll be converted from scientific notation. - When comments are allowed with
CommentPolicy=Preserve, comments will sometimes be moved to the other sides of commas or colons, and line-ending comments might be converted to block comments. There's no way to disable this behavior while preserving comments.
Length and Complexity
Length and complexity are how FracturedJson decides how much to put on one line.
MaxTotalLineLength
Maximum length of a line, including indentation and everything, for purposes of deciding how much to pile together.
Example with MaxTotalLineLength=80
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43,
47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107,
109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181,
191, 193, 197, 199
],
"ComplexObject": {
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": { "Q": null, "W": [-2, -1, 0, 1] },
"Distraction": [[], null, null]
}
}
Example with MaxTotalLineLength=50
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19,
23, 29, 31, 37, 41, 43, 47, 53,
59, 61, 67, 71, 73, 79, 83, 89,
97, 101, 103, 107, 109, 113, 127, 131,
137, 139, 149, 151, 157, 163, 167, 173,
179, 181, 191, 193, 197, 199
],
"ComplexObject": {
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": {
"Q": null ,
"W": [-2, -1, 0, 1]
},
"Distraction": [[], null, null]
}
}
There are still some cases where a line will go longer than this value. A single element, with indentation, property name and leading and trailing comments, can still exceed the setting. Long strings, in particular, may overrun the limit.
Example with MaxTotalLineLength=80
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43,
47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107,
109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181,
191, 193, 197, 199
],
"SomeString1": "A particularly long string for demo purposes",
"SomeString2": "A shorter string" // with a comment
}
Example with MaxTotalLineLength=50
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19,
23, 29, 31, 37, 41, 43, 47, 53,
59, 61, 67, 71, 73, 79, 83, 89,
97, 101, 103, 107, 109, 113, 127, 131,
137, 139, 149, 151, 157, 163, 167, 173,
179, 181, 191, 193, 197, 199
],
"SomeString1": "A particularly long string for demo purposes",
"SomeString2": "A shorter string" // with a comment
}
MaxInlineLength
Like MaxTotalLineLength, this is used to limit how much gets put onto one line. But this one doesn't count indentation. You might use this instead of MaxTotalLineLength if you want to be sure that similar structures at different depths are formatted the same.
Example with MaxTotalLineLength=50, MaxInlineLength=80
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19,
23, 29, 31, 37, 41, 43, 47, 53,
59, 61, 67, 71, 73, 79, 83, 89,
97, 101, 103, 107, 109, 113, 127, 131
],
"Wrapper1": {
"Wrapper2": {
"Wrapper 3": {
"LongArray": [
2, 3, 5, 7, 11, 13,
17, 19, 23, 29, 31, 37,
41, 43, 47, 53, 59, 61,
67, 71, 73, 79, 83, 89,
97, 101, 103, 107, 109, 113,
127, 131
]
}
}
}
}
Example with MaxTotalLineLength=80, MaxInlineLength=50
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29,
31, 37, 41, 43, 47, 53, 59, 61, 67, 71,
73, 79, 83, 89, 97, 101, 103, 107, 109, 113,
127, 131
],
"Wrapper1": {
"Wrapper2": {
"Wrapper 3": {
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29,
31, 37, 41, 43, 47, 53, 59, 61, 67, 71,
73, 79, 83, 89, 97, 101, 103, 107, 109, 113,
127, 131
]
}
}
}
}
MaxInlineComplexity
The maximum nesting level that can be displayed on a single line. A primitive type or an empty array or object has a complexity of 0. An object or array has a complexity of 1 greater than its most complex child.
Example with MaxInlineComplexity=2
{
"ComplexObject": {
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": { "Q": null, "W": [-2, -1, 0, 1] },
"Distraction": [[], null, null]
}
}
Example with MaxInlineComplexity=1
{
"ComplexObject": {
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": {
"Q": null ,
"W": [-2, -1, 0, 1]
},
"Distraction": [[], null, null]
}
}
MaxCompactArrayComplexity
Maximum nesting level that can be arranged spanning multiple lines, with multiple items per line.
Example with MaxCompactArrayComplexity=1
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,
157, 163, 167, 173, 179, 181, 191, 193, 197, 199
],
"LongArray2": [
[19, 2],
[ 3, 8],
[14, 0],
[ 9, 9],
[ 9, 9],
[ 0, 3],
[10, 1],
[ 9, 1],
[ 9, 2],
[ 6, 13],
[18, 5],
[ 4, 11],
[12, 2]
]
}
Example with MaxCompactArrayComplexity=2
{
"LongArray": [
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,
157, 163, 167, 173, 179, 181, 191, 193, 197, 199
],
"LongArray2": [
[19, 2], [ 3, 8], [14, 0], [ 9, 9], [ 9, 9], [ 0, 3], [10, 1], [ 9, 1], [ 9, 2],
[ 6, 13], [18, 5], [ 4, 11], [12, 2]
]
}
MaxTableRowComplexity
Maximum nesting level allowed as a row of a table-formatted array/object.
Example with MaxTableRowComplexity=2, MaxInlineComplexity=2
{
"Rect" : { "position": {"x": -44, "y": 3.4 }, "color": [0, 255, 255] },
"Point": { "position": { "y": 22.0, "z": 3} },
"Oval" : { "position": null , "color": "#7f3e96" }
}
Example with MaxTableRowComplexity=1, MaxInlineComplexity=2
{
"Rect": { "position": {"x": -44, "y": 3.4}, "color": [0, 255, 255] },
"Point": { "position": {"y": 22, "z": 3} },
"Oval": {"position": null, "color": "#7f3e96"}
}
Example with MaxTableRowComplexity=1, MaxInlineComplexity=1
{
"Rect": {
"position": {"x": -44, "y": 3.4},
"color": [0, 255, 255]
},
"Point": {
"position": {"y": 22, "z": 3}
},
"Oval": {"position": null, "color": "#7f3e96"}
}
TableCommaPlacement
Where to place commas in table-formatted elements.
When set to AfterPadding, the commas come after alignment padding. This puts all of the commas for a column in a line. This can be useful for position-based processing like a text editor's rectangular selection mode. It sometimes looks silly when an array or object contains only simple strings.
Example with TableCommaPlacement=AfterPadding and NumberListAlignment=Decimal:
{
"Inventory": [
{"itm": "gadget" , "qty": 7, "unit_pr": 1.99 , "mfg": "ACME" },
{"itm": "gizmo" , "qty": 19, "unit_pr": 50 , "mfg": "ACME" },
{"itm": "whozit" , "qty": 107, "unit_pr": 0.233, "mfg": "W-Dyne"},
{"itm": "whatzit" , "qty": 82, "unit_pr": 46.25 , "mfg": "W-Dyne"},
{"itm": "thingamabob", "qty": 20, "unit_pr": 8 , "mfg": "ACME" }
],
"Beatles Songs": [
"Taxman" ,
"Hey Jude" ,
"Everybody's Got Something to Hide Except Me and My Monkey",
"Act Naturally" ,
"Ticket To Ride"
]
}
Setting it to BeforePadding looks more natural in most cases. The commas are immediately after the values to their left. It might be a little more confusing with certain number cases.
Example with TableCommaPlacement=BeforePadding and NumberListAlignment=Decimal:
{
"Inventory": [
{"itm": "gadget", "qty": 7, "unit_pr": 1.99, "mfg": "ACME" },
{"itm": "gizmo", "qty": 19, "unit_pr": 50, "mfg": "ACME" },
{"itm": "whozit", "qty": 107, "unit_pr": 0.233, "mfg": "W-Dyne"},
{"itm": "whatzit", "qty": 82, "unit_pr": 46.25, "mfg": "W-Dyne"},
{"itm": "thingamabob", "qty": 20, "unit_pr": 8, "mfg": "ACME" }
],
"Beatles Songs": [
"Taxman",
"Hey Jude",
"Everybody's Got Something to Hide Except Me and My Monkey",
"Act Naturally",
"Ticket To Ride"
]
}
Use BeforePaddingExceptNumbers if you want the BeforePadding look in all cases except number columns. (This is only meaningful when NumberListAlignment is Left or Decimal. The numbers are right-aligned with no padding in the other cases.)
Example with TableCommaPlacement=BeforePaddingExceptNumbers and NumberListAlignment=Decimal:
{
"Inventory": [
{"itm": "gadget", "qty": 7, "unit_pr": 1.99 , "mfg": "ACME" },
{"itm": "gizmo", "qty": 19, "unit_pr": 50 , "mfg": "ACME" },
{"itm": "whozit", "qty": 107, "unit_pr": 0.233, "mfg": "W-Dyne"},
{"itm": "whatzit", "qty": 82, "unit_pr": 46.25 , "mfg": "W-Dyne"},
{"itm": "thingamabob", "qty": 20, "unit_pr": 8 , "mfg": "ACME" }
],
"Beatles Songs": [
"Taxman",
"Hey Jude",
"Everybody's Got Something to Hide Except Me and My Monkey",
"Act Naturally",
"Ticket To Ride"
]
}
MinCompactArrayRowItems
Minimum number of items per line to be eligible for compact-multiline-array formatting. (This isn't exact - some data sets could confuse the evaluation.)
Example with MinCompactArrayRowItems=3, MaxTotalLineLength=100
{
"Books": [
"Harry Potter and the Philosopher's Stone",
"The Fellowship of the Ring" ,
"A Night in the Lonesome October" ,
"Neuromancer" ,
"The Hitchhiker's Guide to the Galaxy"
]
}
Example with MinCompactArrayRowItems=2, MaxTotalLineLength=100
{
"Books": [
"Harry Potter and the Philosopher's Stone", "The Fellowship of the Ring" ,
"A Night in the Lonesome October" , "Neuromancer" ,
"The Hitchhiker's Guide to the Galaxy"
]
}
AlwaysExpandDepth
Forces elements close to the root to always fully expand, regardless of other settings.
AlwaysExpandDepth=-1, MaxInlineComplexity=3
[ [1, 2, 3], [ [4, 5], [6, 7] ] ]
AlwaysExpandDepth=0, MaxInlineComplexity=3
[
[1, 2, 3],
[ [4, 5], [6, 7] ]
]
AlwaysExpandDepth=1, MaxInlineComplexity=3
[
[
1,
2,
3
],
[
[4, 5],
[6, 7]
]
]
Padding and Indenting
IndentSpaces
Indents by this number of spaces for each level of depth. (Ignored if UseTabToIndent=true.)
UseTabToIndent
If true, a single tab character is used to indent, instead of spaces.
SimpleBracketPadding
If true, a space is added between an array/object's brackets and its contents, if that array/object has a complexity of 1. That is, if it only contains primitive elements and/or empty arrays/objects.
Example with SimpleBracketPadding=false
{
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": { "Q": null, "W": [-2, -1, 0, 1] },
"Distraction": [[], null, null]
}
Example with SimpleBracketPadding=true
{
"Subthing1": { "X": 55, "Y": 19, "Z": -4 },
"Subthing2": { "Q": null, "W": [ -2, -1, 0, 1 ] },
"Distraction": [ [], null, null ]
}
NestedBracketPadding
If true, a space is added between an array/object's brackets and its contents, if that array/object has a complexity of 2 or more. That is, if it contains non-empty arrays/objects.
Example with NestedBracketPadding=true
{
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": { "Q": null, "W": [-2, -1, 0, 1] },
"Distraction": [[], null, null]
}
Example with NestedBracketPadding=false
{
"Subthing1": {"X": 55, "Y": 19, "Z": -4},
"Subthing2": {"Q": null, "W": [-2, -1, 0, 1]},
"Distraction": [[], null, null]
}
ColonPadding
If true, a space is added after a colon.
CommaPadding
If true, a space is added after a comma.
CommentPadding
If true, a space is added between a prefix/postfix comment and the element to which it is attached.
OmitTrailingWhitespace
If true, the generated JSON text won't have spaces at the ends of lines. If OmitTrailingWhitespace is false and CommaPadding is true, often lines will end in a space. (There are a few other cases where it can happen too.) Defaults to false in the .NET and JavaScript libraries for sake of backward compatibility.
JsonEolStyle
Determines which sort of line endings to use.
Miscellaneous
NumberListAlignment
Controls how lists or table columns that contain only numbers and nulls are aligned. The default value - Normalize - allows the numbers to be parsed and rewritten, all with the same number of digits after the decimal point. (This only works if all of the numbers can be written in 15 or fewer characters without scientific notation.). The other three options, Left, Right, and Decimal align the values using their exact representations from the input document.
Example with NumberListAlignment=Left, MaxTotalLineLength=60
[
{"a": 123.456 , "b": 0 , "c": 0 },
{"a": 234567.8, "b": 0 , "c": 0 },
{"a": 3 , "b": 0.00000, "c": 7e2 },
{"a": null , "b": 2e-1 , "c": 80e1},
{"a": 5.6789 , "b": 3.5e-1 , "c": 0 }
]
Example with NumberListAlignment=Right, MaxTotalLineLength=60
[
{"a": 123.456, "b": 0, "c": 0},
{"a": 234567.8, "b": 0, "c": 0},
{"a": 3, "b": 0.00000, "c": 7e2},
{"a": null, "b": 2e-1, "c": 80e1},
{"a": 5.6789, "b": 3.5e-1, "c": 0}
]
Example with NumberListAlignment=Decimal, MaxTotalLineLength=60
[
{"a": 123.456 , "b": 0 , "c": 0 },
{"a": 234567.8 , "b": 0 , "c": 0 },
{"a": 3 , "b": 0.00000, "c": 7e2},
{"a": null , "b": 2e-1 , "c": 80e1},
{"a": 5.6789, "b": 3.5e-1 , "c": 0 }
]
Example with NumberListAlignment=Normalize, MaxTotalLineLength=60
[
{"a": 123.4560, "b": 0.00, "c": 0},
{"a": 234567.8000, "b": 0.00, "c": 0},
{"a": 3.0000, "b": 0.00, "c": 700},
{"a": null , "b": 0.20, "c": 800},
{"a": 5.6789, "b": 0.35, "c": 0}
]
CommentPolicy
Determines how comments should be handled. The JSON standard doesn't allow comments, but as an unofficial extension they are fairly wide-spread and useful.
- TreatAsError - Comments found in the input will cause exceptions.
- Remove - Comments in the input won't cause exceptions, but they won't be included in the output.
- Preserve - Comments in the input will be included in the output.
PreserveBlankLines
If true, blank lines (lines containing only whitespace) from the input will be reproduced in the output.
AllowTrailingCommas
If true, the final element in an array or object in the input may have a comma after it; otherwise an exception is thrown. The JSON standard doesn't allow trailing commas, but some other tools allow them, so the option is provided for interoperability with them.
PrefixString
A string to be included at the start of every line of output. Note that if this string is anything other than whitespace, it will probably make the output invalid as JSON.