├── book.json ├── styles ├── print.css └── website.css ├── definitions.adoc ├── SUMMARY.adoc ├── .gitignore ├── README.adoc ├── syntax.adoc ├── modules.adoc ├── kinds.adoc ├── types.adoc └── lexical.adoc /book.json: -------------------------------------------------------------------------------- 1 | {} -------------------------------------------------------------------------------- /styles/print.css: -------------------------------------------------------------------------------- 1 | /* CSS for print */ 2 | -------------------------------------------------------------------------------- /styles/website.css: -------------------------------------------------------------------------------- 1 | /* CSS for website */ 2 | -------------------------------------------------------------------------------- /definitions.adoc: -------------------------------------------------------------------------------- 1 | = Definitions 2 | 3 | == Top Level Definitions 4 | 5 | <> -------------------------------------------------------------------------------- /SUMMARY.adoc: -------------------------------------------------------------------------------- 1 | = Summary 2 | 3 | . link:README.adoc[Introduction] 4 | . link:lexical.adoc[Lexical Syntax] 5 | . link:syntax.adoc[Expressions] 6 | . Pattern Matching 7 | . link:kinds.adoc[Kinds] 8 | . link:types.adoc[Types] 9 | . link:definitions.adoc[Definitions] 10 | . link:modules.adoc[Modules] 11 | 12 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Node rules: 2 | ## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 3 | .grunt 4 | 5 | ## Dependency directory 6 | ## Commenting this out is preferred by some people, see 7 | ## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git 8 | node_modules 9 | 10 | # Book build output 11 | _book 12 | 13 | # eBook build output 14 | *.epub 15 | *.mobi 16 | *.pdf -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | # Frege Quick Reference 2 | 3 | link:https://github.com/Frege/frege[Frege] is an implementation of Haskell 2010 for the Java Virtual Machine. 4 | 5 | link:http://haskell.org[Haskell] is a pure functional, statically typed programming language with non-strict evaluation. It is specified in detail in link:https://haskell.org/definition/haskell2010.pdf[The Haskell 2010 Report]. 6 | 7 | In the following quick reference, things are not explained thoroughly. Instead, the motto is facts, facts, facts. Often just examples are being given. 8 | 9 | -------------------------------------------------------------------------------- /syntax.adoc: -------------------------------------------------------------------------------- 1 | # Expressions 2 | 3 | :syntax-highlighting: 4 | 5 | Frege, being a functional language, has a rich variety of expressions to offer. Quite some expression forms are _syntactic sugar_ that allow to abbreviate more complex expressions. 6 | 7 | ## Terms 8 | 9 | [source,ebnf] 10 | ---- 11 | term ::= qvarid 12 | | literal 13 | 14 | variable ::= VARID 15 | qvarid ::= QUALIFIER? QUALIFIER? variable 16 | ---- 17 | 18 | A variable denotes the value it is bound to in the given context. Bindings can be established in *pattern matching* or *value binding definitions*. 19 | 20 | ### Literals 21 | 22 | See <> 23 | 24 | (to be continued) -------------------------------------------------------------------------------- /modules.adoc: -------------------------------------------------------------------------------- 1 | = Modules 2 | 3 | A _module_ is the compilation unit for Frege. It constitutes a name space for the enclosed definitions. Compiled modules can be imported from other modules to access the exported types, type classes and functions. 4 | 5 | NOTE: Currently, all items not declared `private` can be accessed from other modules. 6 | 7 | When module `foo.A` imports module `bar.B` we say that `foo.A` _depends on_ `bar.B` and on all modules that `bar.B` depends on. A module must not depend on itself. 8 | 9 | A _source file_ defines exactly one module. 10 | 11 | == Module Names 12 | 13 | A _module name_ consists of a number of identifiers separated with dots. The last or only component must start with an uppercase letter. 14 | 15 | Compilation of a module results in a Java class whose fully qualified name matches the module name. 16 | 17 | .Given 18 | module org.desperate.programmers.Foo where { ... } 19 | 20 | will result in the following Java code: 21 | 22 | package org.desperate.programmers; 23 | public class Foo { ... } 24 | 25 | It is customary to use lowercase identifiers for the package part, that is, only the last component of a Frege module name should start with an uppercase letter. 26 | 27 | NOTE: Because of the way the JVM works, it is only possible to reference classes in the unnamed package from classes that are also in the unnamed package. It is therefore not recommended to use simple module names for library modules. 28 | 29 | === Magic Module Names 30 | 31 | If the first component of a module name starts with an uppercase letter, that letter gets replaced with it's lowercase associate and the extra component `frege` is prepended to the module name. 32 | 33 | .Example 34 | import Data.List 35 | 36 | .Translation 37 | import frege.data.List 38 | 39 | === Prelude 40 | 41 | The module name `Prelude` is an abbreviation for `frege.Prelude`. 42 | 43 | == Module Definition 44 | 45 | [code,bnf] 46 | ---- 47 | module ::= DOCUMENTATION* moduleheader? '{' definitions+ '}' 48 | moduleheader ::= 'module' modulename 'where' 49 | ---- 50 | 51 | When the module header is missing, the compiler inserts 52 | 53 | [code,haskell] 54 | ---- 55 | module Main where 56 | ---- 57 | 58 | When the module header is missing and the first token that follows the optional documentation comments is not an opening brace, the lexical analyzer will assume <> mode starting at column one. 59 | 60 | == Integration with other JVM Languages 61 | 62 | It is sometimes desirable that compilation of a Frege module produces a class that extends another JVM class, or implements some interfaces. Usually, this requires also glue java code. 63 | 64 | To achieve this, there is the `native module` directive, that can occur as top level definition. There must be at most one such directive per module. 65 | 66 | .Syntax 67 | module-directive ::= 'native' 'module' 68 | ('type' typeApp)? 69 | ('interface' typeApp (',' typeApp)*)? 70 | 'where' '{' java code '}' 71 | 72 | The type after the *`type`* keyword must denote a native type. The compiler will create a class that claims to extends this type. (Hence this native type must actually be a Java class.) 73 | 74 | The types after the *`interface`* keyword must all denote native types. The compiler will create a class that claims to implement those interfaces. 75 | 76 | Necessary glue code can be written in curly braces after the *`where`* keyword. The curly braces should be given explicitly, to avoid insertion of semicolons. 77 | 78 | The _java code_ is parsed as a sequence of <> that are simply replicated in code generation. Because of this, avoid the Java `--` operator, as this would be interpreted as the start of a line comment. 79 | 80 | Observe that the types to extend or implement are given as <>! This means, appropriate native definitions must be in scope. 81 | -------------------------------------------------------------------------------- /kinds.adoc: -------------------------------------------------------------------------------- 1 | = Kinds 2 | 3 | :icons: font 4 | :syntax-highlighting: 5 | 6 | == What are Kinds? 7 | 8 | Kinds are the _types of types_ or better _type expressions_. We need them because not every type expression denotes a set of possible values. For example: 9 | 10 | ---- 11 | Maybe 12 | ---- 13 | 14 | No value actually can have type `Maybe`. Values can be of type `Maybe Int` or `Maybe [String]` and we can even speak of `Maybe a`. 15 | 16 | But if `Maybe` is not a type, what is it then? This is exactly what kinds tell us! 17 | We define: 18 | 19 | * Type expressions with kind `*` denote actual types, that is, sets of possible values. 20 | * If k~1~ and k~2~ are kinds, then so is k~1~ -> k~2~. 21 | A type expression with kind k~1~ -> k~2~ can be applied to another type expression of kind k~1~ and the resulting type expression has kind k~2~ 22 | * The arrow binds right associatively, so that k~1~ -> k~2~ -> k~3~ means k~1~ -> (k~2~ -> k~3~) 23 | * If `t` is a type expression and `k` is a kind, the construct `t :: k` means "type expression `t` has (or is of) kind `k` 24 | 25 | We can now derive the kind of type expression `Maybe`. Surely it holds that 26 | 27 | [code,haskell] 28 | ---- 29 | Int :: * 30 | Maybe Int :: * 31 | ---- 32 | 33 | since we can imagine values like 34 | 35 | [source,haskell] 36 | ---- 37 | 5 :: Int 38 | Just 7 :: Maybe Int 39 | ---- 40 | 41 | that inhabit those types. From this it follows that `Maybe` is something that can be applied to a type expression of kind `\*` and the resulting type expression also has kind `*`. Therefore: 42 | 43 | [source,haskell] 44 | ---- 45 | Maybe :: * -> * 46 | ---- 47 | 48 | NOTE: Note the spaces between the double colon, the stars and the arrow! Always include them when you write kinds, because input like `::*->*` would be interpreted as an <>. 49 | 50 | ## Kind Annotations 51 | 52 | The compiler tries to infer the kind of each type expression occurring in the program, so normally a programmer needs not be concerned with kinds. 53 | 54 | There may be cases where this doesn't work automatically and kind inference leads to error messages. The remedy is to write some *kind annotations*. 55 | 56 | Kind annotations are currently allowed on variables only. Here is an example: 57 | 58 | .Example with kind annotations 59 | [source,haskell] 60 | ---- 61 | data Foo (f :: * -> *) a b = X (f a) (f b) 62 | 63 | foo :: Foo Maybe Int Double 64 | foo = X (Just 1) Nothing 65 | 66 | 67 | bar :: Foo [] Int Double 68 | bar = X [] [5.23, 8e-7] 69 | ---- 70 | 71 | It is recommended to annotate type variables where they are introduced: 72 | 73 | 1. in the left hand side of a `type`, `data` or `newtype` definition 74 | 2. in the list of type variables following `forall` 75 | 3. in a type class definition after the class name 76 | 77 | NOTE: In future versions of the compiler, kind annotations will be forbidden except where stated above. 78 | 79 | ## Annotation of Java type variable bounds 80 | 81 | Frequently, _bounds_ are specified for type variables in Java generic types. 82 | 83 | .Example: 84 | [source,java] 85 | ---- 86 | class Enum> { ... } 87 | ---- 88 | 89 | It'll cause compiler errors when we define this in Frege as 90 | 91 | .Wrong: 92 | [source,haskell] 93 | ---- 94 | data Enum e = pure native java.lang.Enum{e} where { ... } 95 | ---- 96 | 97 | Instead, we need to annotate the type variable `e` with its correct bound: 98 | 99 | .Correct: 100 | [source,haskell] 101 | ---- 102 | data Enum (e ≤ Enum e) = pure native java.lang.Enum{e} where { ... } 103 | ---- 104 | 105 | When the Java type bound takes the form: 106 | 107 | [source,java] 108 | ---- 109 | extends ClassType & Interface1 & Interface2 & Interface3 110 | ---- 111 | 112 | we write this as tuple in Frege: 113 | 114 | [source,haskell] 115 | ---- 116 | (Classtype, Interface1, Interface2, Interface3) 117 | ---- 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | -------------------------------------------------------------------------------- /types.adoc: -------------------------------------------------------------------------------- 1 | = Types 2 | 3 | :icons: font 4 | 5 | == Syntax of Types 6 | 7 | [source,java] 8 | ---- 9 | /* type constructor */ 10 | tycon ::= QUALIFIER? CONID 11 | | '[' ']' /* list type constructor */ 12 | | '(' ')' /* unit type constructor */ 13 | | '(' ','+ ')' /* tuple type constructors */ 14 | | '(' '->' ')' /* function type constructor */ 15 | 16 | /* simple type variable */ 17 | simpleTyvar ::= VARID 18 | 19 | /* type variable with kind */ 20 | tyvar ::= simpleTyvar 21 | | '(' simpleTyvar '::' kind ')' 22 | | genericTypeVar 23 | 24 | /* bounded type variables, needed in native definitions */ 25 | genericTypeVar ::= 26 | '(' simpleTyvar '≤' typeApp ')' /* T extends C<...> */ 27 | 28 | /* wild card types, needed in native definitions */ 29 | wildCardType: 30 | '(' '≤' typeApp ')' /* ? extends C<...> */ 31 | | '(' '≥' typeApp ')' /* ? super C<...> */ 32 | 33 | /* type kind */ 34 | simplekind ::= '*' 35 | | '(' kind ')' 36 | 37 | kind ::= simplekind 38 | | simplekind '->' kind 39 | ---- 40 | 41 | For a discussion of kinds, <>. 42 | 43 | Type variables normally scope over a single type expression, where 44 | two type variables with the same name stand for the same type. 45 | 46 | In `data`, `newtype` or `type` definitions, type variables introduced left from the equals sign scope over the whole right hand side. 47 | 48 | In type `class` definitions, there is one type variable that stands 49 | for the instantiated type and scopes over all definitions in 50 | the where block of the class definition. 51 | 52 | In generic type variables, the given type denotes the _upper bound_ for some native type. It must be an instantiation of a native type or a tuple of such types. 53 | 54 | .Given 55 | data Enum (e ≤ Enum e) = pure native java.lang.Enum 56 | data Comparable t = pure native java.lang.Comparable 57 | 58 | the type variable 59 | 60 | t ≤ (Enum t, Comparable t) 61 | 62 | will be introduced in corresponding java constructs like 63 | 64 | T extends java.lang.Enum & java.lang.Comparable 65 | 66 | In wild card types, the given type denotes the _upper bound_ or the _lower bound_ of some native type. Here, no tuples are allowed since wild card types in Java can name a single type only. 67 | 68 | [source,java] 69 | ---- 70 | /* type term */ 71 | typeTerm ::= tyvar 72 | | tycon 73 | | wildCardType /* for native types */ 74 | | '(' quantifiedType ')' /* type in parentheses */ 75 | | '(' type (',' type)+ ')' /* tuple type */ 76 | | '[' type ']' /* list type */ 77 | 78 | /* type application */ 79 | typeApp ::= typeTerm+ 80 | 81 | /* type */ 82 | type ::= typeApp ( '->' type) /* function type */ 83 | constrainedType ::= constraints '=>' type 84 | constraint ::= QUALIFIER? CONID typeApp 85 | constraints ::= constraint | '(' constraint (',' constraint)* ')' 86 | quantifiedType ::= ('forall' | '∀') tyvar+ '.' (constrainedType | type) 87 | ---- 88 | 89 | .Examples 90 | String -- the String type 91 | Int -- the Int type 92 | M.Foo -- the type Foo from name space M 93 | t -- a type variable, stands for a type 94 | (t :: * -> *) -- a type variable with kind * -> * 95 | () -- the unit type 96 | [Int] -- list of integers 97 | [] Int -- the same 98 | (a,a,b) -- a 3 tuple where the first 2 elements have the same type 99 | (Int, [String]) -- a tuple, holding an Int and a list of Strings 100 | [(Int, [String])] -- a list of such tuples 101 | Int -> Int -- a function from Int to Int 102 | (a->b) -> [a] -> [b] -- a function that takes another function 103 | -- from a to b and a list of a and produces 104 | -- a list of b 105 | forall a b . (a->b) -> [a] -> [b] 106 | -- same as before, but explicitly quantified 107 | (∀ t.[t]->[t]) -> [a] -> [b] -> ([a], [b]) 108 | 109 | Types can mostly be written without explicit quantification. In this case we say the type is implicitly quantified. A `forall` with all free type variables is supplied by the compiler. 110 | 111 | However, for higher rank types we need an explicit `forall`. The last type in the examples above shows this. We have here a function that takes a higher order function that works on all lists, regardless of the element type. For example, `reverse` is such a function. This makes it possible for our higher rank function to apply the argument function to two lists of different types. 112 | 113 | 114 | == Standard Types 115 | 116 | |=== 117 | | Frege type | Java type | Explanation 118 | 119 | | Bool | boolean | 120 | | Int | int | 121 | | Long | long | 122 | | Integer | java.math.BigInteger | 123 | | Float | float | 124 | | Double | double | 125 | | Char | char | 126 | | String | java.lang.String | 127 | | Regex | java.util.regex.Pattern | 128 | | () | | the unit type with the element () 129 | | [a] | | lists 130 | | (a,b) | | tuples (up to 26 elements) 131 | | a -> b | | functions 132 | | Maybe a | | optional value 133 | | Either a b | | generic sum type 134 | 135 | |=== -------------------------------------------------------------------------------- /lexical.adoc: -------------------------------------------------------------------------------- 1 | # Lexical Matters 2 | 3 | :syntax-highlighting: 4 | 5 | ## Source code 6 | 7 | Source code is a sequence of Unicode code points. It is *strongly recommended* to keep source code in UTF-8 encoded text files. The compiler supports different encodings through the `-encoding` command line option, though. 8 | 9 | .Example 10 | ---- 11 | # use default encoding of the java platform (dangerous!) 12 | java -jar fregec.jar -encoding DEFAULT your.fr 13 | 14 | # use russian encoding (not tested, for lack of keyboard) 15 | java -jar fregec.jar -encoding KOI8_R your.fr 16 | 17 | # use UTF-8 (the only sensible decision) 18 | java -jar fregec.jar your.fr 19 | ---- 20 | 21 | NOTE: With default encoding, it is likely that your source code will not compile on different platforms if it contains any non-ASCII characters, because those characters are in some obscure proprietary encoding nobody else on the planet does understand. (Windows users, I'm looking at you!). 22 | 23 | NOTE: The eclipse plugin for Frege does support UTF-8 only. 24 | 25 | 26 | ## Tokens 27 | 28 | The lexical analyzer recognizes lexemes, or tokens, as described below. It turns a sequence of characters into a sequence of tokens. 29 | 30 | ### Whitespace 31 | 32 | Whitespace can appear in arbitrary quantity between two tokens. However, whitespace at the beginning of a line is syntactically relevant in <> mode. 33 | 34 | Two tokens must be separated by whitespace if the second token is a valid suffix of the first one. 35 | 36 | .Greedy Lexing 37 | 38 | v10 -- one token 39 | v 10 -- two tokens 40 | 41 | ### Comments 42 | 43 | Ordinary comments can appear everywhere whitespace can. 44 | 45 | .Line Comment 46 | -- extends to the end of the line 47 | 48 | .Block Comment 49 | {- extends {- to matching -} closing -} 50 | 51 | Block comments *do nest* and can extend over multiple lines. They can be used to separate tokens. 52 | 53 | .Two tokens separated by block comment 54 | v{-separates!-}10 55 | 56 | ### Documentation Text 57 | 58 | Looks like a comment at first sight, but is a syntactical element. 59 | 60 | .Documentation Text 61 | [source,haskell] 62 | ---- 63 | {-- 64 | First paragraph. 65 | 66 | Second paragraph. 67 | -} 68 | --- this is a single paragraph of documentation 69 | ---- 70 | 71 | Documentation text may appear 72 | 73 | * before the module header, multiple documentation texts may appear. 74 | * before a (non local) declaration of a function, variable, type class, data type, instance or type class. Syntactically, documentation text is treated here like a definition. This means 75 | ** in <> mode, documentation text must start with the same indentation as any other definition 76 | ** in explicit mode, documentation text and the next definition must be separated with semicolon. 77 | * immediately before a constructor is introduced, that is, before the constructor name. 78 | * immediately after the constructor declaration 79 | * after a field declaration, where it can stand in place of a comma. 80 | 81 | .Example 82 | [source,haskell] 83 | ---- 84 | --- This is a nice module. 85 | --- Have fun! 86 | module Nice where 87 | 88 | --- Complex numbers 89 | {-- 90 | This is merely a specialised tuple that holds two 91 | double numbers. 92 | 93 | An infix constructor ':+:' is available. 94 | -} 95 | data Complex = 96 | {-- The constructor is also named @Complex@, 97 | I simply had no better idea. Sorry. -} 98 | Complex { 99 | !re :: Double --- real part 100 | !im :: Double --- imaginary part 101 | } 102 | 103 | --- construct a 'Complex' number 104 | a :+: b = Complex a b 105 | ---- 106 | 107 | NOTE: Let bound definitions can not have documentation, as they are not accessible from outside the module. 108 | 109 | Multiple adjacent documentation texts are joined with a paragraph break inbetween. The documentation extracted from a sequence of documentationn texts is attached to the documented item. 110 | 111 | You write documentation with an easy <> language. 112 | 113 | You should write documentation texts because 114 | 115 | * a module documentation can be generated from your compiled module 116 | * the eclipse plugin can show the documentation of your functions on mouse hover and in code completion suggestions when your module is imported. 117 | * the Hoogle database for your module can make use of documentation text. 118 | 119 | ### Literals 120 | 121 | .Integer Literals 122 | 17 0x11 021 -- int value 17 in decimal, hexadecimal and octal 123 | 5_483_438 -- trailing groups of 3 digits can be separated 124 | 123L 217l -- long values (like in java) 125 | 5467n 7654N -- big integer literal 126 | 127 | .Floating Point Literals 128 | 1.34e-17 1.0d 0D -- double literals 129 | 0.2F 2.0f -- float literal 130 | 131 | Either one or more of the fractional part, the exponent or the suffix characters `D`, `F`, `d` or `f` may be omitted, but not all (this would result in an integer literal). 132 | 133 | .Boolean Literals 134 | true false -- like in Java 135 | True False -- like in Haskell 136 | 137 | #### Quoted constructs 138 | 139 | .Character Literals 140 | 'a' 141 | '\'' -- apostrophe 142 | '\\' -- backslash 143 | '\u2200' -- the character '∀' 144 | '\n' -- newline 145 | '\012' -- yet another newline 146 | 147 | All escape characters/sequences allowed in Java are also allowed in Frege. Character literals are 16-bit quantities, like in Java. This means that Unicode code points above 0xffff are not characters in Java and Frege. 148 | 149 | .String Literals 150 | "like in Java" 151 | "𝕲𝖔𝖙𝖙𝖑𝖔𝖇" 152 | 153 | Strings can contain any unicode characters. However, code points from the higher plane are encoded as a surrogate pairs. 154 | 155 | .Regular Expression Literals 156 | ´^foo\\´ -- "foo" at the start followed by backslash 157 | '(foo|bar)' -- upright quotes ok when more than 1 char 158 | '(?:)x' -- trick: same as ´x´ 159 | 160 | Regular expressions can be given as literals. They are checked for validity at compile time. No backslash duplications is needed, as is the case when one specifies them as string in Java. 161 | 162 | The first example above corresponds to the following Java code: 163 | 164 | [source,java] 165 | ---- 166 | final public static java.util.regex.Pattern p = 167 | java.util.regex.Pattern.compile("^foo\\\\"); 168 | ---- 169 | 170 | where `p` is some fresh name the compiler uses internally. 171 | 172 | A quoted construct in upright quotes is interpreted as regular expression literal when it can't possibly be a character. This is for the convenience of those that don't have acute accent marks on their keyboard. 173 | 174 | Withing regular expression literals, escape sequences follow the regular expression syntax. For example `\b` is a word break in regular expressions, but a backspace in strings. 175 | 176 | ### Separators 177 | 178 | The following characters are separators and have certain syntactic meanings 179 | 180 | { } [ ] ( ) , ; 181 | 182 | ### Keywords 183 | 184 | [source] 185 | ---- 186 | abstract case class data default derive deriving do 187 | else false forall foreign if import in 188 | infix infixl infixr 189 | instance interface let module native newtype of 190 | package private protected public 191 | then throws true type where 192 | 193 | = | \ 194 | -> .. :: <- => 195 | → … ∷ ← ⇒ ∀ 196 | ---- 197 | 198 | The last line lists some Unicode symbols that have the same meaning as the 2-character ascii symbols above them. The `∀` has the same meaning as `forall`. 199 | 200 | The following are keywords only when the next token is the keyword *`native`* 201 | 202 | pure mutable 203 | 204 | ### Operators 205 | 206 | Any sequence of characters that doesn't contain separators, quotes, apostrophes, acute/grave accent marks, letters, digits or whitespace is a lexical operator, unless it is a keyword. Operators are used to form infix expressions. 207 | 208 | When recognizing operators, the lexer considers the longest sequence of operator characters available. Symbolic keywords are not recognized when they appear as subsequence of an operator. 209 | 210 | ::* -- operator 211 | :: * -- double colon, operator 212 | 213 | 214 | This provides enormous symbolic freedom for user defined operators. 215 | 216 | In addition, a variable or data constructor can be turned into an operator by enclosing its name in acute accent marks: 217 | 218 | [source] 219 | ---- 220 | f `fmap` xs -- the fmap function used as operator 221 | ---- 222 | 223 | ### Variable Names 224 | 225 | Are used to name functions, variables, type variables and fields. 226 | 227 | _foo _Foo foo foo' f2o__o'' f'o'o' 228 | 229 | 230 | Variable names start with a lowercase letter or an underscore and may be followed by arbitrary many letters, digits, apostrophes and underscores. 231 | 232 | A sole underscore is a variable name reserved for use in pattern matching, where it indicates an unused value. 233 | 234 | For the purpose of Frege, all letters that are not uppercase letters are counted as lowercase. 235 | 236 | ### Constructor Names 237 | 238 | Are used to name namespaces, types, type classes and data constructors. Also, the last component of a module name must lexically be a constructor name. 239 | 240 | Such a name starts with an uppercase letter, which may be followed by an arbitrary number of letters, digits, apostrophes and underscores. 241 | 242 | Namespaces can have the same name as types or type classes. Data constructors can have the same name as namespaces, types or type classes. 243 | 244 | .A not so extreme example 245 | [source,haskell] 246 | ---- 247 | module Foo where 248 | 249 | data Foo = Foo 250 | ---- 251 | 252 | Editors for Frege should highlight or colour constructor names in such a way that they are easily distinguished. 253 | 254 | ### Qualifier 255 | 256 | A constructor name immediately followed by `.` 257 | This is used to form qualified names. 258 | 259 | ### Qualified Names 260 | 261 | A data constructor, variable or operator can be qualified by a namespace, a type name or by a namespace and a type name. 262 | Namespace and type name must be given as qualifiers, that is, they must be immediately followed by a dot. 263 | 264 | Foo . bar -- not a qualified name 265 | Foo.bar -- a qualified name 266 | Foo. bar -- the same 267 | Mod.Typ.### -- fully qualified operator 268 | 269 | ### Module names 270 | 271 | A sequence of names, separated by dots. 272 | The last part must be a construtor name. 273 | Since this will be the fully qualified name of the Java class that is generated for this module, it is expected that the name follows Java customs. See also <>. 274 | 275 | ### Native names 276 | 277 | A fully qualified name of some existing static method, class or interface. If this contains characters that are not allowed in Frege names (like `$`) or words that are keywords, it can be given as a string literal. 278 | 279 | [source,java] 280 | ---- 281 | java.lang.String.charAt 282 | "javafx.scene.control.TabPane$TabClosingPolicy" 283 | ---- 284 | 285 | [[layout]] 286 | ## Layout 287 | 288 | Like in Haskell, Frege code can be written using blocks delimitted by curly braces, where subsequent definitions are separated by semicolons. 289 | 290 | In fact, this is the language the parser understands. 291 | The so-called layout feature allows omission of those braces and semicolons, by inferring their positions based on the indentation of the program text and inserting them as needed before parsing. 292 | 293 | NOTE: Syntax diagrams will always show the explicit syntax with braces and semicolons. 294 | 295 | Informally stated, the braces and semicolons are inserted as follows. 296 | 297 | The layout (or ”offside”) rule takes effect whenever the open brace is omitted after the keyword `where`, `let`, `do`, or `of`. 298 | 299 | When this happens, the indentation of the next lexeme (whether or not on a new line) is remembered and the omitted open brace is inserted 300 | (the whitespace preceding the lexeme may include comments). If the next lexeme is not more indented than the current indentation level, an additional closing brace is inserted. 301 | 302 | For each subsequent line, 303 | if it contains only whitespace or is indented more, 304 | then the previous item is continued (nothing is inserted); 305 | if it is indented the same amount, 306 | then a new item begins (a semicolon is inserted); 307 | and if it is indented less, then the layout list ends (a close brace is inserted). 308 | 309 | The layout rule matches only those open braces that it has inserted; 310 | an explicit open brace must be matched by an explicit close brace. 311 | Within these explicit open braces, no layout processing is performed for constructs outside the braces, even if a line is indented to the left of an earlier implicit open brace. 312 | 313 | .Layout Examples 1 314 | [source, haskell] 315 | ---- 316 | module Foo where 317 | 318 | bar = 1 319 | baz = bar + x 320 | where 321 | x = y+2 322 | y = bar*5 323 | ---- 324 | 325 | becomes 326 | 327 | [source, haskell] 328 | ---- 329 | module Foo where 330 | 331 | {bar = 1 332 | ;baz = bar + x 333 | where 334 | {x = y+2 335 | ;y = bar*5 336 | } 337 | } 338 | ---- 339 | 340 | [[markup]] 341 | ## Documentation Text Markup 342 | 343 | The following markup is supported by the documentation tool and the eclipse plugin: 344 | 345 | *bold* _italic_ @monospaced@ 'reference' 346 | 347 | A *reference* is the (possibly qualified) name of a frege type, function, etc. 348 | This should turn to a hyperlink when processed. The *reference* will be resolved in the context of the module that contains the comment. What this means is that _reference_ must be a name that would be valid 349 | on the toplevel of the module. If the name resolution fails, the text enclosed in the apostrophes will be shown in red color. 350 | 351 | But sometimes one needs to reference some item from another module that is not imported. For this, the following syntax is possible: 352 | 353 | 'some.other.Package#something' 354 | 355 | The validity of such a reference can not be checked, of course. 356 | 357 | Finally, if one needs a generic link, it can be written like thus: 358 | 359 | 'http://projecteuler.net/index.php?section=problems&id=12 Euler probelm 12' 360 | 361 | The part before the first space character is taken as URL, the rest is the text that will be shown. 362 | 363 | An empty line serves as paragraph break. 364 | Special paragraphs are 365 | 366 | [source] 367 | ---- 368 | # Header 1 369 | ## Header 2 370 | ### Header 3 371 | > preformatted text (i.e. code examples) 372 | > each line must start with ">" 373 | 374 | - unordered list item 375 | 1. ordered list item 376 | (2) ordered list item 377 | [item] list item tagged with "item" 378 | ---- 379 | 380 | Paragraphs do not nest. 381 | 382 | --------------------------------------------------------------------------------