/
api.html
3345 lines (2856 loc) · 142 KB
/
api.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head>
<meta charset="UTF-8">
<title>Analysis Server API Specification</title>
<style>body {
font-family: sans-serif, serif;
padding-left: 5%;
padding-right: 5%;
}
h1 {
text-align: center;
}
h2.domain {
border-bottom: 3px solid rgb(160, 160, 160);
}
pre {
margin: 0px;
}
div.box {
border: 1px solid rgb(0, 0, 0);
background-color: rgb(207, 226, 243);
padding: 0.5em;
}
div.hangingIndent {
padding-left: 3em;
text-indent: -3em;
}
dt {
margin-top: 1em;
margin-bottom: 1em;
}
dt.notification {
font-weight: bold;
}
dt.refactoring {
font-weight: bold;
}
dt.request {
font-weight: bold;
}
dt.typeDefinition {
font-weight: bold;
}
</style></head>
<body>
<h1>Analysis Server API Specification</h1>
<h1 style="color:#999999">WORKING DRAFT - Version 0.3</h1>
<p>
This document contains a specification of the API provided by
the analysis server. The API in this document is currently under
development and should be expected to change. In some cases
those changes will be substantial.
</p>
<h2>Overview</h2>
<p>
The analysis server API is a bi-directional client-server
API. The API is independent of the transport mechanism used, but
is heavily influenced by a model in which sockets or character
streams are used to transport JSON-RPC encoded information.
</p>
<h3>Transport Mechanism</h3>
<p>
The characters passed to the server are expected to be encoded
using UTF-8.
</p>
<p>
When character streams are used as the transport, messages are
delineated by newlines. This means, in particular, that the JSON
encoding process must not introduce newlines within a
message. Note however that newlines are used in this document
for readability.
</p>
<p>
To ease interoperability with Lisp-based clients (which may not
be able to easily distinguish between empty lists, empty maps,
and null), client-to-server communication is allowed to replace
any instance of “<tt>{}</tt>” or “<tt>[]</tt>” with null. The
server will always properly represent empty lists as
“<tt>[]</tt>” and empty maps as “<tt>{}</tt>”.
</p>
<h3>Communication Structure</h3>
<p>
Clients can make a request of the server and the server will
provide a response for each request that it receives. While many
of the requests that can be made by a client are informational
in nature, we have chosen to always return a response so that
clients can know whether the request was received and was
correct.
</p>
<p>
There is no guarantee concerning the order in which responses
will be returned, but there is a guarantee that the server will
process requests in the order in which they are sent as long as
the transport mechanism also makes this guarantee. Responses can
be returned in an order that is different from the order in
which the requests were received because some requests take
longer to process than others.
</p>
<p>
Every request is required to have two fields and may have an
optional third field. The first required field is the ‘id’
field, which is only used by the server to associate a response
with the request that generated the response. The second
required field is the ‘method’ field, which is used to determine
what the server is being requested to do. The optional field is
the ‘params’ field, whose structure is dependent on the method
being requested. The structure of this field is described with
each request for which it is required.
</p>
<p>
Every response has up to three fields. The first field is the
‘id’ field, which is always present and whose value is the
identifier that was passed to the request that generated the
response. The second field is the ‘error’ field, which is only
present if an error was encountered while processing the
request. The third field is the ‘result’ field, whose structure
is dependent on the method being responded to, and is described
with each request that will produce it.
</p>
<p>
The server can also communicate to the clients by sending a
notification. The purpose of these notifications is to provide
information to clients as it becomes available rather than to
require that clients poll for it. Unless explicitly stated, all
notifications are designed to return the complete information
available at the time the notification is sent; clients are not
required to update previously communicated
results. Consequently, the server can and should return partial
results before all results are available. For example, the
syntactic errors for a file can be returned as soon as the
syntactic analysis is complete, and both syntactic and semantic
errors can be returned together at a later time.
</p>
<p>
Each notification has two fields. The first field is the ‘event’
field, which identifies the kind of notification. The second
field is the ‘params’ field, whose structure is dependent on the
kind of notification being sent. The structure of this field is
described with each notification.
</p>
<h3>Eventual Consistency</h3>
<p>
TBD
</p>
<h3>Domains</h3>
<p>
For convenience, the API is divided into domains. Each domain is
specified in a separate section below:
</p>
<ul>
<li><a href="#domain_server">Server</a></li>
<li><a href="#domain_analysis">Analysis</a></li>
<li><a href="#domain_completion">Code Completion</a></li>
<li><a href="#domain_search">Search</a></li>
<li><a href="#domain_edit">Edit</a></li>
<li><a href="#domain_execution">Execution</a></li>
</ul>
<p>
The specifications of the API’s refer to data structures beyond
the standard JSON primitives. These data structures are
documented in the section titled <a href="#types">Types</a>.
</p>
<h3>Command-line Arguments</h3>
<p>
The command-line arguments that can be passed to the server.
</p>
<h4>Options</h4>
<blockquote>
<dl>
<dt>--no-error-notification</dt>
<dd>
Disable notifications about errors (see analysis.error). If this
flag is not specified then notifications will be sent for all
errors produced for all files in the actual analysis roots.
</dd>
</dl>
</blockquote>
<h2 class="domain"><a name="domain_server">Domain: server</a></h2>
<p>
The server domain contains API’s related to the execution of
the server.
</p>
<h3>Requests</h3><dl><dt class="request">server.getVersion</dt><dd><div class="box"><pre>request: {
"id": String
"method": "server.getVersion"
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
"result": {
"<b>version</b>": String
}
}</pre></div>
<p>Return the version number of the analysis server.</p>
<h4>Returns</h4><dl><dt class="field"><b><i>version ( String )</i></b></dt><dd>
<p>The version number of the analysis server.</p>
</dd></dl></dd><dt class="request">server.shutdown</dt><dd><div class="box"><pre>request: {
"id": String
"method": "server.shutdown"
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Cleanly shutdown the analysis server. Requests that are
received after this request will not be processed. Requests
that were received before this request, but for which a
response has not yet been sent, will not be responded to. No
further responses or notifications will be sent after the
response to this request has been sent.
</p>
</dd><dt class="request">server.setSubscriptions</dt><dd><div class="box"><pre>request: {
"id": String
"method": "server.setSubscriptions"
"params": {
"<b>subscriptions</b>": List<<a href="#type_ServerService">ServerService</a>>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Subscribe for services. All previous subscriptions are
replaced by the given set of services.
</p>
<p>
It is an error if any of the elements in the list are not
valid services. If there is an error, then the current
subscriptions will remain unchanged.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>subscriptions ( List<<a href="#type_ServerService">ServerService</a>> )</i></b></dt><dd>
<p>A list of the services being subscribed to.</p>
</dd></dl></dd></dl><h3>Notifications</h3><dl><dt class="notification">server.connected</dt><dd><div class="box"><pre>notification: {
"event": "server.connected"
}</pre></div>
<p>
Reports that the server is running. This notification is
issued once after the server has started running but before
any requests are processed to let the client know that it
started correctly.
</p>
<p>
It is not possible to subscribe to or unsubscribe from this
notification.
</p>
</dd><dt class="notification">server.error</dt><dd><div class="box"><pre>notification: {
"event": "server.error"
"params": {
"<b>isFatal</b>": bool
"<b>message</b>": String
"<b>stackTrace</b>": String
}
}</pre></div>
<p>
Reports that an unexpected error has occurred while
executing the server. This notification is not used for
problems with specific requests (which are returned as part
of the response) but is used for exceptions that occur while
performing other tasks, such as analysis or preparing
notifications.
</p>
<p>
It is not possible to subscribe to or unsubscribe from this
notification.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>isFatal ( bool )</i></b></dt><dd>
<p>
True if the error is a fatal error, meaning that the
server will shutdown automatically after sending this
notification.
</p>
</dd><dt class="field"><b><i>message ( String )</i></b></dt><dd>
<p>
The error message indicating what kind of error was
encountered.
</p>
</dd><dt class="field"><b><i>stackTrace ( String )</i></b></dt><dd>
<p>
The stack trace associated with the generation of the
error, used for debugging the server.
</p>
</dd></dl></dd><dt class="notification">server.status</dt><dd><div class="box"><pre>notification: {
"event": "server.status"
"params": {
"<b>analysis</b>": <span style="color:#999999">optional</span> <a href="#type_AnalysisStatus">AnalysisStatus</a>
}
}</pre></div>
<p>
Reports the current status of the server. Parameters are
omitted if there has been no change in the status
represented by that parameter.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"STATUS"</tt> in
the list of services passed in a server.setSubscriptions
request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>analysis ( <span style="color:#999999">optional</span> <a href="#type_AnalysisStatus">AnalysisStatus</a> )</i></b></dt><dd>
<p>
The current status of analysis, including whether
analysis is being performed and if so what is being
analyzed.
</p>
</dd></dl></dd></dl>
<h2 class="domain"><a name="domain_analysis">Domain: analysis</a></h2>
<p>
The analysis domain contains API’s related to the analysis of
files.
</p>
<h3>Requests</h3><dl><dt class="request">analysis.getErrors</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.getErrors"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
"result": {
"<b>errors</b>": List<<a href="#type_AnalysisError">AnalysisError</a>>
}
}</pre></div>
<p>
Return the errors associated with the given file. If the
errors for the given file have not yet been computed, or the
most recently computed errors for the given file are out of
date, then the response for this request will be delayed
until they have been computed. If some or all of the errors
for the file cannot be computed, then the subset of the
errors that can be computed will be returned and the
response will contain an error to indicate why the errors
could not be computed.
</p>
<p>
This request is intended to be used by clients that cannot
asynchronously apply updated error information. Clients that
<b>can</b> apply error information as it becomes available
should use the information provided by the 'analysis.errors'
notification.
</p>
<p>
If a request is made for a file which does not exist, or
which is not currently subject to analysis (e.g. because it
is not associated with any analysis root specified to
analysis.setAnalysisRoots), an error of type
<tt>GET_ERRORS_INVALID_FILE</tt> will be generated.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file for which errors are being requested.
</p>
</dd></dl><h4>Returns</h4><dl><dt class="field"><b><i>errors ( List<<a href="#type_AnalysisError">AnalysisError</a>> )</i></b></dt><dd>
<p>
The errors associated with the file.
</p>
</dd></dl></dd><dt class="request">analysis.getHover</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.getHover"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>offset</b>": int
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
"result": {
"<b>hovers</b>": List<<a href="#type_HoverInformation">HoverInformation</a>>
}
}</pre></div>
<p>
Return the hover information associate with the given
location. If some or all of the hover information is not
available at the time this request is processed the
information will be omitted from the response.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file in which hover information is being
requested.
</p>
</dd><dt class="field"><b><i>offset ( int )</i></b></dt><dd>
<p>
The offset for which hover information is being
requested.
</p>
</dd></dl><h4>Returns</h4><dl><dt class="field"><b><i>hovers ( List<<a href="#type_HoverInformation">HoverInformation</a>> )</i></b></dt><dd>
<p>
The hover information associated with the
location. The list will be empty if no information
could be determined for the location. The list can
contain multiple items if the file is being analyzed
in multiple contexts in conflicting ways (such as a
part that is included in multiple libraries).
</p>
</dd></dl></dd><dt class="request">analysis.reanalyze</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.reanalyze"
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Force the re-analysis of everything contained in the
existing analysis roots. This will cause all previously
computed analysis results to be discarded and recomputed,
and will cause all subscribed notifications to be re-sent.
</p>
</dd><dt class="request">analysis.setAnalysisRoots</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.setAnalysisRoots"
"params": {
"<b>included</b>": List<<a href="#type_FilePath">FilePath</a>>
"<b>excluded</b>": List<<a href="#type_FilePath">FilePath</a>>
"<b>packageRoots</b>": <span style="color:#999999">optional</span> Map<<a href="#type_FilePath">FilePath</a>, <a href="#type_FilePath">FilePath</a>>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Sets the root paths used to determine which files to
analyze. The set of files to be analyzed are all of the
files in one of the root paths that are not also in one of
the excluded paths.
</p>
<p>
Note that this request determines the set of requested
analysis roots. The actual set of analysis roots at any
given time is the intersection of this set with the set of
files and directories actually present on the
filesystem. When the filesystem changes, the actual set of
analysis roots is automatically updated, but the set of
requested analysis roots is unchanged. This means that if
the client sets an analysis root before the root becomes
visible to server in the filesystem, there is no error; once
the server sees the root in the filesystem it will start
analyzing it. Similarly, server will stop analyzing files
that are removed from the file system but they will remain
in the set of requested roots.
</p>
<p>
If an included path represents a file, then server will look
in the directory containing the file for a pubspec.yaml
file. If none is found, then the parents of the directory
will be searched until such a file is found or the root of
the file system is reached. If such a file is found, it will
be used to resolve package: URI’s within the file.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>included ( List<<a href="#type_FilePath">FilePath</a>> )</i></b></dt><dd>
<p>
A list of the files and directories that should be
analyzed.
</p>
</dd><dt class="field"><b><i>excluded ( List<<a href="#type_FilePath">FilePath</a>> )</i></b></dt><dd>
<p>
A list of the files and directories within the
included directories that should not be analyzed.
</p>
</dd><dt class="field"><b><i>packageRoots ( <span style="color:#999999">optional</span> Map<<a href="#type_FilePath">FilePath</a>, <a href="#type_FilePath">FilePath</a>> )</i></b></dt><dd>
<p>
A mapping from source directories to target directories
that should override the normal package: URI resolution
mechanism. The analyzer will behave as though each
source directory in the map contains a special
pubspec.yaml file which resolves any package: URI to the
corresponding path within the target directory. The
effect is the same as specifying the target directory as
a "--package_root" parameter to the Dart VM when
executing any Dart file inside the source directory.
</p>
<p>
Files in any directories that are not overridden by this
mapping have their package: URI's resolved using the
normal pubspec.yaml mechanism. If this field is absent,
or the empty map is specified, that indicates that the
normal pubspec.yaml mechanism should always be used.
</p>
</dd></dl></dd><dt class="request">analysis.setPriorityFiles</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.setPriorityFiles"
"params": {
"<b>files</b>": List<<a href="#type_FilePath">FilePath</a>>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Set the priority files to the files in the given list. A
priority file is a file that is given priority when
scheduling which analysis work to do first. The list
typically contains those files that are visible to the user
and those for which analysis results will have the biggest
impact on the user experience. The order of the files within
the list is significant: the first file will be given higher
priority than the second, the second higher priority than
the third, and so on.
</p>
<p>
Note that this request determines the set of requested
priority files. The actual set of priority files is the
intersection of the requested set of priority files with the
set of files currently subject to analysis. (See
analysis.setSubscriptions for a description of files that
are subject to analysis.)
</p>
<p>
If a requested priority file is a directory it is ignored,
but remains in the set of requested priority files so that
if it later becomes a file it can be included in the set of
actual priority files.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>files ( List<<a href="#type_FilePath">FilePath</a>> )</i></b></dt><dd>
<p>
The files that are to be a priority for analysis.
</p>
</dd></dl></dd><dt class="request">analysis.setSubscriptions</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.setSubscriptions"
"params": {
"<b>subscriptions</b>": Map<<a href="#type_AnalysisService">AnalysisService</a>, List<<a href="#type_FilePath">FilePath</a>>>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Subscribe for services. All previous subscriptions are
replaced by the current set of subscriptions. If a given
service is not included as a key in the map then no files
will be subscribed to the service, exactly as if the service
had been included in the map with an explicit empty list of
files.
</p>
<p>
Note that this request determines the set of requested
subscriptions. The actual set of subscriptions at any given
time is the intersection of this set with the set of files
currently subject to analysis. The files currently subject
to analysis are the set of files contained within an actual
analysis root but not excluded, plus all of the files
transitively reachable from those files via import, export
and part directives. (See analysis.setAnalysisRoots for an
explanation of how the actual analysis roots are
determined.) When the actual analysis roots change, the
actual set of subscriptions is automatically updated, but
the set of requested subscriptions is unchanged.
</p>
<p>
If a requested subscription is a directory it is ignored,
but remains in the set of requested subscriptions so that if
it later becomes a file it can be included in the set of
actual subscriptions.
</p>
<p>
It is an error if any of the keys in the map are not valid
services. If there is an error, then the existing
subscriptions will remain unchanged.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>subscriptions ( Map<<a href="#type_AnalysisService">AnalysisService</a>, List<<a href="#type_FilePath">FilePath</a>>> )</i></b></dt><dd>
<p>
A table mapping services to a list of the files being
subscribed to the service.
</p>
</dd></dl></dd><dt class="request">analysis.updateContent</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.updateContent"
"params": {
"<b>files</b>": Map<<a href="#type_FilePath">FilePath</a>, <a href="#type_AddContentOverlay">AddContentOverlay</a> | <a href="#type_ChangeContentOverlay">ChangeContentOverlay</a> | <a href="#type_RemoveContentOverlay">RemoveContentOverlay</a>>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Update the content of one or more files. Files that were
previously updated but not included in this update remain
unchanged. This effectively represents an overlay of the
filesystem. The files whose content is overridden are
therefore seen by server as being files with the given
content, even if the files do not exist on the filesystem or
if the file path represents the path to a directory on the
filesystem.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>files ( Map<<a href="#type_FilePath">FilePath</a>, <a href="#type_AddContentOverlay">AddContentOverlay</a> | <a href="#type_ChangeContentOverlay">ChangeContentOverlay</a> | <a href="#type_RemoveContentOverlay">RemoveContentOverlay</a>> )</i></b></dt><dd>
<p>
A table mapping the files whose content has changed to a
description of the content change.
</p>
</dd></dl></dd><dt class="request">analysis.updateOptions</dt><dd><div class="box"><pre>request: {
"id": String
"method": "analysis.updateOptions"
"params": {
"<b>options</b>": <a href="#type_AnalysisOptions">AnalysisOptions</a>
}
}</pre><br><pre>response: {
"id": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
}</pre></div>
<p>
Update the options controlling analysis based on the given
set of options. Any options that are not included in the
analysis options will not be changed. If there are options
in the analysis options that are not valid, they will be
silently ignored.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>options ( <a href="#type_AnalysisOptions">AnalysisOptions</a> )</i></b></dt><dd>
<p>
The options that are to be used to control analysis.
</p>
</dd></dl></dd></dl><h3>Notifications</h3><dl><dt class="notification">analysis.errors</dt><dd><div class="box"><pre>notification: {
"event": "analysis.errors"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>errors</b>": List<<a href="#type_AnalysisError">AnalysisError</a>>
}
}</pre></div>
<p>
Reports the errors associated with a given file. The set of
errors included in the notification is always a complete
list that supersedes any previously reported errors.
</p>
<p>
It is only possible to unsubscribe from this notification by
using the command-line flag --no-error-notification.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file containing the errors.
</p>
</dd><dt class="field"><b><i>errors ( List<<a href="#type_AnalysisError">AnalysisError</a>> )</i></b></dt><dd>
<p>
The errors contained in the file.
</p>
</dd></dl></dd><dt class="notification">analysis.flushResults</dt><dd><div class="box"><pre>notification: {
"event": "analysis.flushResults"
"params": {
"<b>files</b>": List<<a href="#type_FilePath">FilePath</a>>
}
}</pre></div>
<p>
Reports that any analysis results that were previously
associated with the given files should be considered to be
invalid because those files are no longer being analyzed,
either because the analysis root that contained it is no
longer being analyzed or because the file no longer exists.
</p>
<p>
If a file is included in this notification and at some later
time a notification with results for the file is received,
clients should assume that the file is once again being
analyzed and the information should be processed.
</p>
<p>
It is not possible to subscribe to or unsubscribe from this
notification.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>files ( List<<a href="#type_FilePath">FilePath</a>> )</i></b></dt><dd>
<p>
The files that are no longer being analyzed.
</p>
</dd></dl></dd><dt class="notification">analysis.folding</dt><dd><div class="box"><pre>notification: {
"event": "analysis.folding"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>regions</b>": List<<a href="#type_FoldingRegion">FoldingRegion</a>>
}
}</pre></div>
<p>
Reports the folding regions associated with a given
file. Folding regions can be nested, but will not be
overlapping. Nesting occurs when a foldable element, such as
a method, is nested inside another foldable element such as
a class.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"FOLDING"</tt> in
the list of services passed in an analysis.setSubscriptions
request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file containing the folding regions.
</p>
</dd><dt class="field"><b><i>regions ( List<<a href="#type_FoldingRegion">FoldingRegion</a>> )</i></b></dt><dd>
<p>
The folding regions contained in the file.
</p>
</dd></dl></dd><dt class="notification">analysis.highlights</dt><dd><div class="box"><pre>notification: {
"event": "analysis.highlights"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>regions</b>": List<<a href="#type_HighlightRegion">HighlightRegion</a>>
}
}</pre></div>
<p>
Reports the highlight regions associated with a given file.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"HIGHLIGHTS"</tt>
in the list of services passed in an
analysis.setSubscriptions request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file containing the highlight regions.
</p>
</dd><dt class="field"><b><i>regions ( List<<a href="#type_HighlightRegion">HighlightRegion</a>> )</i></b></dt><dd>
<p>
The highlight regions contained in the file. Each
highlight region represents a particular syntactic or
semantic meaning associated with some range. Note that
the highlight regions that are returned can overlap
other highlight regions if there is more than one
meaning associated with a particular region.
</p>
</dd></dl></dd><dt class="notification">analysis.navigation</dt><dd><div class="box"><pre>notification: {
"event": "analysis.navigation"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>regions</b>": List<<a href="#type_NavigationRegion">NavigationRegion</a>>
}
}</pre></div>
<p>
Reports the navigation targets associated with a given file.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"NAVIGATION"</tt>
in the list of services passed in an
analysis.setSubscriptions request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file containing the navigation regions.
</p>
</dd><dt class="field"><b><i>regions ( List<<a href="#type_NavigationRegion">NavigationRegion</a>> )</i></b></dt><dd>
<p>
The navigation regions contained in the file.
The regions are sorted by their offsets.
Each navigation region represents a list of targets
associated with some range. The lists will usually
contain a single target, but can contain more in the
case of a part that is included in multiple libraries
or in Dart code that is compiled against multiple
versions of a package. Note that the navigation
regions that are returned do not overlap other
navigation regions.
</p>
</dd></dl></dd><dt class="notification">analysis.occurrences</dt><dd><div class="box"><pre>notification: {
"event": "analysis.occurrences"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>occurrences</b>": List<<a href="#type_Occurrences">Occurrences</a>>
}
}</pre></div>
<p>
Reports the occurrences of references to elements within a
single file.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"OCCURRENCES"</tt>
in the list of services passed in an
analysis.setSubscriptions request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file in which the references occur.
</p>
</dd><dt class="field"><b><i>occurrences ( List<<a href="#type_Occurrences">Occurrences</a>> )</i></b></dt><dd>
<p>
The occurrences of references to elements within the
file.
</p>
</dd></dl></dd><dt class="notification">analysis.outline</dt><dd><div class="box"><pre>notification: {
"event": "analysis.outline"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>outline</b>": <a href="#type_Outline">Outline</a>
}
}</pre></div>
<p>
Reports the outline associated with a single file.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"OUTLINE"</tt> in
the list of services passed in an analysis.setSubscriptions
request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file with which the outline is associated.
</p>
</dd><dt class="field"><b><i>outline ( <a href="#type_Outline">Outline</a> )</i></b></dt><dd>
<p>
The outline associated with the file.
</p>
</dd></dl></dd><dt class="notification">analysis.overrides</dt><dd><div class="box"><pre>notification: {
"event": "analysis.overrides"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>overrides</b>": List<<a href="#type_Override">Override</a>>
}
}</pre></div>
<p>
Reports the overridding members in a file.
</p>
<p>
This notification is not subscribed to by default. Clients
can subscribe by including the value <tt>"OVERRIDES"</tt> in
the list of services passed in an analysis.setSubscriptions
request.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file with which the overrides are associated.
</p>
</dd><dt class="field"><b><i>overrides ( List<<a href="#type_Override">Override</a>> )</i></b></dt><dd>
<p>
The overrides associated with the file.
</p>
</dd></dl></dd></dl>
<h2 class="domain"><a name="domain_completion">Domain: completion</a></h2>
<p>
The code completion domain contains commands related to
getting code completion suggestions.
</p>
<h3>Requests</h3><dl><dt class="request">completion.getSuggestions</dt><dd><div class="box"><pre>request: {
"id": String
"method": "completion.getSuggestions"
"params": {
"<b>file</b>": <a href="#type_FilePath">FilePath</a>
"<b>offset</b>": int
}
}</pre><br><pre>response: {
"<b>id</b>": String
"error": <span style="color:#999999">optional</span> <a href="#type_RequestError">RequestError</a>
"result": {
"<b>id</b>": <a href="#type_CompletionId">CompletionId</a>
}
}</pre></div>
<p>
Request that completion suggestions for the given offset in
the given file be returned.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>file ( <a href="#type_FilePath">FilePath</a> )</i></b></dt><dd>
<p>
The file containing the point at which suggestions are
to be made.
</p>
</dd><dt class="field"><b><i>offset ( int )</i></b></dt><dd>
<p>
The offset within the file at which suggestions are to
be made.
</p>
</dd></dl><h4>Returns</h4><dl><dt class="field"><b><i>id ( <a href="#type_CompletionId">CompletionId</a> )</i></b></dt><dd>
<p>
The identifier used to associate results with this
completion request.
</p>
</dd></dl></dd></dl><h3>Notifications</h3><dl><dt class="notification">completion.results</dt><dd><div class="box"><pre>notification: {
"event": "completion.results"
"params": {
"<b>id</b>": <a href="#type_CompletionId">CompletionId</a>
"<b>replacementOffset</b>": int
"<b>replacementLength</b>": int
"<b>results</b>": List<<a href="#type_CompletionSuggestion">CompletionSuggestion</a>>
"<b>isLast</b>": bool
}
}</pre></div>
<p>
Reports the completion suggestions that should be presented
to the user. The set of suggestions included in the
notification is always a complete list that supersedes any
previously reported suggestions.
</p>
<h4>Parameters</h4><dl><dt class="field"><b><i>id ( <a href="#type_CompletionId">CompletionId</a> )</i></b></dt><dd>
<p>
The id associated with the completion.
</p>
</dd><dt class="field"><b><i>replacementOffset ( int )</i></b></dt><dd>
<p>
The offset of the start of the text to be
replaced. This will be different than the offset used
to request the completion suggestions if there was a
portion of an identifier before the original
offset. In particular, the replacementOffset will be
the offset of the beginning of said identifier.
</p>
</dd><dt class="field"><b><i>replacementLength ( int )</i></b></dt><dd>
<p>
The length of the text to be replaced if the remainder
of the identifier containing the cursor is to be
replaced when the suggestion is applied (that is, the
number of characters in the existing identifier).
</p>
</dd><dt class="field"><b><i>results ( List<<a href="#type_CompletionSuggestion">CompletionSuggestion</a>> )</i></b></dt><dd>
<p>
The completion suggestions being reported. The
notification contains all possible completions at the
requested cursor position, even those that do not match
the characters the user has already typed. This allows
the client to respond to further keystrokes from the
user without having to make additional requests.
</p>
</dd><dt class="field"><b><i>isLast ( bool )</i></b></dt><dd>
<p>
True if this is that last set of results that will be