Render an expression.

Examples

>>> :{
>>> render'expression renderContext'terse
>>> (lambda
>>> (param "a" <> pattern
>>> [ dict'param "f"
>>> , dict'param "b" & def (apply (var "g") (var "x"))
>>> ] <> ellipsis)
>>> (apply (var "f") (var "b")))
>>> :}
"a@{ f, b ? g x, ... }: f b"

Render an expression in a list context.

Render an expression in the context of the left-hand side of a Dot.

Render an expression in the context of the left-hand side of an Apply.

Render an expression in the context of the right-hand side of an Apply.

The primary, top-level expression parser. This is what you use to parse a .nix file.

Examples

>>> parseTest parse'expression ""
parse error at (line 1, column 1):
unexpected end of input
expecting expression

Parser for a parenthesized expression, from opening parenthesis to closing parenthesis.

Parser for an expression in a context that is expecting a dict key.

One of:

• an unquoted string
• a quoted dynamic string
• an arbitrary expression wrapped in antiquotes (${ ... })

Parser for a list of expressions in a list literal ([ x y z ]) or in a chain of function arguments (f x y z).

Examples

>>> parseTest parse'expressionList ""
[]

>>> parseTest (length <$> parse'expressionList) "x \"one two\" (a: b) (c d)"
4

>>> parseTest (length <$> parse'expressionList) "(x \"one two\" (a: b) (c d))"
1

Parser for a single item within an expression list (expressionListP). This expression is not a lambda, a function application, a let-in expression, or a with expression.

Examples

>>> parseTest parse'expressionList'1 "ab.xy"
{- 1:1-1:6 -} dot ({- 1:1-1:3 -} var "ab") ({- 1:4-1:6 -} str [{- 1:4-1:6 -} "xy"])

>>> :{
>>> parseTest (expression'discardSource <$> parse'expressionList'1)
>>> "(x: f x x) y z"
>>> :}
lambda (param "x") (apply (apply (var "f") (var "x")) (var "x"))

>>> :{
>>> parseTest (expression'discardSource <$> parse'expressionList'1)
>>> "{ a = b; }.a y"
>>> :}
dot (dict [dict'eq (str ["a"]) (var "b")]) (str ["a"])

Like parse'expressionList'1, but with the further restriction that the expression may not be a Dot.

Examples

>>> parseTest parse'expressionList'1'noDot "ab.xy"
{- 1:1-1:3 -} var "ab"

>>> :{
>>> parseTest (expression'discardSource <$> parse'expressionList'1'noDot)
>>> "(x: f x x) y z"
>>> :}
lambda (param "x") (apply (apply (var "f") (var "x")) (var "x"))

>>> :{
>>> parseTest (expression'discardSource <$> parse'expressionList'1'noDot)
>>> "{ a = b; }.a y"
>>> :}
dict [dict'eq (str ["a"]) (var "b")]

A variable x, as in the lambda calculus sense, is in one of two positions:

1. A binding, which may take a number of forms: - x: ... (Param'Name) - let x = ... ; in ... (LetBinding'Eq) - let inherit ( ... ) x; in ... (LetBinding'Inhherit)
2. A contextual reference to a lambda head or let binding in which x is bound: - The expression x by itself - An inherit binding in a dict expression (DictBinding'Inherit'Var)

Syntax

Variables are always written without quotes.

Unquoted strings are used for variables (Expr'Var) and places that bind variables (Lambda and Let).

Render an unquoted string in unquoted form.

Insert escape sequences for rendering normal double-quoted (") strings.

Parser for at least one normal character, within a normally-quoted string context, up to but not including the end of the string or the start of an antiquotation.

A fixed string value. We use the description "static" to mean the string may not contain antiquotation, in contrast with Str'Dynamic which can.

Render a static string, in unquoted form if possible.

Render a static string, in quoted form.

Parser for a static string which may be either quoted or unquoted.

Examples

>>> parseTest parse'strStatic "\"hello\""
{- 1:1-1:8 -} "hello"

>>> parseTest parse'strStatic "hello"
{- 1:1-1:6 -} "hello"

>>> parseTest parse'strStatic "\"a b\""
{- 1:1-1:6 -} "a b"

>>> parseTest parse'strStatic "a b"
{- 1:1-1:2 -} "a"

By "static," we mean that the string may not contain antiquotation:

>>> parseTest parse'strStatic "\"a${x}b\" xyz"
parse error at (line 1, column 5):
antiquotation is not allowed in this context

Parser for a static string that is quoted.

Parser for an unquoted static string.

A dynamic string is a quoted string expression, which may be a simple string like "hello" or a more complex string containing antiquotation like "Hello, my name is ${name}!". See Expr'Str.

We use the description "dynamic" to mean the string may contain antiquotation, in contrast with Str'Static which cannot.

This is the type of string expressions (Expr'Str).

String syntax

A string may be quoted either in the traditional form using a single double-quote (" ... "):

"one\ntwo"

or in the "indented string" form using two single-quotes ('' ... ''):

''
  one
  two
''

Both of these examples reduce to the same value, because leading whitespace is stripped from indented strings.

Either may contain "antiquotation" (also known as "string interpolation") to conveniently concatenate string-valued variables into the string.

"Hello, my name is ${name}!"

Normal strings may contain the following escape sequences:

• \\ → \
• \" → "
• \${ → ${
• \n → newline
• \r → carriage return
• \t → tab

The indented string form does not interpret any escape sequences.

One part of a Str'Dynamic.

Simplify a dynamic string by combining consecutive pieces of static text.

Examples

>>> :{
>>> str :: Text -> Str'1
>>> str x = Str'1'Literal $ Str'Static x Nothing
>>> 
>>> var :: Text -> Str'1
>>> var x = Str'1'Antiquote . Expr'Var $
>>> Var (unquotedString'orThrow x) Nothing
>>> :}

>>> :{
>>> str'dynamic'normalize $ Str'Dynamic (Seq.fromList
>>> [str "a", str "b", var "x", var "y", str "c", str "d"]) Nothing
>>> :}
str ["ab", antiquote (var "x"), antiquote (var "y"), "cd"]

Examples

>>> str'dynamic'to'static $ Str'Dynamic (Seq.fromList []) Nothing
Just ""

>>> a = Str'1'Literal (Str'Static "hi" Nothing)

>>> b = Str'1'Antiquote $ Expr'Var $ Var (unquotedString'orThrow "x") Nothing

>>> str'dynamic'to'static $ Str'Dynamic (Seq.fromList [ a ]) Nothing
Just "hi"

>>> str'dynamic'to'static $ Str'Dynamic (Seq.fromList [ a, b ]) Nothing
Nothing

Render a dynamic string, in unquoted form if possible.

Render a dynamic string, in quoted form.

Parser for a dynamic string enclosed in quotes (" ... ").

A string that can be rendered unquoted. Unquoted strings are restricted to a conservative set of characters; see text'canBeUnquoted for the full rules.

This type does not represent a particular part of Bricks syntax, but it is a wrapper for Text that enforces the limitations of strings at various places in the Bricks syntax.

Construction

• unquotedString'try
• unquotedString'orThrow

Deconstruction

• unquotedString'text

See also

• text'canBeUnquoted
• char'canBeUnquoted

Properties

• A text value may be used to construct an UnquotedString iff it satisfies text'canBeUnquoted.

  text'canBeUnquoted x = isJust (unquotedString'try x)

Throws an exception if the string cannot render unquoted.

Whether a string having this name can be rendered without quoting it.

Requirements for unquoted strings

We allow a string to render unquoted if all these conditions are met:

• The string is nonempty
• All characters satify char'canBeUnquoted
• The string is not a keyword

Properties

• A text value may be used to construct an UnquotedString iff it satisfies text'canBeUnquoted.

  text'canBeUnquoted x = isJust (unquotedString'try x)

Examples

>>> text'canBeUnquoted "-ab_c"
True

>>> text'canBeUnquoted ""
False

>>> text'canBeUnquoted "a\"b"
False

>>> text'canBeUnquoted "let"
False

Whether the character is allowed to be included in an UnquotedString. Such characters are letters, +, -, *, /, and _.

This is used in the implementation of text'canBeUnquoted.

Parser for an unquoted string. Unquoted strings are restricted to a conservative set of characters, and they may not be any of the keywords. See text'canBeUnquoted for a complete description of the unquoted string rules.

Examples

>>> parseTest parse'strUnquoted "abc"
("abc",1:1-1:4)

Here the parser consumes letters up to but not including {, because that character does not satisfy char'canBeUnquoted:

>>> parseTest parse'strUnquoted "ab{c"
("ab",1:1-1:3)

"let" does not parse as an unquoted string because let is a keyword:

>>> parseTest parse'strUnquoted "let"
parse error at (line 1, column 4):
unexpected end of input

This parser does not parse quoted strings:

>>> parseTest parse'strUnquoted "\"abc\""
parse error at (line 1, column 1):
unexpected "\""

An "indented string literal," delimited by two single-quotes ''.

This type of literal is called "indented" because the parser automatically removes leading whitespace from the string (inStr'dedent), which makes it convenient to use these literals for multi-line strings within an indented expression without the whitespace from indentation ending up as part of the string.

One line of an InStr.

Determine how many characters of whitespace to strip from an indented string.

Determine the minimum indentation of any nonempty line, and remove that many space characters from the front of every line.

Remove any empty lines from the beginning or end of an indented string, and remove the newline from the final nonempty line.

Parser for a dynamic string enclosed in "indented string" format, delimited by two single-quotes '' ... ''.

This form of string does not have any escape sequences. Therefore the only way to express '' or ${ within an indented string is to antiquote them.

Examples

>>> x = "''${\"''\"} and ${\"\\${\"}''"

>>> putStrLn x
''${"''"} and ${"\${"}''

>>> parseTest (inStr'discardSource <$> parse'inStr) x
str'indented [indent 0 [antiquote (str ["''"]), " and ", antiquote (str ["${"])] Nothing]

>>> parseTest parse'inStr x
{- 1:1-1:25 -} str'indented [indent {- 1:3-1:3 -} 0 [antiquote ({- 1:5-1:9 -} str [{- 1:6-1:8 -} "''"]), {- 1:10-1:15 -} " and ", antiquote ({- 1:17-1:22 -} str [{- 1:18-1:21 -} "${"])] Nothing]

Parser for a single line of an InStr.

A list is an ordered collection.

Syntax

A list expression (Expr'List) starts with [, ends with ], and contains any number of expressions in between.

The empty list:

[ ]

A list containing three variables:

[ a b c ]

Lambdas, function applications, let-in expressions, and with expressions must be parenthesized when in a list.

[
  (x: f x y)
  (g y)
  (let a = y; in f a a)
  (with d; f x a)
]

Render a list literal ([ ... ]).

Parser for a list expression ([ ... ]).

Examples

>>> parseTest parse'list "[]"
{- 1:1-1:3 -} list []

>>> :{
>>> parseTest (list'discardSource <$> parse'list)
>>> "[x \"one\" (a: b) (c d)]"
>>> :}
list [var "x", str ["one"], lambda (param "a") (var "b"), apply (var "c") (var "d")]

A dict is an unordered enumerated mapping from strings.

Syntax

A dict expression (Expr'Dict) starts with { or rec {, ends with }, and contains any number of DictBindings in between.

The empty dict (with no bindings):

{ }

A dict with two bindings:

{
  a = "one";
  b = "one two";
}

By default, dict bindings cannot refer to each other. For that, you need the rec keyword to create a recursive dict.

rec {
  a = "one";
  b = "${a} two";
}

In either case, the order of the bindings does not matter.

The left-hand side of a dict binding may be a quoted string (in the traditional " ... " style, not the indented-string '' style), which make it possible for them to be strings that otherwise couldn't be expressed unquoted, such as strings containing spaces:

{ "a b" = "c"; }

The left-hand side of a dict may even be an arbitrary expression, using the ${ ... } form:

let x = "a b"; in { ${x} = "c"; }

Dicts also support the inherit keyword:

{ inherit a; inherit (x) c d; }

The previous expression is equivalent to:

{ a = a; c = x.c; d = x.d; }

Render a dict literal ({ ... }).

Parser for a dict expression, either recursive (rec keyword) or not.

Examples

>>> parseTest parse'dict "{}"
{- 1:1-1:3 -} dict []

>>> parseTest parse'dict "rec { }"
{- 1:1-1:8 -} rec'dict []

>>> :{
>>> parseTest (dict'discardSource <$> parse'dict)
>>> "{ a = b; inherit (x) y z \"s t\"; }"
>>> :}
dict [dict'eq (str ["a"]) (var "b"), dict'inherit'from (var "x") ["y", "z", "s t"]]

Parser for a recursive (rec keyword) dict.

Examples

>>> parseTest parse'dict'rec "rec { }"
{- 1:1-1:8 -} rec'dict []

>>> :{
>>> parseTest (dict'discardSource <$> parse'dict'rec)
>>> "rec { a = \"1\"; b = \"${a}2\"; }"
>>> :}
rec'dict [dict'eq (str ["a"]) (str ["1"]), dict'eq (str ["b"]) (str [antiquote (var "a"), "2"])]

Parser for a non-recursive (no rec keyword) dict.

Examples

>>> parseTest parse'dict'noRec "{ }"
{- 1:1-1:4 -} dict []

>>> :{
>>> parseTest (dict'discardSource <$> parse'dict'noRec)
>>> "{ a = \"1\"; b = \"${a}2\"; }"
>>> :}
dict [dict'eq (str ["a"]) (str ["1"]), dict'eq (str ["b"]) (str [antiquote (var "a"), "2"])]

A binding within a Dict.

Render a binding within a Dict, including the trailing semicolon.

The dot function looks up a value (or a list of values) from a dict.

Syntax

A dot expression is named after the . character it contains. a.b looks up value at key b in the dict a.

The examples in this section all reduce to "Z".

{ a = "Z"; }.a

let x = { a = "Z"; }; in x.a

{ x = { a = "Z"; }; }.x.a

The right-hand side of a dot may be a quoted string (in the traditional " ... " style, not the indented-string '' style):

{ a = "Z"; }."a"

The right-hand side of a dot may even be an arbitrary expression, using the ${ ... } form:

{ a = "Z"; }.${ let b = "a"; in b }

Render a dot expression (a.b).

Parser for a chain of dict lookups (like .a.b.c) on the right-hand side of a Dot expression.

Examples

>>> parseTest parse'dot'rhs'chain ""
[]

>>> parseTest parse'dot'rhs'chain ".abc"
[{- 1:2-1:5 -} str [{- 1:2-1:5 -} "abc"]]

>>> :{
>>> parseTest (fmap expression'discardSource <$> parse'dot'rhs'chain)
>>> ".a.${b}.\"c\".\"d${e}\""
>>> :}
[str ["a"],var "b",str ["c"],str ["d", antiquote (var "e")]]

A function expressed as a lambda abstraction.

Syntax

A lambda expression (Expr'Lambda) has the form x: y where x is the function parameter to bind in the function body y.

This is a function that turns a name into a greeting:

name: "Hello, ${name}!"

The function parameter can also be a dict pattern, which looks like this:

{ a, b, c ? "another" }: "Hello, ${a}, ${b}, and ${c}!"

That function accepts a dict and looks up the keys a, b, and c from it, applying the default value "another" to c if it is not present in the dict. Dict patterns therefore give us something that resembles functions with named parameters and default arguments.

By default, a lambda defined with a dict pattern fails to evaluate if the dict argument contains keys that are not listed in the pattern. To prevent it from failing, you can end the pattern with ... :

({ a, ... }: x) { a = "1"; b = "2"; }

Every function has a single parameter. If you need multiple parameters, you have to curry:

a: b: [ a b ]

Render a lambda expression (x: y).

Parser for a lambda expression (x: y).

Examples

>>> test = parseTest (lambda'discardSource <$> parse'lambda)

>>> test "x: [x x \"a\"]"
lambda (param "x") (list [var "x", var "x", str ["a"]])

>>> test "{a,b}:a"
lambda (pattern [dict'param "a", dict'param "b"]) (var "a")

>>> test "{ ... }: \"x\""
lambda (pattern [] <> ellipsis) (str ["x"])

>>> test "a@{ f, b ? g x, ... }: f b"
lambda (param "a" <> pattern [dict'param "f", dict'param "b" & def (apply (var "g") (var "x"))] <> ellipsis) (apply (var "f") (var "b"))

>>> test "a: b: \"x\""
lambda (param "a") (lambda (param "b") (str ["x"]))

A parameter to a Lambda. All functions have a single parameter, but it's more complicated than that because it may also include dict destructuring.

Render a lambda parameter: everything from the beginning of a lambda, up to but not including the : that separates the head from the body of the lambda.

Parser for a function parameter (the beginning of a Lambda), including the colon. This forms part of parse'expression, so it backtracks in places where it has overlap with other types of expressions.

Parser for a parameter that starts with a variable. This could be a simple param that consists only of only the variable, or the variable may be followed by a dict pattern.

Parser for a param that has no variable, only a a dict pattern. This parser backtracks because the beginning of a dict pattern looks like the beginning of a dict expression.

A type of function parameter (Param) that does dict destructuring.

One item within a DictPattern.

Render a dict pattern ({ a, b ? c, ... }).

Render a single item in a DictPattern.

Parser for a dict pattern (the type of lambda parameter that does dict destructuring. This parser does not backtrack.

This is used in a lookahead by parse'param to determine whether we're about to start parsing a DictPattern.

The application of a function to a single argument.

Syntax

An function application expression (Expr'Apply) looks like this:

f x

If a function has multiple (curried) parameters, you can chain them together like so:

f x y z

Render a function application expression (f x).

Syntax

A let-in expression (Expr'Let) looks like this:

let
  greet = x: "Hello, ${x}!";
  name = "Chris";
in
  greet name

Let bindings, like dict bindings, may also use the inherit keyword.

let
  d = { greet = x: "Hello, ${x}!"; name = "Chris"; }
  inherit (d) greet name;
in
  greet name

The previous example also demonstrates how the bindings in a let expression may refer to each other (much like a dict with the rec keyword). As with dicts, the order of the bindings does not matter.

Render a let-in expression.

A semicolon-terminated binding within the binding list of a Let expression.

Render a binding within a Let, including the trailing semicolon.

All of the keywords. This list is used when parsing and rendering because an unquoted string cannot have a name that is exactly the same as a keyword.

Backtracking parser for a particular keyword.