# LLM Prompt for Documentation

## Documentation

### Parser

#### Parser

**Type Annotation**

**Description**

Opaque type for a parser that will try to parse an `a` from an `input`.

As such, a parser can be considered a recipe for a function of the type
```
input -> Result {val: a, input: input} [ParsingFailure Str]
```

How a parser is _actually_ implemented internally is not important
and this might change between versions;
for instance to improve efficiency or error messages on parsing failures.

#### ParseResult

**Type Annotation**

**Description**

```
ParseResult input a : Result { val : a, input : input } [ParsingFailure Str]
```

#### buildPrimitiveParser

**Type Annotation**

```roc
(input -> ParseResult input a) -> Parser input a
```

**Description**

Write a custom parser without using provided combintors.

#### parsePartial

**Type Annotation**

```roc
Parser input a, input -> ParseResult input a
```

**Description**

Most general way of running a parser.

Can be thought of as turning the recipe of a parser into its actual parsing function
and running this function on the given input.

Moat parsers consume part of `input` when they succeed. This allows you to string parsers
together that run one after the other. The part of the input that the first
parser did not consume, is used by the next parser.
This is why a parser returns on success both the resulting value and the leftover part of the input.

This is mostly useful when creating your own internal parsing building blocks.

#### parse

**Type Annotation**

```roc

    Parser input a, 
    input, 
    (input -> Bool)
    -> Result a 
        [
            ParsingFailure Str,
            ParsingIncomplete input
        ]
```

**Description**

Runs a parser on the given input, expecting it to fully consume the input

The `input -> Bool` parameter is used to check whether parsing has 'completed',
i.e. how to determine if all of the input has been consumed.

For most input types, a parsing run that leaves some unparsed input behind
should be considered an error.

#### fail

**Type Annotation**

```roc
Str -> Parser * *
```

**Description**

Parser that can never succeed, regardless of the given input.
It will always fail with the given error message.

This is mostly useful as a 'base case' if all other parsers
in a `oneOf` or `alt` have failed, to provide some more descriptive error message.

#### const

**Type Annotation**

```roc
a -> Parser * a
```

**Description**

Parser that will always produce the given `a`, without looking at the actual input.
This is useful as a basic building block, especially in combination with
`map` and `apply`.
```
parseU32 : Parser (List U8) U32
parseU32 =
    const Num.toU32
    |> keep digits

expect parseStr parseU32 "123" == Ok 123u32
```

#### alt

**Type Annotation**

```roc
Parser input a, Parser input a -> Parser input a
```

**Description**

Try the `first` parser and (only) if it fails, try the `second` parser as fallback.

#### apply

**Type Annotation**

```roc
Parser input (a -> b), Parser input a -> Parser input b
```

**Description**

Runs a parser building a function, then a parser building a value,
and finally returns the result of calling the function with the value.

This is useful if you are building up a structure that requires more parameters
than there are variants of `map`, `map2`, `map3` etc. for.

For instance, the following two are the same:
```
const (\x, y, z -> Triple x y z)
|> map3 String.digits String.digits String.digits

const (\x -> \y -> \z -> Triple x y z)
|> apply String.digits
|> apply String.digits
|> apply String.digits
```
Indeed, this is how `map`, `map2`, `map3` etc. are implemented under the hood.

# Currying
Be aware that when using `apply`, you need to explicitly 'curry' the parameters to the construction function.
This means that instead of writing `\x, y, z -> ...`
you'll need to write `\x -> \y -> \z -> ...`.
This is because the parameters of the function will be applied one by one as parsing continues.

#### oneOf

**Type Annotation**

```roc
List (Parser input a) -> Parser input a
```

**Description**

Try a list of parsers in turn, until one of them succeeds.
```
color : Parser Utf8 [Red, Green, Blue]
color =
    oneOf [
        const Red |> skip (string "red"),
        const Green |> skip (string "green"),
        const Blue |> skip (string "blue"),
    ]

expect parseStr color "green" == Ok Green
```

#### map

**Type Annotation**

```roc
Parser input a, (a -> b) -> Parser input b
```

**Description**

Transforms the result of parsing into something else,
using the given transformation function.

#### map2

**Type Annotation**

```roc

    Parser input a, 
    Parser input b, 
    (a, b -> c)
    -> Parser input c
```

**Description**

Transforms the result of parsing into something else,
using the given two-parameter transformation function.

#### map3

**Type Annotation**

```roc

    Parser input a, 
    Parser input b, 
    Parser input c,     
    (a, 
    b, 
    c
    -> d)
    -> Parser input d
```

**Description**

Transforms the result of parsing into something else,
using the given three-parameter transformation function.

If you need transformations with more inputs,
take a look at `apply`.

#### flatten

**Type Annotation**

```roc
Parser input (Result a Str) -> Parser input a
```

**Description**

Removes a layer of `Result` from running the parser.

Use this to map functions that return a result over the parser,
where errors are turned into `ParsingFailure`s.

```
# Parse a number from a List U8
u64 : Parser Utf8 U64
u64 =
    string
    |> map \val ->
        when Str.toU64 val is
            Ok num -> Ok num
            Err _ -> Err "$(val) is not a U64."
    |> flatten
```

#### lazy

**Type Annotation**

```roc
({} -> Parser input a) -> Parser input a
```

**Description**

Runs a parser lazily

This is (only) useful when dealing with a recursive structure.
For instance, consider a type `Comment : { message: String, responses: List Comment }`.
Without `lazy`, you would ask the compiler to build an infinitely deep parser.
(Resulting in a compiler error.)


#### maybe

**Type Annotation**

```roc
Parser input a -> Parser input (Result a [Nothing])
```

#### many

**Type Annotation**

```roc
Parser input a -> Parser input (List a)
```

**Description**

A parser which runs the element parser *zero* or more times on the input,
returning a list containing all the parsed elements.

Also see [Parser.oneOrMore].

#### oneOrMore

**Type Annotation**

```roc
Parser input a -> Parser input (List a)
```

**Description**

A parser which runs the element parser *one* or more times on the input,
returning a list containing all the parsed elements.

Also see [Parser.many].

#### between

**Type Annotation**

```roc

    Parser input a, 
    Parser input open, 
    Parser input close
    -> Parser input a
```

**Description**

Runs a parser for an 'opening' delimiter, then your main parser, then the 'closing' delimiter,
and only returns the result of your main parser.

Useful to recognize structures surrounded by delimiters (like braces, parentheses, quotes, etc.)

```
betweenBraces  = \parser -> parser |> between (scalar '[') (scalar ']')
```

#### sepBy1

**Type Annotation**

```roc
Parser input a, Parser input sep -> Parser input (List a)
```

#### sepBy

**Type Annotation**

```roc
Parser input a, Parser input sep -> Parser input (List a)
```

**Description**

```
parseNumbers : Parser (List U8) (List U64)
parseNumbers =
    digits |> sepBy (codeunit ',')

expect parseStr parseNumbers "1,2,3" == Ok [1,2,3]
```

#### ignore

**Type Annotation**

```roc
Parser input a -> Parser input {}
```

#### keep

**Type Annotation**

```roc
Parser input (a -> b), Parser input a -> Parser input b
```

#### skip

**Type Annotation**

```roc
Parser input a, Parser input * -> Parser input a
```

#### chompUntil

**Type Annotation**

```roc
a -> Parser (List a) (List a)
    where a implements Eq
```

**Description**

Match zero or more codeunits until the it reaches the given codeunit.
The given codeunit is not included in the match.

This can be used with [Parser.skip] to ignore text.

```
ignoreText : Parser (List U8) U64
ignoreText =
    const (\d -> d)
    |> skip (chompUntil ':')
    |> skip (codeunit ':')
    |> keep digits

expect parseStr ignoreText "ignore preceding text:123" == Ok 123
```

This can be used with [Parser.keep] to capture a list of `U8` codeunits.

```
captureText : Parser (List U8) (List U8)
captureText =
    const (\codeunits -> codeunits)
    |> keep (chompUntil ':')
    |> skip (codeunit ':')

expect parseStr captureText "Roc:" == Ok ['R', 'o', 'c']
```

Use [String.strFromUtf8] to turn the results into a `Str`.

Also see [Parser.chompWhile].

#### chompWhile

**Type Annotation**

```roc
(a -> Bool) -> Parser (List a) (List a)
    where a implements Eq
```

**Description**

Match zero or more codeunits until the check returns false.
The codeunit that returned false is not included in the match.
Note: a chompWhile parser always succeeds!

This can be used with [Parser.skip] to ignore text.
This is useful for chomping whitespace or variable names.

```
ignoreNumbers : Parser (List U8) Str
ignoreNumbers =
    const (\str -> str)
    |> skip (chompWhile \b -> b >= '0' && b <= '9')
    |> keep (string "TEXT")

expect parseStr ignoreNumbers "0123456789876543210TEXT" == Ok "TEXT"
```

This can be used with [Parser.keep] to capture a list of `U8` codeunits.

```
captureNumbers : Parser (List U8) (List U8)
captureNumbers =
    const (\codeunits -> codeunits)
    |> keep (chompWhile \b -> b >= '0' && b <= '9')
    |> skip (string "TEXT")

expect parseStr captureNumbers "123TEXT" == Ok ['1', '2', '3']
```

Use [String.strFromUtf8] to turn the results into a `Str`.

Also see [Parser.chompUntil].

### String

#### Utf8

**Type Annotation**

**Description**

```
Utf8 : List U8
```

#### parseStr

**Type Annotation**

```roc

    Parser Utf8 a, 
    Str
    -> Result a 
        [
            ParsingFailure Str,
            ParsingIncomplete Str
        ]
```

**Description**

Parse a [Str] using a [Parser]
```
color : Parser Utf8 [Red, Green, Blue]
color =
    oneOf [
        Parser.const Red |> Parser.skip (string "red"),
        Parser.const Green |> Parser.skip (string "green"),
        Parser.const Blue |> Parser.skip (string "blue"),
    ]

expect parseStr color "green" == Ok Green
```

#### parseStrPartial

**Type Annotation**

```roc
Parser Utf8 a, Str -> Parser.ParseResult Str a
```

**Description**

Runs a parser against the start of a string, allowing the parser to consume it only partially.

- If the parser succeeds, returns the resulting value as well as the leftover input.
- If the parser fails, returns `Err (ParsingFailure msg)`


```
atSign : Parser Utf8 [AtSign]
atSign = Parser.const AtSign |> Parser.skip (codeunit '@')

expect parseStr atSign "@" == Ok AtSign
expect parseStrPartial atSign "@" |> Result.map .val == Ok AtSign
expect parseStrPartial atSign "$" |> Result.isErr
```

#### parseUtf8

**Type Annotation**

```roc

    Parser Utf8 a, 
    Utf8
    -> Result a 
        [
            ParsingFailure Str,
            ParsingIncomplete Utf8
        ]
```

**Description**

Runs a parser against a string, requiring the parser to consume it fully.

- If the parser succeeds, returns `Ok a`
- If the parser fails, returns `Err (ParsingFailure Str)`
- If the parser succeeds but does not consume the full string, returns `Err (ParsingIncomplete (List U8))`

#### parseUtf8Partial

**Type Annotation**

```roc
Parser Utf8 a, Utf8 -> Parser.ParseResult Utf8 a
```

**Description**

Runs a parser against the start of a list of scalars, allowing the parser to consume it only partially.

#### codeunitSatisfies

**Type Annotation**

```roc
(U8 -> Bool) -> Parser Utf8 U8
```

**Description**

```
isDigit : U8 -> Bool
isDigit = \b -> b >= '0' && b <= '9'

expect parseStr (codeunitSatisfies isDigit) "0" == Ok '0'
expect parseStr (codeunitSatisfies isDigit) "*" |> Result.isErr
```

#### codeunit

**Type Annotation**

```roc
U8 -> Parser Utf8 U8
```

**Description**

```
atSign : Parser Utf8 [AtSign]
atSign = Parser.const AtSign |> Parser.skip (codeunit '@')

expect parseStr atSign "@" == Ok AtSign
expect parseStrPartial atSign "$" |> Result.isErr
```

#### utf8

**Type Annotation**

```roc
List U8 -> Parser Utf8 (List U8)
```

**Description**

Parse an extact sequence of utf8

#### string

**Type Annotation**

```roc
Str -> Parser Utf8 Str
```

**Description**

Parse the given [Str]
```
expect parseStr (string "Foo") "Foo" == Ok "Foo"
expect parseStr (string "Foo") "Bar" |> Result.isErr
```

#### anyCodeunit

**Type Annotation**

```roc
Parser Utf8 U8
```

**Description**

Matches any [U8] codeunit
```
expect parseStr anyCodeunit "a" == Ok 'a'
expect parseStr anyCodeunit "$" == Ok '$'
```

#### anyThing

**Type Annotation**

```roc
Parser Utf8 Utf8
```

**Description**

Matches any [Utf8] and consumes all the input without fail.
```
expect
    bytes = Str.toUtf8 "consumes all the input"
    Parser.parse anyThing bytes List.isEmpty == Ok bytes
```

#### anyString

**Type Annotation**

```roc
Parser Utf8 Str
```

#### digit

**Type Annotation**

```roc
Parser Utf8 U64
```

**Description**

```
expect parseStr digit "0" == Ok 0
expect parseStr digit "not a digit" |> Result.isErr
```

#### digits

**Type Annotation**

```roc
Parser Utf8 U64
```

**Description**

Parse a sequence of digits into a [U64], accepting leading zeroes
```
expect parseStr digits "0123" == Ok 123
expect parseStr digits "not a digit" |> Result.isErr
```

#### oneOf

**Type Annotation**

```roc
List (Parser Utf8 a) -> Parser Utf8 a
```

**Description**

Try a bunch of different parsers.

The first parser which is tried is the one at the front of the list,
and the next one is tried until one succeeds or the end of the list was reached.
```
boolParser : Parser Utf8 Bool
boolParser =
    oneOf [string "true", string "false"]
    |> Parser.map (\x -> if x == "true" then Bool.true else Bool.false)

expect parseStr boolParser "true" == Ok Bool.true
expect parseStr boolParser "false" == Ok Bool.false
expect parseStr boolParser "not a bool" |> Result.isErr
```

#### strFromUtf8

**Type Annotation**

```roc
Utf8 -> Str
```

#### strFromAscii

**Type Annotation**

```roc
U8 -> Str
```

### CSV

#### CSV

**Type Annotation**

**Description**

This is a CSV parser which follows RFC4180

For simplicity's sake, the following things are not yet supported:
- CSV files with headings

The following however *is* supported
- A simple LF ("\n") instead of CRLF ("\r\n") to separate records.

#### CSVRecord

**Type Annotation**

#### parseStr

**Type Annotation**

```roc

    Parser CSVRecord a, 
    Str
    -> Result (List a) 
        [
            ParsingFailure Str,
            SyntaxError Str,
            ParsingIncomplete CSVRecord
        ]
```

**Description**

Attempts to Parser.parse an `a` from a `Str` that is encoded in CSV format.

#### parseCSV

**Type Annotation**

```roc

    Parser CSVRecord a, 
    CSV
    -> Result (List a) 
        [
            ParsingFailure Str,
            ParsingIncomplete CSVRecord
        ]
```

**Description**

Attempts to Parser.parse an `a` from a `CSV` datastructure (a list of lists of bytestring-fields).

#### record

**Type Annotation**

```roc
a -> Parser CSVRecord a
```

**Description**

Wrapper function to combine a set of fields into your desired `a`

```
record (\firstName -> \lastName -> \age -> User {firstName, lastName, age})
|> field string
|> field string
|> field u64
```

#### field

**Type Annotation**

```roc
Parser String.Utf8 a -> Parser CSVRecord a
```

**Description**

Turns a parser for a `List U8` into a parser that parses part of a `CSVRecord`.

#### string

**Type Annotation**

```roc
Parser CSVField Str
```

**Description**

Parser for a field containing a UTF8-encoded string

#### u64

**Type Annotation**

```roc
Parser CSVField U64
```

**Description**

Parse a number from a CSV field

#### f64

**Type Annotation**

```roc
Parser CSVField F64
```

**Description**

Parse a 64-bit float from a CSV field

#### parseStrToCSVRecord

**Type Annotation**

```roc

    Str
    -> Result CSVRecord 
        [
            ParsingFailure Str,
            ParsingIncomplete String.Utf8
        ]
```

**Description**

Attempts to Parser.parse a Str into the internal `CSVRecord` datastructure (A list of bytestring-fields).

#### file

**Type Annotation**

```roc
Parser String.Utf8 CSV
```

### HTTP

#### Request

**Type Annotation**

#### Response

**Type Annotation**

#### request

**Type Annotation**

```roc
Parser String.Utf8 Request
```

#### response

**Type Annotation**

```roc
Parser String.Utf8 Response
```

### Markdown

#### Markdown

**Type Annotation**

**Description**

Content values

#### all

**Type Annotation**

```roc
Parser String.Utf8 (List Markdown)
```

#### heading

**Type Annotation**

```roc
Parser String.Utf8 Markdown
```

**Description**

Headings

```
expect String.parseStr heading "# Foo Bar" == Ok (Heading One "Foo Bar")
expect String.parseStr heading "Foo Bar\n---" == Ok (Heading Two "Foo Bar")
```

#### link

**Type Annotation**

```roc
Parser String.Utf8 Markdown
```

**Description**

Links

```
expect String.parseStr link "[roc](https://roc-lang.org)" == Ok (Link "roc" "https://roc-lang.org")
```

#### image

**Type Annotation**

```roc
Parser String.Utf8 Markdown
```

**Description**

Images

```
expect String.parseStr image "![alt text](/images/logo.png)" == Ok (Image "alt text" "/images/logo.png")
```

#### code

**Type Annotation**

```roc
Parser String.Utf8 Markdown
```

**Description**

Parse code blocks using triple backticks
supports block extension e.g. ```roc

```
expect
    text =
        """
        ```roc
        # some code
        foo = bar
        ```
        """

    a = String.parseStr code text
    a == Ok (Code { ext: "roc", pre: "# some code\nfoo = bar\n" })
```

### Xml

#### Xml

**Type Annotation**

#### XmlDeclaration

**Type Annotation**

#### XmlVersion

**Type Annotation**

#### Node

**Type Annotation**

#### Attribute

**Type Annotation**

#### xmlParser

**Type Annotation**

```roc
Parser Utf8 Xml
```