OLD | NEW |
---|---|
(Empty) | |
1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 /// New Compiler API. This API is under construction, use only internally or | |
6 /// in unittests. | |
7 | |
8 library compiler_new; | |
9 | |
10 import 'dart:async'; | |
11 import 'src/apiimpl.dart'; | |
12 import 'compiler.dart' show Diagnostic, PackagesDiscoveryProvider; | |
13 export 'compiler.dart' show Diagnostic, PackagesDiscoveryProvider; | |
14 | |
15 // Unless explicitly allowed, passing `null` for any argument to the | |
16 // methods of library will result in an Error being thrown. | |
17 | |
18 /// Interface for providing the compiler with input. That is, Dart source files, | |
19 /// package config files, etc. | |
20 abstract class CompilerInput { | |
21 /// Returns a future that completes to the source corresponding to [uri]. | |
22 /// If an exception occurs, the future completes with this exception. | |
23 /// | |
24 /// The source can be represented either as a [:List<int>:] of UTF-8 bytes or | |
25 /// as a [String]. | |
26 /// | |
27 /// The following text is non-normative: | |
28 /// | |
29 /// It is recommended to return a UTF-8 encoded list of bytes because the | |
30 /// scanner is more efficient in this case. In either case, the data structure | |
31 /// is expected to hold a zero element at the last position. If this is not | |
32 /// the case, the entire data structure is copied before scanning. | |
33 Future/*<String | List<int>>*/ readFromUri(Uri uri); | |
34 } | |
35 | |
36 /// Interface for producing output from the compiler. That is, JavaScript target | |
37 /// files, source map files, dump info files, etc. | |
38 abstract class CompilerOutput { | |
39 /// Returns an [EventSink] that will serve as compiler output for the given | |
40 /// component. | |
41 /// | |
42 /// Components are identified by [name] and [extension]. By convention, | |
43 /// the empty string [:"":] will represent the main script | |
44 /// (corresponding to the script parameter of [compile]) even if the | |
45 /// main script is a library. For libraries that are compiled | |
46 /// separately, the library name is used. | |
47 /// | |
48 /// At least the following extensions can be expected: | |
49 /// | |
50 /// * "js" for JavaScript output. | |
51 /// * "js.map" for source maps. | |
52 /// * "dart" for Dart output. | |
53 /// * "dart.map" for source maps. | |
54 /// | |
55 /// As more features are added to the compiler, new names and | |
56 /// extensions may be introduced. | |
57 EventSink<String> createEventSink(String name, String extension); | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
EventSink seems like an implementation detail of h
Johnni Winther
2015/07/13 17:45:19
EventSink _is_ going away. My plan was to add a Ou
| |
58 } | |
59 | |
60 /// Interface for receiving diagnostic message from the compiler. That is, | |
61 /// errors, warnings, hints, etc. | |
62 abstract class CompilerDiagnostics { | |
63 /// Invoked by the compiler to report diagnostics. If [uri] is `null`, so are | |
64 /// [begin] and [end]. No other arguments may be `null`. If [uri] is not | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
given that `uri, begin, end` may be null, should w
Johnni Winther
2015/07/13 17:45:19
My plan is to use more structured objects instead
| |
65 /// `null`, neither are [begin] and [end]. [uri] indicates the compilation | |
66 /// unit from where the diagnostic originates. [begin] and [end] are | |
67 /// zero-based character offsets from the beginning of the compilation unit. | |
68 /// [message] is the diagnostic message, and [kind] indicates indicates what | |
69 /// kind of diagnostic it is. | |
70 void reportDiagnostic(Uri uri, int begin, int end, | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
Consider renaming to just `report`?
(given that t
Johnni Winther
2015/07/13 17:45:19
Good idea.
| |
71 String message, Diagnostic kind); | |
72 } | |
73 | |
74 /// Information resulting from the compilation. | |
75 class CompilationResult { | |
76 /// `true` if the compilation succeeded, that is, compilation didn't fail due | |
77 /// to compile-time errors and/or internal errors. | |
78 final bool isSuccess; | |
79 | |
80 /// The compiler object used for the compilation. | |
81 /// | |
82 /// Note: The type of [compiler] is implementation dependent and may vary. | |
83 /// Use only for debugging and testing. | |
84 final compiler; | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
I know this is currently used in tests, but beside
Johnni Winther
2015/07/13 17:45:19
Do you have any ideas for an alternative way of su
Siggi Cherem (dart-lang)
2015/07/13 18:08:06
Nothing concrete at this time. I have to look clos
| |
85 | |
86 CompilationResult(this.compiler, {this.isSuccess: true}); | |
87 } | |
88 | |
89 /// Object for passing options to the compiler. | |
90 class CompilerOptions { | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
Yay!!!!!
| |
91 final Uri entryPoint; | |
92 final Uri libraryRoot; | |
93 final Uri packageRoot; | |
94 final Uri packageConfig; | |
95 final PackagesDiscoveryProvider packagesDiscoveryProvider; | |
96 final List<String> options; | |
Siggi Cherem (dart-lang)
2015/07/13 17:28:37
Maybe add a TODO that this list of options should
Johnni Winther
2015/07/13 17:45:19
Not all options. We need a backdoor for experiment
| |
97 final Map<String, dynamic> environment; | |
98 | |
99 /// Creates an option object for the compiler. | |
100 // TODO(johnniwinther): Expand comment when [options] are explicit as named | |
101 // arguments. | |
102 factory CompilerOptions( | |
103 {Uri entryPoint, | |
104 Uri libraryRoot, | |
105 Uri packageRoot, | |
106 Uri packageConfig, | |
107 PackagesDiscoveryProvider packagesDiscoveryProvider, | |
108 List<String> options: const <String>[], | |
109 Map<String, dynamic> environment: const <String, dynamic>{}}) { | |
110 if (entryPoint == null) { | |
111 throw new ArgumentError("entryPoint must be non-null"); | |
112 } | |
113 if (!libraryRoot.path.endsWith("/")) { | |
114 throw new ArgumentError("libraryRoot must end with a /"); | |
115 } | |
116 if (packageRoot != null && !packageRoot.path.endsWith("/")) { | |
117 throw new ArgumentError("packageRoot must end with a /"); | |
118 } | |
119 return new CompilerOptions._( | |
120 entryPoint, | |
121 libraryRoot, | |
122 packageRoot, | |
123 packageConfig, | |
124 packagesDiscoveryProvider, | |
125 options, | |
126 environment); | |
127 } | |
128 | |
129 CompilerOptions._( | |
130 this.entryPoint, | |
131 this.libraryRoot, | |
132 this.packageRoot, | |
133 this.packageConfig, | |
134 this.packagesDiscoveryProvider, | |
135 this.options, | |
136 this.environment); | |
137 } | |
138 | |
139 /// Returns a future that completes to a [CompilationResult] when the Dart | |
140 /// sources in [options] have been compiled. | |
141 /// | |
142 /// The generated compiler output is obtained by providing a [compilerOutput]. | |
143 /// | |
144 /// If the compilation fails, the future's `CompilationResult.isSuccess` will | |
floitsch
2015/07/13 18:16:49
is `false` ... is invoked
Johnni Winther
2015/07/13 19:02:22
Done.
| |
145 /// be `false` and [CompilerDiagnostics.reportDiagnostic] on | |
146 /// [compilerDiagnostics] will have been invoked at least once with | |
147 /// `kind == Diagnostic.ERROR` or `kind == Diagnostic.CRASH`. | |
148 Future<CompilationResult> compile( | |
149 CompilerOptions compilerOptions, | |
150 CompilerInput compilerInput, | |
151 CompilerDiagnostics compilerDiagnostics, | |
152 CompilerOutput compilerOutput) { | |
153 | |
154 if (compilerOptions == null) { | |
155 throw new ArgumentError("compilerOptions must be non-null"); | |
156 } | |
157 if (compilerInput == null) { | |
158 throw new ArgumentError("compilerInput must be non-null"); | |
159 } | |
160 if (compilerDiagnostics == null) { | |
161 throw new ArgumentError("compilerDiagnostics must be non-null"); | |
162 } | |
163 if (compilerOutput == null) { | |
164 throw new ArgumentError("compilerOutput must be non-null"); | |
165 } | |
166 | |
167 Compiler compiler = new Compiler( | |
168 compilerInput, | |
169 compilerOutput, | |
170 compilerDiagnostics, | |
171 compilerOptions.libraryRoot, | |
172 compilerOptions.packageRoot, | |
173 compilerOptions.options, | |
174 compilerOptions.environment, | |
175 compilerOptions.packageConfig, | |
176 compilerOptions.packagesDiscoveryProvider); | |
177 return compiler.run(compilerOptions.entryPoint).then((bool success) { | |
178 return new CompilationResult(compiler, isSuccess: success); | |
179 }); | |
180 } | |
OLD | NEW |