You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Fixed strange whitespace (added whitespace after headers / put
paragraphs in a single line)
- Changed `long` to `modulealias`
- General wording improvements + fixed error in `opaque` type defn.
Copy file name to clipboardexpand all lines: docs/syntax.md
+36-37
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,12 @@
1
-
# LambdaBuffers file
1
+
# LambdaBuffers Frontend (.lbf) syntax
2
2
3
-
The input to LambdaBuffers is a text file which contains a module that defines
4
-
a specification of the types you want to generate.
5
-
This section gives the exact syntax of a LambdaBuffers file, and informally describes meaning of the syntactic constructs.
3
+
The input to the LambdaBuffers Frontend is a text file which contains a module that defines a specification of the types and type class instances you want to generate. This chapter gives the exact syntax of a LambdaBuffers Frontend file, and informally describes meaning of the syntactic constructs.
6
4
7
-
The name of a LambdaBuffers file must end with `.lbf`.
5
+
The name of a LambdaBuffers Frontend file must end with `.lbf`, and hence may also be referred to as a .lbf file or a .lbf schema.
8
6
9
7
## Notation
10
-
In the following description of a LambdaBuffers file's syntax, we use
11
-
a similar BNF syntax from [Section 10.1 of the Haskell Report](https://www.haskell.org/onlinereport/haskell2010/).
12
-
So, the following notational conventions are used for presenting syntax.
8
+
9
+
In the following description of a LambdaBuffers Frontend file's syntax, we use a similar BNF syntax from [Section 10.1 of the Haskell Report](https://www.haskell.org/onlinereport/haskell2010/). So, the following notational conventions are used for presenting syntax.
@@ -26,20 +23,20 @@ So, the following notational conventions are used for presenting syntax.
26
23
| `pat1|pat2` | choice |
27
24
-->
28
25
29
-
Note that the terminal syntax permits C-style escape sequences e.g.
30
-
`'\n'` denotes line feed (newline), and `'\r'` denotes carriage return.
26
+
Note that the terminal syntax permits C-style escape sequences e.g. `'\n'` denotes line feed (newline), and `'\r'` denotes carriage return.
31
27
32
-
Productions will be of the form
28
+
Productions will be of the form:
33
29
34
30
```text
35
31
nonterm -> alt1 | ... | altn
36
32
```
37
33
38
34
## Input file representation
39
-
The input file is Unicode text where the encoding is subject to the system locale.
40
-
We will often use the unqualified term *character* to refer to a Unicode code point in the input file.
35
+
36
+
The input file is Unicode text where the encoding is subject to the system locale. We will often use the unqualified term *character* to refer to a Unicode code point in the input file.
41
37
42
38
## Characters
39
+
43
40
The following terms are used to denote specific Unicode character categories:
44
41
45
42
-`upper` denotes a Unicode code point categorized as an uppercase letter or titlecase letter (i.e., with General Category value Lt or Lu).
@@ -54,56 +51,54 @@ Interested readers may find details of Unicode character categories in [Section
54
51
55
52
## Lexical syntax
56
53
57
-
Tokens form the vocabulary of LambdaBuffers files.
58
-
The classes of tokens are defined as follows.
54
+
Tokens form the vocabulary of LambdaBuffers Frontend files. The classes of tokens are defined as follows.
59
55
60
56
```text
61
57
keyword -> 'module' | 'sum' | 'prod' | 'record'
62
58
| 'opaque' | 'class' | 'instance' | 'import'
63
59
| 'qualified' | 'as'
64
60
modulename -> uppercamelcase
65
-
longmodulename -> long modulename
61
+
longmodulename -> modulealias modulename
66
62
typename -> uppercamelcase
67
63
fieldname -> lowercamelcase\keyword
68
-
longtypename -> long typename
64
+
longtypename -> modulealias typename
69
65
varname -> lowers\keyword
70
66
punctuation -> '<=' | ',' | '(' | ')' | '{' | '}'
71
67
| ':' | ':-' | '=' | '|'
72
68
classname -> uppercamelcase
73
-
longclassname -> long uppercamelcase
69
+
longclassname -> modulealias uppercamelcase
74
70
```
75
71
76
72
where
77
73
78
74
```text
79
75
uppercamelcase -> upper { alphanum }
80
76
lowercamelcase -> lower { alphanum }
81
-
long -> { uppercamelcase '.' }
77
+
modulealias -> { uppercamelcase '.' }
82
78
lowers -> lower { lower }
83
79
```
84
80
85
-
Input files are broken into *tokens* which use the *maximal munch* rule i.e.,
86
-
at each point, the next token is the longest sequence of characters that
87
-
form a valid token.
88
-
`space`s or line comments are ignored except as it separates tokens that
89
-
would otherwise combine into a single token.
81
+
Input files are broken into *tokens* which use the *maximal munch* rule i.e., at each point, the next token is the longest sequence of characters that form a valid token. `space`s or line comments are ignored except as it separates tokens that would otherwise combine into a single token.
90
82
91
83
### Line comments
84
+
92
85
A *line comment* starts with the terminal `'--'` followed by zero or more printable Unicode characters stopping at the first end of line (`'\n'` or `'\r\n'`).
93
86
94
-
## Syntax of LambdaBuffers files
95
-
A LambdaBuffers file defines a module that is a collection of data types, classes, instance clauses, and derive clauses.
87
+
## Syntax of LambdaBuffers Frontend files
96
88
97
-
The overall layout of a LambdaBuffers file is:
89
+
A LambdaBuffers Frontend file defines a module that is a collection of data types, classes, instance clauses, and derive clauses.
90
+
91
+
The overall layout of a LambdaBuffers Frontend file is:
The file must specify the module's `longmodulename` where its `modulename` must match the file's name not including the `.lbf` extension.
97
+
The file must specify the module's `longmodulename` where its `modulename` must match the LambdaBuffers Frontend file's file name not including the `.lbf` extension.
104
98
After, the file may contain a sequence of `import`s followed by a sequence of `statement`s.
105
99
106
100
### Import
101
+
107
102
Imports bring *entities* (types and classes) of other modules into scope.
108
103
109
104
```text
@@ -125,13 +120,15 @@ statement -> typedef
125
120
```
126
121
127
122
#### Type definitions
123
+
128
124
Types may be either sum types, product types, record types, or opaque types.
Class definitions do not instruct the code generator to generate code, but
189
-
instead provides a means to communicate with the code generator the
190
-
instances one would like to generate (via a derive clause).
189
+
Class definitions communicate with the code generator the implementations that already exist (via instance clauses) or that one would like to generate (via derive clauses).
191
190
192
191
#### Instance clause
192
+
193
193
An instance clause specifies a type is an instance of a class.
Instance clauses do not instruct the code generator to generate code, but
201
-
instead instructs the compiler (semantic checking) that the target language
202
-
provides instances for the given type provided that the given `constraintexps`
203
-
have instances.
200
+
Instance clauses do not instruct the code generator to generate code, but instead instructs the compiler (semantic checking) that the target language environment provides type class implementations for the given type (provided that the given `constraintexps` also have implementations).
204
201
205
202
#### Derive clause
203
+
206
204
Derive clauses instruct the code generator to generate code for a type so that it is an instance of a class.
0 commit comments