Toml.Edit

The value at a path, if a key there holds one.

Whether a key is in the document at all.

get answers this too, but answering it with get means holding a Toml.Ast.Value in order to throw it away, and the question a program writing a config file asks is usually this one: is this key already here, or am I the one putting it there? That is what decides whether it needs an explanation written above it -- see introduce.

Put a value at a path.

If a key is already there, only its value changes: the key keeps its spelling, the equals sign keeps the whitespace around it, and the comment on the line stays where it was. Nothing else in the file moves.

If there is no such key, one is added. It goes at the end of the table it belongs to, after the last key already in it, indented to match. If the table does not exist either, a [header] for it is appended to the end of the file with the key beneath and a blank line above, and a file that ended with a newline still does.

A top-level key added to a file that has no top-level keys yet goes before the first [header], with a blank line between, since anything written after a header belongs to that header's table. It goes above the comment block directly over that header too, because that block is the header's by the convention above; a comment with a blank line under it stays where it is.

A value that is already what you are setting it to is left exactly as it is written. This is not thrift, it is the difference between an editor and an encoder, and it is the one thing about this module worth reading twice.

Setting a value replaces the whitespace inside it, because the whitespace was part of the old value and the new one has none of its own. So a list somebody arranged by hand:

ports = [
  8000,  # http
  8001   # https
]

written back with set [ "ports" ] (array [ int 8000, int 8001 ]) would come out as ports = [8000, 8001]. That is right for a list that changed -- there is no old formatting to keep for a new value -- and it is destructive for one that did not.

Which is the case that actually happens. A program that writes its whole configuration out on every save touches every key, so the key the user hand-arranged gets flattened by a save about some other key. Comparing first is what stops that, and doing it here rather than leaving it to every caller is the only way it gets done: the caller would have to hold the old document, take it apart, and know that 1.50 and 1.5 are the same number and 0x1F and 31 are the same integer.

The comparison is by value and not by text. A string is its characters after escapes, an integer or float is its number whatever base or spelling it was written in, a date-time is the instant and the offset, an array is its elements in order, and an inline table is its entries in order. So set over 0x1F with int 31 changes nothing and the file keeps saying 0x1F. To change the spelling rather than the value, remove the key and set it again. That takes the comments the key owned away with the line, so read them first with comments and put them back with setComments after.

An edit that gives the file a meaning it cannot have -- a key under an inline table, say -- is not refused here. See what this module does not check.

Set a value, and explain the key if this is the call that put it there.

Toml.Edit.introduce [ "theme" ]
    { blankBefore = True
    , leading = [ " Which colour scheme to open in." ]
    , trailing = Nothing
    }
    (Toml.Edit.string "dark")

set and setComments together, except that the comments are written only when the key was not already in the document.

That condition is the whole reason this exists, and it is a rule about the person on the other end of the file rather than about TOML. A program that keeps a config file wants every key it invents to arrive with a sentence saying what the key is for, because a config file whose fields are undocumented is one nobody opens. It does not want to write that sentence again on every save: the user who deleted it meant to delete it, and the user who rewrote it in their own language has not made a mistake for the next save to correct.

On a document with the key already in it this is exactly set, comments and all left alone. On Toml.empty it writes the key and the explanation together, which is how a file that has never existed comes out documented.

Take a key out, and the comments that belong to it with it.

The line goes, its leading comment block goes, and its trailing comment goes with the line it was on. A floating comment -- one with a blank line above it -- stays, which is the whole point of the blank line.

Nothing else changes. Removing the last key of a table leaves the [header] behind, because an empty table is still a table and saying otherwise would be this module deciding something the file did not.

Take a whole table out: its [header], everything under it, and the comments that belong to the header.

Sub-tables go too, since [a.b] is under [a]. An array of tables named by the path goes entirely, every item of it.

Give a key a new name and change nothing else.

Toml.Edit.rename [ "server", "port" ] "listen"

-->  [server]
-->  listen = 8443       # was: port = 8443

The value stays as it was written, the whitespace around the equals sign stays, and the comments stay with the line. The new name is spelled bare where the grammar allows it and quoted where it does not.

Only the last part of the path is the name: this renames the key port, not the table server. For a table see renameTable.

Whether the new name is already taken is not asked here. It is not a question about syntax, so the answer comes from Toml.Table.fromDocument, like every other question of its kind -- see the two layers in Toml.Table.

Give a table a new name: its own [header], every header nested under it, and every dotted key that spells the name out itself.

Toml.Edit.renameTable [ "server" ] "listener"

-->  [listener]
-->  [listener.tls]

Only the last part of the path is the name, as with rename, so a table's ancestors never move and nothing has to be lifted into a different section for the result to mean what it says.

A dotted key changes only where the renamed part is a table it passes through: renameTable [ "a" ] "x" turns a.b = 1 into x.b = 1 and leaves b alone, because b names the value rather than a table. By the same rule this does nothing to a path that names a key: [ "server", "port" ] is not a table, and rename is the one that renames it.

The comments that belong to a key, by the convention above.

{ blankBefore = True
, leading = [ " how long to wait" ]
, trailing = Just " seconds"
}

This and setComments are inverses: what one reads, the other writes back unchanged. A key that is not in the document has no comments and reads as { blankBefore = False, leading = [], trailing = Nothing }.

Set the comments that belong to a key, by the same convention comments reads them by.

Toml.Edit.setComments [ "timeout" ]
    { blankBefore = True
    , leading = [ " How long to wait." ]
    , trailing = Just " seconds"
    }

-->  <a blank line>
-->  # How long to wait.
-->  timeout = 30 # seconds

comments and this are inverses, so what one reads the other writes back unchanged -- including the blank line, which is why Comments has a field for it.

leading = [] takes the block above the key away and trailing = Nothing takes the comment off the line. Anything separated from the key by a blank line is not the key's and is left alone, which is the same blank line that protects it from remove. A key that is not there is left alone too.

blankBefore = True puts a blank line above the block if there is not one already, and False takes one away if there is. Asking for one does nothing at the top of the document, where there is no line above to be blank, and does nothing directly under a [header], where the key is the first of its table and a blank would hold it off the header it belongs to -- the same rule Toml.Encode writes by. Taking one away is the one thing here that reaches past the key's own lines, so it is worth knowing what it does: the blank line is what separates a floating comment from an owned one, and removing it makes the block above join this key's -- which is to say it will go when this key goes.

The comments that belong to a table's [header] line: the block directly above it and the comment beside it, by the same convention as a key's, and the same ones removeTable takes with the table.

Toml.Edit.tableComments [ "servers", "alpha" ]

-->  { blankBefore = True, leading = [ " The primary." ], trailing = Nothing }

For an array of tables the path means the first [[header]], which is the other way round from every other path in this module. A path into an array of tables names its last item when it names a value, because that is the item TOML means by it. A comment over a header explains the key -- the whole array -- and the first header is where Toml.Encode writes it. The other items are reached through the AST.

A table with no header line of its own -- one that only [a.b] implied, or one a dotted key built -- has no line for a comment to be on, and reads as { blankBefore = False, leading = [], trailing = Nothing }. So does a table that is not there.

Set the comments that belong to a table's [header] line, by the same convention tableComments reads them by.

Toml.Edit.setTableComments [ "servers", "alpha" ]
    { blankBefore = True, leading = [ " The primary." ], trailing = Nothing }

-->  <a blank line>
-->  # The primary.
-->  [servers.alpha]

The two are inverses, as comments and setComments are, and for an array of tables the path means the first [[header]] for the reason given there.

This is how a program explains a section it created. introduce explains a key, and the header it brought with that key has nothing over it until this is called; calling it only when member said the first key was not there yet keeps the explanation to the run that invented the section, which is the same rule introduce keeps for a key.

One difference from setComments: blankBefore = True directly under another header is honoured. The first key of a table belongs against its header, but a nested header directly under its parent is two sections meeting, and the blank between them is the one Toml.Encode keeps. At the top of the file it is still a no-op.

A table with no header line, or none at all, is left alone.

Every key in the document, in the order the file writes them.

Table headers are not keys and are not here; the path of a key written under [server] begins with server all the same.

A string.

An integer that fits in a Gren Int.

An integer of any size.

A float. inf and nan are written as those words; everything else gets a decimal point even when it does not need one, since 1 without one is an integer in TOML.

An exact decimal.

A boolean.

A date and time with an offset.

A date and time with no offset.

A date.

A time of day.

An array, on one line: [1, 2, 3].

Toml.Edit.set [ "ports" ]
    (Toml.Edit.array [ Toml.Edit.int 80, Toml.Edit.int 443 ])

An array already in the file keeps every character of itself for as long as nothing is set over it, newlines and comments inside the brackets included. This is the spelling for one that is being written fresh.

An inline table, on one line: { a = 1, b = 2 }.

Toml.Edit.set [ "limits" ]
    (Toml.Edit.inlineTable
        [ { key = "soft", value = Toml.Edit.int 1024 }
        , { key = "hard", value = Toml.Edit.int 4096 }
        ]
    )

This is also how to change something inside an inline table, since a path does not reach in -- see what a path means. Build the table you want and set the whole of it.

There is no builder here for a [header] table, because a header is a line rather than a value and set puts values on lines. A key under a header that does not exist yet already brings one with it.