Skip to content
← Back

src/syntax/process/synthesise_top_level_entry.ghul

1
namespace Syntax.Process is
2
use Source
3
use Logging
4
use Trees
5
6
// Synthesises a global entry point from a file's top-level statements.
7
//
8
// A file with no namespace may carry bare statements at file scope. The
9
// parser collects them, in source order, onto the root definition list;
10
// this rewriter wraps them into a global function named after the
11
// configured entry point, so every downstream phase sees an ordinary
12
// function. Runs before expand_namespaces, which then wraps the
13
// synthesised function into the file's root namespace alongside any other
14
// global definitions.
15
//
16
// Top-level statements and namespaces are mutually exclusive in a file:
17
// a file that carries both is a compile error and no entry is synthesised.
18
//
19
// The entry takes the two shapes the runtime can hand an entry point -
20
// `args: string[]` and `env: Ghul.Environment` - so the statements can
21
// read the command line and the process environment directly, and a
22
// Main-compatible `_entry` wrapper is synthesised beside it to carry
23
// both in. Under `--target wasm`, which starts a program with no
24
// arguments, each is declared only where the statements name it.
25
class SYNTHESISE_TOP_LEVEL_ENTRY(_entry_point: Compiler.ENTRY_POINT, _logger: Logger) is
26
apply(node: Node) is
27
if !isa Definitions.LIST(node) then
28
return
29
fi
30
31
let list = cast Definitions.LIST(node)
32
let statements = list.top_level_statements
33
34
if !statements? then
35
return
36
fi
37
38
list.top_level_statements = null
39
40
for definition in list do
41
if isa Definitions.NAMESPACE(definition) then
42
_logger.error(
43
statements.location,
44
"top-level statements cannot appear in a file with a namespace"
45
)
46
47
return
48
fi
49
od
50
51
for statement in statements do
52
if isa Statements.LET(statement) then
53
for variable in statement.variables do
54
variable.is_top_level = true
55
56
if _reject_entry_parameter_collision(variable) then
57
statement.poison()
58
variable.poison()
59
fi
60
od
61
fi
62
od
63
64
// Pushed to the front so compile-expressions walks the entry
65
// before any other function in the file: the top-level `let`
66
// variables it declares settle their inferred types during the
67
// entry's own walk, and every sibling function reads them
68
// after that.
69
list.push(_synthesise_entry(statements, _keeps_both_parameters(list)))
70
si
71
72
// Whether a file's root definition list carries a synthesised
73
// top-level entry. Consulted wherever that file needs treating
74
// differently: it compiles first, and it takes the full-rebuild
75
// path in analysis mode.
76
has_top_level_entry(definition: Node?) -> bool static is
77
if let list = cast Definitions.LIST?(definition) then
78
for d in list do
79
let unwrapped = d.without_pragmas
80
81
if let function = cast Definitions.FUNCTION?(unwrapped) then
82
if function.is_top_level_entry then
83
return true
84
fi
85
elif let `namespace = cast Definitions.NAMESPACE?(unwrapped) then
86
// Expand-namespaces wraps a namespace-less file's
87
// definitions - the synthesised entry among them -
88
// into a file-private namespace, so the entry sits
89
// one list down once that pass has run.
90
if has_top_level_entry(`namespace.body) then
91
return true
92
fi
93
fi
94
od
95
fi
96
97
return false
98
si
99
100
// The entry's implicit `args` and `env` formals are in scope across
101
// the whole entry body, so a top-level `let` of either name would
102
// shadow - and be shadowed by - them inside the statements. Name
103
// resolution from the body finds the formal first, so the let's
104
// inferred type lands on the formal and the global's type is never
105
// set; reporting the collision here turns that silent mis-compile
106
// into a diagnostic.
107
_reject_entry_parameter_collision(variable: Variables.VARIABLE) -> bool is
108
let name = variable.name
109
110
if name? /\ (name.name =~ "args" \/ name.name =~ "env") then
111
_logger.error(
112
name.location,
113
"a top-level '{name.name}' collides with the entry point's '{name.name}' parameter; use another name")
114
115
return true
116
fi
117
118
return false
119
si
120
121
// Whether the entry keeps both parameters whatever its statements
122
// read. It does on .NET, where a host such as a session calls it
123
// with both and a stack trace names it with both; for a cell, which
124
// the session's own entry calls with both whatever it reads; and beside a
125
// function the file declares under the entry's name, which outranks
126
// the statements and could otherwise collide with a narrower
127
// overload. Only a target that starts a program with no arguments
128
// takes the narrower entry.
129
_keeps_both_parameters(list: Definitions.LIST) -> bool is
130
if IoC.CONTAINER.instance.target_profile.entry_takes_arguments \/ IoC.CONTAINER.instance.build_flags.want_cells then
131
return true
132
fi
133
134
for d in list do
135
if let function = cast Definitions.FUNCTION?(d.without_pragmas) then
136
if function.name? /\ function.name.name =~ _entry_point.name then
137
return true
138
fi
139
fi
140
od
141
142
return false
143
si
144
145
// A submission's entry returns the value of its final expression
146
// to whatever ran it, so it is declared to return any value or
147
// none and the ordinary tail rule does the rest: a final
148
// expression of any type is assignable to it, and a final
149
// statement with no value leaves the entry returning nothing.
150
_return_type(location: LOCATION) -> TypeExpressions.TypeExpression =>
151
if IoC.CONTAINER.instance.build_flags.is_session_step then
152
TypeExpressions.OPTIONAL(
153
location,
154
TypeExpressions.NAMED(location, Identifiers.Identifier(location, "object")))
155
else
156
TypeExpressions.INFER(location)
157
fi
158
159
_synthesise_entry(statements: Statements.LIST, keep_both: bool) -> Definitions.FUNCTION is
160
let location = statements.location
161
162
let arguments = Collections.LIST[Variables.VARIABLE]()
163
164
// The two shapes the runtime can hand an entry point (GHUL.md,
165
// "functions"), so the statements can read the command line as
166
// `args` and the process environment as `env`. The wrapper
167
// synthesise-entry-environment-wrapper builds beside this
168
// function is what carries the environment in. Under
169
// `--target wasm` each is declared only where the statements name
170
// it, so an entry that reads neither takes no arguments.
171
//
172
// Like the entry's name below, the formals and their types
173
// carry an internal location: at the statement span they would
174
// record uses covering the whole region, and a hover or a
175
// completion anywhere in the statements would land on them.
176
let internal = LOCATION.internal
177
178
let body = Bodies.BLOCK(location, statements)
179
let scanner = NAME_REFERENCE_SCANNER()
180
181
if keep_both \/ scanner.body_references(body, "args") then
182
let args_type = TypeExpressions.ARRAY_(internal, TypeExpressions.NAMED(internal, Identifiers.Identifier(internal, "string")))
183
let args_param = Variables.VARIABLE(internal, Identifiers.Identifier(internal, "args"), args_type, false, true, null)
184
args_param.mark_argument()
185
arguments.add(args_param)
186
fi
187
188
if keep_both \/ scanner.body_references(body, "env") then
189
let env_type = TypeExpressions.NAMED(
190
internal,
191
Identifiers.QUALIFIED(
192
internal,
193
Identifiers.Identifier(internal, "Ghul"),
194
"Environment",
195
internal,
196
internal))
197
let env_param = Variables.VARIABLE(internal, Identifiers.Identifier(internal, "env"), env_type, false, true, null)
198
env_param.mark_argument()
199
arguments.add(env_param)
200
fi
201
202
let result = Definitions.FUNCTION(
203
location,
204
// The entry has no declaration the source names, so its
205
// identifier carries an internal location: a name at the
206
// statement span would record a hover use covering the whole
207
// region, and any hover on a non-symbol position there would
208
// report the synthesised entry.
209
Identifiers.Identifier(LOCATION.internal, _entry_point.name),
210
TypeExpressions.LIST(location, Collections.LIST[TypeExpressions.TypeExpression](0)),
211
Variables.LIST(location, arguments),
212
_return_type(LOCATION.internal),
213
Modifiers.LIST(location, null, null),
214
body
215
)
216
217
result.is_top_level_entry = true
218
219
return result
220
si
221
si
222
si