Use a decoder to decode a KDL document

At the end of the day, once you've built up your KDL decoder, this function is how you use it. Just provide your decoder and a Document to decode, and you'll either get back the data structure your decoder was designed for, or one of your error types if something went wrong.

A decoder for simple KDL values, like strings, numbers, and booleans

A decoder for KDL nodes

A decoder for KDL documents, and equivalently, child blocks of KDL nodes

'cause they're both just lists of Nodes.

Alter the output type of an existing combinator

Sometimes a simple existing decoder isn't enough. Suppose you want to decode a percentage, but in KDL it's represented as an integer between 0 and 100, but in your datastructure, you want to represent it as a floating point between 0.0 and 1.0. You could represent that decoder like this:

-- the `float` decoder automatically converts integers to floats
decodePercent = float "the data wasn't a number!"
    |> map (\input -> input / 100.0)

Note: This combinator is generic, and can be used with any of the three decoders in this module.

Require two things to be true of a value

For those familiar with the JSON decoding module, this function is included to make you feel at home. But most of the time you'll probably want to use the andApply function instead.

This function runs TWO decoders on one object. The decode succeeds only if both of the component decoders succeed. If that's the case, then the output of each constituent decoder is fed to the provided function.

Note: This combinator is generic, and can be used with any of the three decoders in this module.

Add another requirement to a decoder and combine their values through application

This can be very helpful when defining decoders for documents, properties, and arguments, especially when combined with succeed. This can be a little easier to see through example:

type MyWeirdDatatype = MyWeirdDatatype String Int


mkMyWeirdDatatype : Int -> String -> Int -> MyWeirdDatatype
mkMyWeirdDatatype x str y = MyWeirdDatatype str (x - y)


decodeMyWeirdData : DocumentDecoder String MyWeirdDatatype
decodeMyWeirdData =
    succeed mkMyWeirdDatatype
        |> andApply (argument "needs 3 args" (int "expected an int"))
        |> andApply (argument "needs 3 args" (string "expected a string"))
        |> andApply (argument "needs 3 args" (int "expected an int"))
        |> andRequire (noOtherArguments "too many arguments!")
        |> andRequire (noOtherProperties "shouldnt be any properties")
        |> andRequire (noChildren "shouldnt be any children!")
        |> singleNodeDocument "no node provided!" "only expected one node!" "unrecognized node!" "my-weird-data"


(parse "my-weird-data 5 meowy 2" |> Result.map (decode decodeMyWeirdData)) == Ok (Ok (MyWeirdDatatype "meowy" 3))

Note: This combinator is generic, and can be used with any of the three decoders in this module, though most of the time you'll be using it with NodeDecoders.

A version of andApply that ignores the output of its first argument and while still adding the constraints

Note: This combinator is generic, and can be used with any of the three decoders in this module, though most of the time you'll be using it with NodeDecoders.

Run a decoder, then run a function on the result to produce a new decoder, which is also run.

Sometimes the behaviour of the decoder going forward is contingent on values already decoded. This is the function to turn to in that case. Analagous to Json.Decode.andThen.

Note: This combinator is generic, and can be used with any of the three decoders in this module.

A decoder that always succeeds and produces a value of your choice

Note: This combinator is generic, and can be used with any of the three decoders in this module.

Decode any rational number

This will handle integers, numbers with decimals, and even numbers with exponents, like 120.9312e100, however, it can't decode special "numbers" like NaN (#nan) or infinity (#inf), and will return its first argument as an error if applied to any of these.

Of course, this will also give its first argument as an error when applied to non-numeric data, like strings or booleans.

Decode a number as a floating point

Unlike rational, this can decode values like NaN (#nan) and infinity (#inf), but may not necessarily represent a number with maximal position, and can introduce minor numeric errors, so isn't ideal for situations where absolute accuracy is important.

This will also give its first argument as an error when applied to non-numeric data, like strings or booleans.

Decode a number as an integer

This will decode a value as an integer. However, it will fail (and return its first argument as an error) if used to decode non-integer data, or any numbers too large or to small to be represented by Elm's Int type.

Note that 1.1e1 and 1.0 are considered integers.

This will also give its first argument as an error when applied to non-numeric data, like strings or booleans.

Decode a string

This will decode any quoted string, bare string, raw string, or multiline string of any variety into an Elm String

This will return its first argument as an error when applied to non-string data, like numbers or booleans.

Decode a Boolean

This will decode #true and #false into their Elm Bool equivalents

This will return its first argument as an error when applied to non-boolean data, like numbers or strings.

Require a value to be #null

This decoder only succeeds when applied to the KDL value #null. Its return value is always unit, aka the empty tuple, aka ().

This will return its first argument as an error when applied to anything other then #null.

Require that a condition be true of the value returned by a ValueDecoder

If that condition isn't true, then an error of your choice is raised. Here's a simple example. Say you want a node count that only accepts non-negative integers as an argument. You could describe this node like this:

decodeCount =
    argument "count needs 1 argument" (
        int "argument must be an integer"
        |> guardV "can't have a negative count!" (\x -> x >= 0)
    )
    |> andRequire (noOtherArguments "too many arguments on count!")
    |> singleNodeDocument "missing node!" "extra node!" "unrecognized node!" "count"

See also: guardN, the NodeDecoder equivalent of this function

A decoder which always fails with an error of your choice rather than parsing a value

Try several different decoders to see if any work

Sometimes, you'll need to decode a value which could have one of several possible types. For example, say you have a date node which can be followed by either an integer (which should be interpretted as a UNIX timestamp) or a string (which should be interpretted as a string). For example, say you have a date node which can be followed by either an integer (which should be interpretted as a UNIX timestamp) or a string (which should be interpretted as a string). In this case, you can't just decode that value using string or int — you'll need to try both to see which one works. Here's how you can do that with oneOfV:

type MyDate
    = Datestring String
    | UnixTime Int


decodeDate : DocumentDecoder String MyDate
decodeDate =
    argument "date takes one argument"
        (
            oneOfV "dates must be either strings or ints!"
                [ string () |> map Datestring
                , int () |> map UnixTime
                ]
        )
    |> andRequire (noOtherArguments "too many arguments!")
    |> singleNodeDocument "missing node" "too many nodes" "unrecognized node" "date"


(parse "date 1733882937" |> Result.map (decode decodeDate)) == Ok (Ok (UnixTime 1733882937))

oneOfV takes two arguments. The first is an error to return if all other errors fail. The second is a list of decoders that should be tried. Note that all errors from the internal parsers are discarded if those parsers fail.

Add a required argument to a node

The argument takes the form of a ValueDecoder, which will be used to decode the argument itself. If the argument is absent, however, the provided error will be returned instead.

One thing to keep in mind is that arguments are order sensitive. Arguments will be expected to appear in the same order that they are applied to the NodeDecoder being built. That is:

-- Decodes `tuple hi 1` but not `tuple 1 hi`
tuple1 = succeed pair
    |> andApply (argument "two args required!" (string "first argument should be a string")) 
    |> andApply (argument "two args required!" (int "second argument should be an int")) 
    |> andRequire (noOtherArguments "only 2-tuples are supported")
    |> singleNodeDocument "missing node" "too many nodes" "wrong node name" "tuple"


-- Decodes `tuple 1 hi` but not `tuple hi 1`
tuple2 = succeed pair
    |> andApply (argument "two args required!" (int "first argument should be an int")) 
    |> andApply (argument "two args required!" (string "second argument should be a string")) 
    |> andRequire (noOtherArguments "only 2-tuples are supported")
    |> singleNodeDocument "missing node" "too many nodes" "wrong node name" "tuple"

Similarly, if noOtherArguments or arguments is used, they should be come after all other arguments.

If you'd rather the argument be completely optional, see optionalArgument. If you would like to decode an arbitrary number of arguments all using the same decoder, see arguments.

This function mirrors the behavior of property, but for arguments rather than properties.

Add an optional argument to a node

If any (not-yet-decoded) argument is present, this decodes it with the provided decoder. Notice that the returned parser decodes to Maybe t rather than just t. This is because Nothing will be the result when the argument is absent.

Please read the documentation for argument for important details regarding ordering.

This mirrors the behavior of optionalProperty for arguments rather than properties.

Decodes all remaining arguments into a list

Requires that you provide a decoder which will be used on all arguments which have not yet been decoded. The results of each decode will be compiled into a list.

This mirrors the behavior of properties but for arguments rather than properties.

Automatically fails if there are any arguments which have not yet been decoded

By default, if there are trailing arguments which don't get decoded, they are simply ignored. For example, the pair parser from the argument documentation will parse tuple 1 hi, but also tuple 1 hi #nan etc etc. This behavior isn't always optimal, since it can lead to users not realizing they're misusing something. Applying this function causes your parser to error if there are any trailing arguments.

Also notice that noOtherArguments and arguments mutually make the other redundant. When noOtherArguments comes first, arguments is guaranteed to decode nothing (and produce the empty list). Meanwhile, if arguments comes first, noOtherArguments is guaranteed to succeed, as arguments is guaranteed to decode all the arguments if it succeeds.

This mirrors the behavior of noOtherProperties but for arguments rather than properties.

Require that a node have a certain property

This adds a requirement of a certain property to a node, which must be present on the node for the parse to succeed. The ifAbsent argument is returned as an error if the property is missing from the node. Otherwise, it's decoded using the decodePropertyValue node. propertyKey is the name of the property.

Note that this is order sensitive. When building a decoder, if you first decode a property, then use properties or noOtherProperties, this property will be "accounted for", and not count towards the properties decoded by either of those two functions. Inversely, if you run noOtherProperties before running property, the resulting decoder will always fail, either because the property was present, but got passed to noOtherProperties first, or because it was absent.

This function mirrors the behavior of argument but for properties rather than arguments.

Optionally decode a property

The resulting node decoder will produce Nothing when the property is absent, or Just when the property is present and can be decoded by the provided decoder.

See property for important notes regarding ordering

As with other node decoders, you'll probably want to chain this with other decoders using andThen and succeed.

This mirrors the behavior of optionalArgument for properties rather than arguments.

Decodes an arbitrary number of properties agnostic regardless of key

You provide a decoder for the value attached to each key, and the decoder decodes each value, and produces a Dict mapping each property name to the resulting value.

Pay attention to the ordering between this and property/optionalProperty. Putting either property or optionalProperty will exclude that property from the set of properties decoded by this function.

This is, in effect, mutually exclusive with noOtherProperties

This mirrors the behavior of arguments but for properties rather than arguments.

Automatically fail if any properties have yet to be decoded

By default, if there are properties which don't get decoded, they are simply ignored. This behavior isn't always optimal, since it can lead to users not realizing they're misusing something. Applying this function causes your parser to error if there are any arguments that are unaccounted for.

This mirrors the behavior of noOtherArguments but for properties rather than arguments.

Parse the children of a node

The children of a node is parsed as just another document. Any of the functions you use to create DocumentDecoders can be used to construct a document decoder which works for the children of a node.

By default, any child nodes are simply ignored without fanfare, but you can specify a specific expectation by either using this function or noChildren, which can ensure that the child nodes are what you expect.

See also: document

Assert that a node does not have any children

Instead of simply ignoring the children of a node, it's often preferable to ensure that the node definitely does not have children, and therefore is less likely to be being used incorrectly. This function concisely accomplishes that.

Equivalent to children (noOtherNodes <error>)

See also: children, noOtherEntries

Decode a node, yeilding its name

It's still possible to decode other parts of the node using other node decoders. It's often helpful to use a pattern like the one demonstrated in the example of andApply. If you just need to check that the name is equal to a certain value, you might prefer assertNodeName.

Require that a condition be true of the value returned by a NodeDecoder

If that condition isn't true, then an error of your choice is raised. Here's one way you could use this to parse a list that needs at least three elments:

-- Decodes "favorite-things \"raindrops on roses\" \"whiskers on kittens\" \"bright copper kettles\""
-- But fails on "favorite-things \"pussy willows\" \"christmas\""
decodeFavoriteThings =
    arguments (string "your favorite things must be strings!")
    |> guardN "You need to least at least three of your favorite things" (\l -> length l >= 3)
    |> singleNodeDocument "missing node!" "extra node!" "unrecognized node!" "favorite-things"

See also: guardV, the ValueDecoder equivalent of this function

A decoder which always fails with an error of your choice rather than parsing a node

Decode one entry which should occur exactly once

Takes four arguments:

• An error to return when the entry is absent
• An error to return when the entry occurs more than once
• The name of the entry (aka the name of the node to look for)
• A decoder for the node once it's found

Decode an entry which may occur any number of times (including zero)

Takes two arguments:

• The name of the entries (aka the name of the nodes to look for)
• A decoder for the node once it's found

Decode an entry which can occur zero or one times

Takes two arguments:

• An error to return when the entry occurs more than once
• The name of the entry (aka the name of the node to look for)
• A decoder for the node once it's found

Only succeed when a document has no nodes left

Any nodes proccessed by entry, optionalEntry, and entries are omitted from the count.

The first argument is the error to produce if any nodes are present at all.

This can also be used to decode an empty document.

Decode a dict-like document

For each node in the document, that node is treated like an entry in a dictionary. The name of the node is seen as the key, and the value is what that node decodes to. Consider this subsection of the cargo.kdl official KDL example:

dependencies {
    nom "6.0.1"
    thiserror "1.0.22"
}

We could parse this like so:

decodeDependencyVersion : NodeDecoder String String
decodeDependencyVersion =
    argument "missing version" (string "version should be a string")
    |> andRequire (noOtherArguments "a dependency should only have one version")
    |> andRequire (noOtherProperties "dependency properties aren't supported")
    |> andRequire (noChildren "dependencies can't have children")


decodeDependencies : DocumentDecoder String (Dict String String)
decodeDependencies =
    dictDocument "dependencies can only be listed once" decodeDependencyVersion 
    |> children
    |> andRequire (noOtherArguments "specify dependencies in the child block")
    |> andRequire (noOtherProperties "specify dependencies in the child block")
    |> singleNodeDocument "missing dependency block" "multiple dependency blocks" "unrecognized node" "dependencies"

Notice that this will return "dependencies can only be listed once" if someone tries to specify a dependency twice.

Decode a document as if it were a multidict (a dict that can have multiple values associated with a single key)

This behaves much like dictDocument, but rather than raise an error when there are multiple nodes with one key,

Decode a document with exactly one node with a fixed name

Best used when your document only has one node, and that node should always have the same name. If you have multiple types of nodes that could appear, you might prefer to use singleNodeDocumentF.

The first three arguments are error values to return if the document is empty (contains no nodes), if there is an extra node that's unaccounted for, and if the name of the node in the document isn't the expected one.

The next two arguments specify the expected name of the node and the NodeDecoder that should be used for it.

Decode a document with exactly one node, but where there might be several possible types of nodes.

Rather than only parse a single type of node (with a fixed name), this function lets you conditionally accept or deny multiple types of nodes based on their name.

The first two arguments are errors to return if the node is absent, or if there is more than one node present. Then the third and final argument is a function which decides what NodeDecoder to use for a given node name.

Keep in mind that you can return failN to reject a node that has a name you don't support.

See also:

• singleNodeDocument, a version of this function for a fixed node name
• documentF, a version of this which can accept multiple nodes, not just one.

Decode a docmunt with an arbitrary number of nodes

This is the most basic, unspecialized type of document decoder. It simply decodes all of the nodes that appear in the document, in order, choosing a NodeDecoder based on the provided lookup table.

For each node to be decoded, its name will be checked against the provided Dict. If a decoder is found there, it will be returned. Otherwise, the the ifUnrecognized error is returned.

It is often helpful to set fallbackNodeDecoder to fail with some error.

For a more powerful version of this, see documentF.

Decode a document with an arbitrary number of nodes, and the power to choose which decoder to use based on an algorithm

Similar to document, documentF allows for parsing an arbitrary number of nodes in a document, ultimately yeilding a list. But while document chose how to decode a node based on a Dict lookup, and always failed when the node was absent from the dict, documentF allows you to specify your own algorithm for choosing a subsequent decoder.