Bricks.Expression

Expressions

data Expression

Constructors

Expr'Var Str'Unquoted

A variable, such as x.

Expr'Str Str'Dynamic

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.

Expr'List List

A list is an ordered collection of expressions.

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)
]

Expr'Dict Dict

A dict is an unordered extensional mapping from strings.

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; }

Expr'Dot Dot

A dot expression (named after the . character it contains) looks up the value in a dict.

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 }

Expr'Lambda Lambda

A lambda expression x: y where x is the parameter.

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 ]

Expr'Apply Apply

Function application:

f x

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

f x y z

Expr'Let Let

A let-in expression:

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.

Expr'With With

A with expression is similar to a let-in expression, but the bindings come from a dict.

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

Instances

Show Expression

This instance is designed for doctests and REPL experimentation. The format is designed to strike a balance in verbosity between the derived Show implementations (which are unwieldily long) and the Bricks language itself (which is quite terse but unsuitable for demonstrating the parser, as outputting a Bricks rendering of parse result wouldn't illumunate anyone's understanding of the AST that the Show instances are here to depict).

Methods

showsPrec :: Int -> Expression -> ShowS

show :: Expression -> String

showList :: [Expression] -> ShowS

Binding Expression DictBinding

Methods

binding :: Expression -> Expression -> DictBinding

Strings

type Str'Static = Text

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

newtype Str'Dynamic

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.

Constructors

Str'Dynamic

Fields

• strDynamic'toSeq :: Seq Str'1

Instances

Show Str'Dynamic

Methods

showsPrec :: Int -> Str'Dynamic -> ShowS

show :: Str'Dynamic -> String

showList :: [Str'Dynamic] -> ShowS

Semigroup Str'Dynamic

Methods

(<>) :: Str'Dynamic -> Str'Dynamic -> Str'Dynamic

sconcat :: NonEmpty Str'Dynamic -> Str'Dynamic

stimes :: Integral b => b -> Str'Dynamic -> Str'Dynamic

Monoid Str'Dynamic

Methods

mempty :: Str'Dynamic

mappend :: Str'Dynamic -> Str'Dynamic -> Str'Dynamic

mconcat :: [Str'Dynamic] -> Str'Dynamic

data Str'1

One part of a Str'Dynamic.

Constructors

Str'1'Literal Str'Static

Str'1'Antiquote Expression

Instances

Show Str'1

Methods

showsPrec :: Int -> Str'1 -> ShowS

show :: Str'1 -> String

showList :: [Str'1] -> ShowS

strDynamic'toList :: Str'Dynamic -> [Str'1]

strDynamic'fromList :: [Str'1] -> Str'Dynamic

strDynamic'singleton :: Str'1 -> Str'Dynamic

String conversions

str'dynamicToStatic :: Str'Dynamic -> Maybe Str'Static

str'staticToDynamic :: Str'Static -> Str'Dynamic

str'unquotedToDynamic :: Str'Unquoted -> Str'Dynamic

Lists

newtype List

A list literal expression, starting with [ and ending with ]. See Expr'List.

Constructors

List (Seq Expression)

Instances

Show List

Methods

showsPrec :: Int -> List -> ShowS

show :: List -> String

showList :: [List] -> ShowS

Semigroup List

Methods

(<>) :: List -> List -> List

sconcat :: NonEmpty List -> List

stimes :: Integral b => b -> List -> List

Monoid List

Methods

mempty :: List

mappend :: List -> List -> List

mconcat :: [List] -> List

Dicts

data Dict

A dict literal expression, starting with { or rec { and ending with }. See Expr'Dict.

Constructors

Dict

Fields

• dict'rec :: Bool

  Whether the dict is recursive (denoted by the rec keyword)

• dict'bindings :: Seq DictBinding

  The bindings (everything between { and })

Instances

Show Dict

Methods

showsPrec :: Int -> Dict -> ShowS

show :: Dict -> String

showList :: [Dict] -> ShowS

data DictBinding

A binding of the form x = y; within a DictLiteral or LetExpr.

Constructors

DictBinding'Eq Expression Expression

DictBinding'Inherit Inherit

Instances

Show DictBinding

Methods

showsPrec :: Int -> DictBinding -> ShowS

show :: DictBinding -> String

showList :: [DictBinding] -> ShowS

IsInherit DictBinding

Methods

fromInherit :: Inherit -> DictBinding

Binding Expression DictBinding

Methods

binding :: Expression -> Expression -> DictBinding

Dict lookup

data Dot

An expression of the form person.name that looks up a key from a dict. See Expr'Dot.

Constructors

Dot

Fields

• dot'dict :: Expression
• dot'key :: Expression

Instances

Show Dot

Methods

showsPrec :: Int -> Dot -> ShowS

show :: Dot -> String

showList :: [Dot] -> ShowS

expression'applyDots

Arguments

:: Expression

Dict

-> [Expression]

Lookups

-> Expression

Dot expression

Lambdas

data Lambda

A function expression. See Expr'Lambda.

Constructors

Lambda

Fields

• lambda'head :: Param

  Declaration of the function's parameter

• lambda'body :: Expression

  Body of the function; what it evaluates to

Instances

Show Lambda

Methods

showsPrec :: Int -> Lambda -> ShowS

show :: Lambda -> String

showList :: [Lambda] -> ShowS

Function parameters

data Param

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.

Constructors

Param'Name Str'Unquoted

A simple single-parameter function

Param'DictPattern DictPattern

Dict destructuring, which gives you something resembling multiple named parameters with default values

Param'Both Str'Unquoted DictPattern

Both a param name and a dict pattern, separated by the @ keyword

Instances

Show Param

Methods

showsPrec :: Int -> Param -> ShowS

show :: Param -> String

showList :: [Param] -> ShowS

data DictPattern

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

Constructors

DictPattern

Fields

• dictPattern'items :: Seq DictPattern'1

  The list of keys to pull out of the dict, along with any default value each may have

• dictPattern'ellipsis :: Bool

  Whether to allow additional keys beyond what is listed in the items, corresponding to the ... keyword

Instances

Show DictPattern

Methods

showsPrec :: Int -> DictPattern -> ShowS

show :: DictPattern -> String

showList :: [DictPattern] -> ShowS

data DictPattern'1

One item within a DictPattern.

Constructors

DictPattern'1

Fields

• dictPattern'1'name :: Str'Unquoted

  The name of the key to pull out of the dict

• dictPattern'1'default :: Maybe Expression

  The default value to be used if the key is not present in the dict

Instances

Show DictPattern'1

Methods

showsPrec :: Int -> DictPattern'1 -> ShowS

show :: DictPattern'1 -> String

showList :: [DictPattern'1] -> ShowS

IsParam DictPattern'1

Methods

param :: Text -> DictPattern'1

Function application

data Apply

A function application expression. See Expr'Apply.

Constructors

Apply

Fields

• apply'func :: Expression

  The function being called

• apply'arg :: Expression

  The argument to the function

Instances

Show Apply

Methods

showsPrec :: Int -> Apply -> ShowS

show :: Apply -> String

showList :: [Apply] -> ShowS

expression'applyArgs

Arguments

:: Expression

Function

-> [Expression]

Args

-> Expression

Function application

let

data Let

A let-in expression. See Expr'Let.

Constructors

Let

Fields

• let'bindings :: Seq LetBinding

  The bindings (everything between the let and in keywords)

• let'value :: Expression

  The value (everything after the in keyword)

Instances

Show Let

Methods

showsPrec :: Int -> Let -> ShowS

show :: Let -> String

showList :: [Let] -> ShowS

data LetBinding

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

Constructors

LetBinding'Eq Str'Static Expression

A binding with an equals sign, of the form x = y;

LetBinding'Inherit Inherit

A binding using the inherit keyword, of the form inherit a b; or inherit (x) a b;

Instances

Show LetBinding

Methods

showsPrec :: Int -> LetBinding -> ShowS

show :: LetBinding -> String

showList :: [LetBinding] -> ShowS

IsInherit LetBinding

Methods

fromInherit :: Inherit -> LetBinding

Binding Text LetBinding

Methods

binding :: Text -> Expression -> LetBinding

with

data With

A with expression. See Expr'With.

Constructors

With

Fields

• with'context :: Expression
• with'value :: Expression

Instances

Show With

Methods

showsPrec :: Int -> With -> ShowS

show :: With -> String

showList :: [With] -> ShowS

inherit

data Inherit

Constructors

Inherit

Fields

• inherit'source :: Maybe Expression
• inherit'names :: Seq Str'Static

Instances

Show Inherit

Methods

showsPrec :: Int -> Inherit -> ShowS

show :: Inherit -> String

showList :: [Inherit] -> ShowS