-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | ... -- -- ... @package bricks-syntax @version 0.0.0.4 module Bricks.Keyword data Keyword -- | 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. keywords :: [Keyword] keyword'rec :: Keyword keyword'let :: Keyword keyword'in :: Keyword keyword'inherit :: Keyword keyword'inlineComment :: Keyword keywordString :: Keyword -> String keywordText :: Keyword -> Text -- | Source information is some form of description of where a Bricks -- expression or term came from. This information is used to tag -- Expressions and Terms so that our error messages can -- tell the user what parts of the Bricks source code are relevant to the -- problem. -- -- Overview of the types involved: -- -- module Bricks.Source -- | An endpoint of a SourceRange. data SourcePosition SourcePosition :: Natural -> Natural -> SourcePosition [sourcePosition'line] :: SourcePosition -> Natural [sourcePosition'column] :: SourcePosition -> Natural show'sourcePosition :: SourcePosition -> Text -- | Start and end points for a span of text. When we parse text into an -- Expression, we annotate it with source ranges so error -- messages that refer to specific expressions can tell the user where in -- their Bricks code those expressions are defined. data SourceRange SourceRange :: SourcePosition -> SourcePosition -> SourceRange [sourceRange'start] :: SourceRange -> SourcePosition [sourceRange'end] :: SourceRange -> SourcePosition show'sourceRange :: SourceRange -> Text sourceRange'join :: SourceRange -> SourceRange -> SourceRange sourceRangeMaybe'join :: Maybe SourceRange -> Maybe SourceRange -> Maybe SourceRange newtype SourceName a SourceName :: a -> SourceName a instance GHC.Classes.Ord Bricks.Source.SourcePosition instance GHC.Classes.Eq Bricks.Source.SourcePosition instance GHC.Show.Show Bricks.Source.SourceRange instance Data.Semigroup.Semigroup Bricks.Source.SourceRange instance GHC.Show.Show Bricks.Source.SourcePosition module Bricks.UnquotedString -- | 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

-- -- -- --

Deconstruction

-- -- -- --

See also

-- -- data UnquotedString -- |

Properties

-- -- unquotedString'try :: Text -> Maybe UnquotedString -- | Throws an exception if the string cannot render unquoted. unquotedString'orThrow :: Text -> UnquotedString unquotedString'text :: UnquotedString -> Text -- | 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: -- -- -- --

Properties

-- -- -- --

Examples

-- -- 
--   >>> text'canBeUnquoted "-ab_c"
--   True
--
-- -- 
--   >>> text'canBeUnquoted ""
--   False
--
-- -- 
--   >>> text'canBeUnquoted "a\"b"
--   False
--
-- -- 
--   >>> text'canBeUnquoted "let"
--   False
--
text'canBeUnquoted :: Text -> Bool -- | 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. char'canBeUnquoted :: Char -> Bool instance GHC.Show.Show Bricks.UnquotedString.UnquotedString module Bricks.Expression data Expression -- | A variable, such as x Expr'Var :: Var -> Expression -- | A string, quoted in the traditional form using a single double-quote -- (" ... ") Expr'Str :: Str'Dynamic -> Expression -- | A string in "indented string" form, using two single-quotes -- ('' ... '') Expr'Str'Indented :: InStr -> Expression -- | A list is an ordered collection of expressions. Expr'List :: List -> Expression -- | A dict is an unordered enumerated mapping from strings. Expr'Dict :: Dict -> Expression -- | A dot expression (named after the . character it contains) -- looks up the value at a particular key in a dict. Expr'Dot :: Dot -> Expression -- | A lambda expression x: y where x is the parameter. Expr'Lambda :: Lambda -> Expression -- | The application of a function to a single argument. Expr'Apply :: Apply -> Expression -- | A let-in expression consists of a list of variable -- bindings followed by an expression. Expr'Let :: Let -> Expression expression'source :: Expression -> Maybe SourceRange expression'discardSource :: Expression -> Expression -- | 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. --
  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)
    3. --
-- --

Syntax

-- -- Variables are always written without quotes. -- -- Unquoted strings are used for variables (Expr'Var) and places -- that bind variables (Lambda and Let). data Var Var :: UnquotedString -> Maybe SourceRange -> Var [var'str] :: Var -> UnquotedString [var'source] :: Var -> Maybe SourceRange var'text :: Var -> Text var'to'str'static :: Var -> Str'Static var'to'str'dynamic :: Var -> Str'Dynamic var'discardSource :: Var -> Var -- | A fixed string value. We use the description "static" to mean the -- string may not contain antiquotation, in contrast with -- Str'Dynamic which can. data Str'Static Str'Static :: Text -> Maybe SourceRange -> Str'Static [str'static'text] :: Str'Static -> Text [str'static'source] :: Str'Static -> Maybe SourceRange str'static'append :: Str'Static -> Str'Static -> Str'Static str'static'discardSource :: Str'Static -> Str'Static str'static'to'dynamic :: Str'Static -> 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: -- -- -- -- The indented string form does not interpret any escape sequences. data Str'Dynamic Str'Dynamic :: Seq Str'1 -> Maybe SourceRange -> Str'Dynamic [strDynamic'toSeq] :: Str'Dynamic -> Seq Str'1 [strDynamic'source] :: Str'Dynamic -> Maybe SourceRange -- | One part of a Str'Dynamic. data Str'1 Str'1'Literal :: Str'Static -> Str'1 Str'1'Antiquote :: Expression -> Str'1 str'1'discardSource :: Str'1 -> Str'1 str'dynamic'append :: Str'Dynamic -> 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'normalize :: Str'Dynamic -> Str'Dynamic str'dynamic'discardSource :: Str'Dynamic -> Str'Dynamic -- |

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
--
str'dynamic'to'static :: Str'Dynamic -> Maybe Str'Static -- | 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. data InStr InStr :: Seq InStr'1 -> Maybe SourceRange -> InStr [inStr'toSeq] :: InStr -> Seq InStr'1 [inStr'source] :: InStr -> Maybe SourceRange inStr'to'strDynamic :: InStr -> Str'Dynamic -- | Determine how many characters of whitespace to strip from an indented -- string. inStr'level :: InStr -> Natural -- | Determine the minimum indentation of any nonempty line, and remove -- that many space characters from the front of every line. inStr'dedent :: 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'trim :: InStr -> InStr inStr'toList :: InStr -> [InStr'1] inStr'discardSource :: InStr -> InStr -- | One line of an InStr. data InStr'1 InStr'1 :: Natural -> Maybe SourceRange -> Seq Str'1 -> Maybe Str'Static -> InStr'1 -- | The number of leading space characters. We store this separately for -- easier implementation of inStr'dedent. [inStr'1'level] :: InStr'1 -> Natural -- | The source position of the leading space characters [inStr'1'indentSource] :: InStr'1 -> Maybe SourceRange -- | The meat of the line, after any leading spaces and before the line -- break. [inStr'1'str] :: InStr'1 -> Seq Str'1 -- | The line break at the end, if any; all lines but the last one should -- have a line break [inStr'1'lineBreak] :: InStr'1 -> Maybe Str'Static inStr'1'toStrParts :: InStr'1 -> Seq Str'1 inStr'1'discardSource :: InStr'1 -> InStr'1 -- | 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)
--   ]
--
data List List :: Seq Expression -> Maybe SourceRange -> List [list'expressions] :: List -> Seq Expression [list'source] :: List -> Maybe SourceRange list'discardSource :: List -> List -- | 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; }
--
data Dict Dict :: Bool -> Seq DictBinding -> Maybe SourceRange -> Dict -- | Whether the dict is recursive (denoted by the rec keyword) [dict'rec] :: Dict -> Bool -- | The bindings (everything between { and }) [dict'bindings] :: Dict -> Seq DictBinding [dict'source] :: Dict -> Maybe SourceRange dict'discardSource :: Dict -> Dict -- | A binding within a Dict. data DictBinding -- | A binding of the form x = y; DictBinding'Eq :: Expression -> Expression -> DictBinding DictBinding'Inherit'Dict :: Expression -> (Seq Str'Static) -> DictBinding DictBinding'Inherit'Var :: (Seq Var) -> DictBinding dictBinding'discardSource :: DictBinding -> DictBinding -- | 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 }
--
data Dot Dot :: Expression -> Expression -> Maybe SourceRange -> Dot [dot'dict] :: Dot -> Expression [dot'key] :: Dot -> Expression [dot'source] :: Dot -> Maybe SourceRange expression'applyDots :: Expression -> [Expression] -> Expression dot'discardSource :: Dot -> Dot -- | 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 ]
--
data Lambda Lambda :: Param -> Expression -> Maybe SourceRange -> Lambda -- | Declaration of the function's parameter [lambda'head] :: Lambda -> Param -- | Body of the function; what it evaluates to [lambda'body] :: Lambda -> Expression [lambda'source] :: Lambda -> Maybe SourceRange lambda'discardSource :: Lambda -> Lambda -- | 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. data Param -- | A simple single-parameter function Param'Name :: Var -> Param -- | Dict destructuring, which gives you something resembling multiple -- named parameters with default values Param'DictPattern :: DictPattern -> Param -- | Both a param name and a dict pattern, separated by the -- @ keyword Param'Both :: Var -> DictPattern -> Param param'discardSource :: Param -> Param -- | A type of function parameter (Param) that does dict -- destructuring. data DictPattern DictPattern :: Seq DictPattern'1 -> Bool -> DictPattern -- | The list of keys to pull out of the dict, along with any default value -- each may have [dictPattern'items] :: DictPattern -> Seq DictPattern'1 -- | Whether to allow additional keys beyond what is listed in the items, -- corresponding to the ... keyword [dictPattern'ellipsis] :: DictPattern -> Bool dictPattern'discardSource :: DictPattern -> DictPattern -- | One item within a DictPattern. data DictPattern'1 DictPattern'1 :: Var -> Maybe Expression -> DictPattern'1 -- | The name of the key to pull out of the dict [dictPattern'1'name] :: DictPattern'1 -> Var -- | The default value to be used if the key is not present in the dict [dictPattern'1'default] :: DictPattern'1 -> Maybe Expression dictPattern'1'discardSource :: DictPattern'1 -> DictPattern'1 -- | 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
--
data Apply Apply :: Expression -> Expression -> Maybe SourceRange -> Apply -- | The function being called [apply'func] :: Apply -> Expression -- | The argument to the function [apply'arg] :: Apply -> Expression [apply'source] :: Apply -> Maybe SourceRange expression'applyArgs :: Expression -> [Expression] -> Expression apply'discardSource :: Apply -> Apply -- |

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. data Let Let :: Seq LetBinding -> Expression -> Maybe SourceRange -> Let -- | The bindings (everything between the let and in -- keywords) [let'bindings] :: Let -> Seq LetBinding -- | The value (everything after the in keyword) [let'value] :: Let -> Expression [let'source] :: Let -> Maybe SourceRange let'discardSource :: Let -> Let -- | A semicolon-terminated binding within the binding list of a Let -- expression. data LetBinding -- | A binding with an equals sign, of the form x = y; LetBinding'Eq :: Var -> Expression -> LetBinding -- | A binding using the inherit keyword, of the form inherit -- (x) a b; LetBinding'Inherit :: Expression -> (Seq Var) -> LetBinding letBinding'discardSource :: LetBinding -> LetBinding instance Data.Semigroup.Semigroup Bricks.Expression.Str'Dynamic instance GHC.Show.Show Bricks.Expression.Expression instance GHC.Show.Show Bricks.Expression.Str'Dynamic instance GHC.Show.Show Bricks.Expression.Str'1 instance GHC.Show.Show Bricks.Expression.InStr instance GHC.Show.Show Bricks.Expression.InStr'1 instance GHC.Show.Show Bricks.Expression.List instance GHC.Show.Show Bricks.Expression.Dict instance GHC.Show.Show Bricks.Expression.DictBinding instance GHC.Show.Show Bricks.Expression.Dot instance GHC.Show.Show Bricks.Expression.Lambda instance GHC.Show.Show Bricks.Expression.Param instance GHC.Show.Show Bricks.Expression.DictPattern instance GHC.Show.Show Bricks.Expression.DictPattern'1 instance GHC.Show.Show Bricks.Expression.Apply instance GHC.Show.Show Bricks.Expression.Let instance GHC.Show.Show Bricks.Expression.LetBinding instance Data.Semigroup.Semigroup Bricks.Expression.Str'Static instance GHC.Show.Show Bricks.Expression.Str'Static instance GHC.Show.Show Bricks.Expression.Var -- | Functions for constructing Expressions that match the -- Show implementations. -- -- This module is only designed for testing and REPL use. It isn't -- re-exported into the main Bricks API because it's a bit messy: -- -- module Bricks.Expression.Construction lambda :: Param'Builder -> Expression -> Expression apply :: Expression -> Expression -> Expression var :: Text -> Expression dot :: Expression -> Expression -> Expression list :: [Expression] -> Expression let'in :: [LetBinding] -> Expression -> Expression let'eq :: Text -> Expression -> LetBinding let'inherit'from :: Expression -> [Text] -> LetBinding dict :: [DictBinding] -> Expression rec'dict :: [DictBinding] -> Expression dict'eq :: Expression -> Expression -> DictBinding dict'inherit'from :: Expression -> [Text] -> DictBinding dict'inherit :: [Text] -> DictBinding str :: [Str'1'IsString] -> Expression antiquote :: Expression -> Str'1'IsString -- | A newtype for Str'1 just so we can give it the IsString -- instance which would be dubiously appropriate for the actual -- Str'1 type. newtype Str'1'IsString Str'1'IsString :: Str'1 -> Str'1'IsString [unStr'1'IsString] :: Str'1'IsString -> Str'1 str'indented :: [InStr'1] -> Expression indent :: Natural -> [Str'1'IsString] -> Maybe Text -> InStr'1 newtype Param'Builder Param'Builder :: (NonEmpty Param) -> Param'Builder param :: Text -> Param'Builder pattern :: [DictPattern'1] -> Param'Builder dict'param :: Text -> DictPattern'1 def :: Expression -> DictPattern'1 -> DictPattern'1 ellipsis :: Param'Builder data Expression -- | An associative operation. -- -- 
--   (a <> b) <> c = a <> (b <> c)
--
-- -- If a is also a Monoid we further require -- -- 
--   (<>) = mappend
--
(<>) :: Semigroup a => a -> a -> a infixr 6 <> -- | & is a reverse application operator. This provides -- notational convenience. Its precedence is one higher than that of the -- forward application operator $, which allows & to be -- nested in $. (&) :: () => a -> (a -> b) -> b infixl 1 & -- | The Maybe type encapsulates an optional value. A value of type -- Maybe a either contains a value of type a -- (represented as Just a), or it is empty (represented -- as Nothing). Using Maybe is a good way to deal with -- errors or exceptional cases without resorting to drastic measures such -- as error. -- -- The Maybe type is also a monad. It is a simple kind of error -- monad, where all errors are represented by Nothing. A richer -- error monad can be built using the Either type. data Maybe a :: * -> * Nothing :: Maybe a Just :: a -> Maybe a instance Data.Semigroup.Semigroup Bricks.Expression.Construction.Param'Builder instance Data.String.IsString Bricks.Expression.Construction.Str'1'IsString