Bricks.Expression

Expressions

data Expression

Constructors

Expr'Var Var

A variable, such as x

Expr'Str Str'Dynamic

A string, quoted in the traditional form using a single double-quote (" ... ")

Expr'Str'Indented InStr

A string in "indented string" form, using two single-quotes ('' ... '')

Expr'List List

A list is an ordered collection of expressions.

Expr'Dict Dict

A dict is an unordered enumerated mapping from strings.

Expr'Dot Dot

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

Expr'Lambda Lambda

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

Expr'Apply Apply

The application of a function to a single argument.

Expr'Let Let

A let-in expression consists of a list of variable bindings followed by an expression.

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

expression'source :: Expression -> Maybe SourceRange

expression'discardSource :: Expression -> Expression

Variables

data Var

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

Constructors

Var

Fields

• var'str :: UnquotedString
• var'source :: Maybe SourceRange

Instances

Show Var

Methods

showsPrec :: Int -> Var -> ShowS

show :: Var -> String

showList :: [Var] -> ShowS

var'text :: Var -> Text

var'to'str'static :: Var -> Str'Static

var'to'str'dynamic :: Var -> Str'Dynamic

var'discardSource :: Var -> Var

Static strings

data Str'Static

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

Constructors

Str'Static

Fields

• str'static'text :: Text
• str'static'source :: Maybe SourceRange

Instances

Show Str'Static

Methods

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

show :: Str'Static -> String

showList :: [Str'Static] -> ShowS

Semigroup Str'Static

Methods

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

sconcat :: NonEmpty Str'Static -> Str'Static

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

str'static'append :: Str'Static -> Str'Static -> Str'Static

str'static'discardSource :: Str'Static -> Str'Static

str'static'to'dynamic :: Str'Static -> Str'Dynamic

Dynamic strings

data Str'Dynamic

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.

Constructors

Str'Dynamic

Fields

• strDynamic'toSeq :: Seq Str'1
• strDynamic'source :: Maybe SourceRange

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

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

str'1'discardSource :: Str'1 -> Str'1

str'dynamic'append :: Str'Dynamic -> Str'Dynamic -> Str'Dynamic

str'dynamic'normalize :: Str'Dynamic -> 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"]

str'dynamic'discardSource :: Str'Dynamic -> Str'Dynamic

str'dynamic'to'static :: Str'Dynamic -> Maybe Str'Static

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

Indented string

data InStr

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.

Constructors

InStr

Fields

• inStr'toSeq :: Seq InStr'1
• inStr'source :: Maybe SourceRange

Instances

Show InStr

Methods

showsPrec :: Int -> InStr -> ShowS

show :: InStr -> String

showList :: [InStr] -> ShowS

inStr'to'strDynamic :: InStr -> Str'Dynamic

inStr'level :: InStr -> Natural

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

inStr'dedent :: InStr -> InStr

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

inStr'trim :: InStr -> InStr

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

inStr'toList :: InStr -> [InStr'1]

inStr'discardSource :: InStr -> InStr

Single line of an indented string

data InStr'1

One line of an InStr.

Constructors

InStr'1

Fields

• inStr'1'level :: Natural

  The number of leading space characters. We store this separately for easier implementation of inStr'dedent.

• inStr'1'indentSource :: Maybe SourceRange

  The source position of the leading space characters

• inStr'1'str :: Seq Str'1

  The meat of the line, after any leading spaces and before the line break.

• inStr'1'lineBreak :: Maybe Str'Static

  The line break at the end, if any; all lines but the last one should have a line break

Instances

Show InStr'1

Methods

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

show :: InStr'1 -> String

showList :: [InStr'1] -> ShowS

inStr'1'toStrParts :: InStr'1 -> Seq Str'1

inStr'1'discardSource :: InStr'1 -> InStr'1

Lists

data List

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

Constructors

List

Fields

• list'expressions :: Seq Expression
• list'source :: Maybe SourceRange

Instances

Show List

Methods

showsPrec :: Int -> List -> ShowS

show :: List -> String

showList :: [List] -> ShowS

list'discardSource :: List -> List

Dicts

data Dict

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

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

• dict'source :: Maybe SourceRange

Instances

Show Dict

Methods

showsPrec :: Int -> Dict -> ShowS

show :: Dict -> String

showList :: [Dict] -> ShowS

dict'discardSource :: Dict -> Dict

data DictBinding

A binding within a Dict.

Constructors

DictBinding'Eq Expression Expression

A binding of the form x = y;

DictBinding'Inherit'Dict Expression (Seq Str'Static)

DictBinding'Inherit'Var (Seq Var)

Instances

Show DictBinding

Methods

showsPrec :: Int -> DictBinding -> ShowS

show :: DictBinding -> String

showList :: [DictBinding] -> ShowS

dictBinding'discardSource :: DictBinding -> DictBinding

Dict lookup

data Dot

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 }

Constructors

Dot

Fields

• dot'dict :: Expression
• dot'key :: Expression
• dot'source :: Maybe SourceRange

Instances

Show Dot

Methods

showsPrec :: Int -> Dot -> ShowS

show :: Dot -> String

showList :: [Dot] -> ShowS

expression'applyDots

Arguments

:: Expression

Dict

-> [Expression]

Lookups

-> Expression

Dot expression

dot'discardSource :: Dot -> Dot

Lambdas

data Lambda

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 ]

Constructors

Lambda

Fields

• lambda'head :: Param

  Declaration of the function's parameter

• lambda'body :: Expression

  Body of the function; what it evaluates to

• lambda'source :: Maybe SourceRange

Instances

Show Lambda

Methods

showsPrec :: Int -> Lambda -> ShowS

show :: Lambda -> String

showList :: [Lambda] -> ShowS

lambda'discardSource :: Lambda -> Lambda

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 Var

A simple single-parameter function

Param'DictPattern DictPattern

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

Param'Both Var 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

param'discardSource :: Param -> Param

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

dictPattern'discardSource :: DictPattern -> DictPattern

data DictPattern'1

One item within a DictPattern.

Constructors

DictPattern'1

Fields

• dictPattern'1'name :: Var

  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

dictPattern'1'discardSource :: DictPattern'1 -> DictPattern'1

Function application

data Apply

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

Constructors

Apply

Fields

• apply'func :: Expression

  The function being called

• apply'arg :: Expression

  The argument to the function

• apply'source :: Maybe SourceRange

Instances

Show Apply

Methods

showsPrec :: Int -> Apply -> ShowS

show :: Apply -> String

showList :: [Apply] -> ShowS

expression'applyArgs

Arguments

:: Expression

Function

-> [Expression]

Args

-> Expression

Function application

apply'discardSource :: Apply -> Apply

let

data Let

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.

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)

• let'source :: Maybe SourceRange

Instances

Show Let

Methods

showsPrec :: Int -> Let -> ShowS

show :: Let -> String

showList :: [Let] -> ShowS

let'discardSource :: Let -> Let

data LetBinding

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

Constructors

LetBinding'Eq Var Expression

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

LetBinding'Inherit Expression (Seq Var)

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

Instances

Show LetBinding

Methods

showsPrec :: Int -> LetBinding -> ShowS

show :: LetBinding -> String

showList :: [LetBinding] -> ShowS

letBinding'discardSource :: LetBinding -> LetBinding