pkg/analyzer_plugin/tool/spec/plugin_spec.html - Issue 2664213003: Add the generator and the generated files

Unified Diff: pkg/analyzer_plugin/tool/spec/plugin_spec.html

Issue 2664213003: Add the generator and the generated files (Closed)

Patch Set: add missed files Created 3 years, 11 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Index: pkg/analyzer_plugin/tool/spec/plugin_spec.html

diff --git a/pkg/analyzer_plugin/tool/spec/plugin_spec.html b/pkg/analyzer_plugin/tool/spec/plugin_spec.html

new file mode 100644

index 0000000000000000000000000000000000000000..84703abe613f69e4488b3e212d8167d0b70f4087

--- /dev/null

+++ b/pkg/analyzer_plugin/tool/spec/plugin_spec.html

@@ -0,0 +1,2780 @@

+<!doctype html>

+<html>

+<head>

+ <meta charset="UTF-8"/>

+ <title>Analysis Server Plugin API Specification</title>

+</head>

+<body>

+<h1>Analysis Server Plugin API Specification</h1>

+<h1 style="color:#999999">Version

+ <version>1.0.0-alpha.0</version>

+</h1>

+

+ This document contains a specification of the API used by the analysis

+ server to communicate with analysis server plugins. Changes to the API will be

+ accompanied by an update to the protocol version number according to the

+ principles of semantic versioning

+ (<a href="http://semver.org/">semver.org</a>).

+

+<h2>Overview</h2>

+

+ TBD

+

+<domain name="plugin">

+

+ The plugin domain contains API’s related to the execution of a plugin.

+

+

+ TODO: Provide notifications by which plugins can report instrumentation

+ and/or DartSilo data.

+

+

+ TODO: Add a notification to the server protocol to inform the client of

+ problems related to the execution of plugins.

+

+ <request method="versionCheck">

+

+ Used to request that the plugin perform a version check to confirm that it

+ works with the version of the analysis server that is executing it.

+

+ <params>

+ <field name="version">

+ <ref>String</ref>

+

+ The version number of the plugin spec supported by the analysis server

+ that is executing the plugin.

+

+ </field>

+ </params>

+ <result>

+ <field name="isCompatible">

+ <ref>bool</ref>

+

+ A flag indicating whether the plugin supports the same version of the

+ plugin spec as the analysis server. If the value is <tt>false</tt>,

+ then the plugin is expected to shutdown after returning the response.

+

+ </field>

+ <field name="name">

+ <ref>String</ref>

+

+ The name of the plugin. This value is only used when the server needs

+ to identify the plugin, either to the user or for debugging purposes.

+

+ </field>

+ <field name="version">

+ <ref>String</ref>

+

+ The version of the plugin. This value is only used when the server

+ needs to identify the plugin, either to the user or for debugging

+ purposes.

+

+ </field>

+ <field name="email" optional="true">

+ <ref>String</ref>

+

+ An e-mail address that either the client or the user can use to

+ contact the maintainers of the plugin when there is a problem.

+

+ </field>

+ <field name="interestingFiles">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ The glob patterns of the files for which the plugin will provide

+ information. This value is ignored if the <tt>isCompatible</tt>

+ field is <tt>false</tt>. Otherwise, it will be used to identify

+ the files for which the plugin should be notified of changes.

+

+ </field>

+ </result>

+ </request>

+ <request method="shutdown">

+

+ Used to request that the plugin exit. The server will not send any other

+ requests after this request. The plugin should not send any responses or

+ notifications after sending the response to this request.

+

+ </request>

+ <notification event="error">

+

+ Used to report that an unexpected error has occurred while executing the

+ plugin. This notification is not used for problems with specific requests

+ (which should be returned as part of the response) but is used for

+ exceptions that occur while performing other tasks, such as analysis or

+ preparing notifications.

+

+ <params>

+ <field name="isFatal">

+ <ref>bool</ref>

+

+ A flag indicating whether the error is a fatal error, meaning that the

+ plugin will shutdown automatically after sending this notification. If

+ <tt>true</tt>, the server will not expect any other responses or

+ notifications from the plugin.

+

+ </field>

+ <field name="message">

+ <ref>String</ref>

+

+ The error message indicating what kind of error was encountered.

+

+ </field>

+ <field name="stackTrace">

+ <ref>String</ref>

+

+ The stack trace associated with the generation of the error, used for

+ debugging the plugin.

+

+ </field>

+ </params>

+ </notification>

+</domain>

+<domain name="analysis">

+

+ The analysis domain contains API’s related to the analysis of files.

+

+ <request method="handleWatchEvents">

+

+ Used to inform the plugin of changes to files in the file system. Only

+ events associated with files that match the <tt>interestingFiles</tt> glob

+ patterns will be forwarded to the plugin.

+

+ <params>

+ <field name="events">

+ <list>

+ <ref>WatchEvent</ref>

+ </list>

+

+ The watch events that the plugin should handle.

+

+ </field>

+ </params>

+ </request>

+ <request method="reanalyze">

+

+ Used to force the re-analysis of everything contained in the specified

+ context roots. This should cause all previously computed analysis results

+ to be discarded and recomputed, and should cause all subscribed

+ notifications to be re-sent.

+

+ <params>

+ <field name="roots" optional="true">

+ <list>

+ <ref>FilePath</ref>

+ </list>

+

+ A list of the context roots that are to be re-analyzed.

+

+

+ If no context roots are provided, then all current context roots

+ should be re-analyzed.

+

+ </field>

+ </params>

+ </request>

+ <request method="setContextBuilderOptions">

+

+ Used to set the options used to build analysis contexts. This request will

+ be sent exactly once before any context roots have been specified.

+

+ <params>

+ <field name="options">

+ <ref>ContextBuilderOptions</ref>

+

+ The options used to build the analysis contexts.

+

+ </field>

+ </params>

+ </request>

+ <request method="setContextRoots">

+

+ Set the list of context roots that should be analyzed.

+

+ <params>

+ <field name="roots">

+ <list>

+ <ref>ContextRoot</ref>

+ </list>

+

+ A list of the context roots that should be analyzed.

+

+ </field>

+ </params>

+ </request>

+ <request method="setPriorityFiles">

+

+ Used to set the priority files to the files in the given list. A priority

+ file is a file that should be 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.

+

+ <params>

+ <field name="files">

+ <list>

+ <ref>FilePath</ref>

+ </list>

+

+ The files that are to be a priority for analysis.

+

+ </field>

+ </params>

+ </request>

+ <request method="setSubscriptions">

+

+ Used to subscribe for services that are specific to individual files. All

+ previous subscriptions should be replaced by the current set of

+ subscriptions. If a given service is not included as a key in the map then

+ no files should be subscribed to the service, exactly as if the service

+ had been included in the map with an explicit empty list of files.

+

+ <params>

+ <field name="subscriptions">

+ <map>

+ <key>

+ <ref>AnalysisService</ref>

+ </key>

+ <value>

+ <list>

+ <ref>FilePath</ref>

+ </list>

+ </value>

+ </map>

+

+ A table mapping services to a list of the files being subscribed to

+ the service.

+

+ </field>

+ </params>

+ </request>

+ <request method="updateContent">

+

+ Used to 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 the plugin 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.

+

+ <params>

+ <field name="files">

+ <map>

+ <key>

+ <ref>FilePath</ref>

+ </key>

+ <value>

+ <union field="type">

+ <ref>AddContentOverlay</ref>

+ <ref>ChangeContentOverlay</ref>

+ <ref>RemoveContentOverlay</ref>

+ </union>

+ </value>

+ </map>

+

+ A table mapping the files whose content has changed to a description

+ of the content change.

+

+ </field>

+ </params>

+ </request>

+ <notification event="errors">

+

+ Used to report 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.

+

+

+ TODO: Decide whether we need to support the '--no-error-notification'

+ option.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the errors.

+

+ </field>

+ <field name="errors">

+ <list>

+ <ref>AnalysisError</ref>

+ </list>

+

+ The errors contained in the file.

+

+ </field>

+ </params>

+ </notification>

+ <notification event="folding">

+

+ Used to report the folding regions associated with a given file. Folding

+ regions can be nested, but cannot be overlapping. Nesting occurs when a

+ foldable element, such as a method, is nested inside another foldable

+ element such as a class.

+

+

+ Folding regions that overlap a folding region computed by the server, or

+ by one of the other plugins that are currently running, might be dropped

+ by the server in order to present a consistent view to the client.

+

+

+ This notification should only be sent if the server has subscribed to it

+ by including the value <tt>"FOLDING"</tt> in the list of services

+ passed in an analysis.setSubscriptions request.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the folding regions.

+

+ </field>

+ <field name="regions">

+ <list>

+ <ref>FoldingRegion</ref>

+ </list>

+

+ The folding regions contained in the file.

+

+ </field>

+ </params>

+ </notification>

+ <notification event="highlights">

+

+ Used to report the highlight regions associated with a given 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.

+

+

+ This notification should only be sent if the server has subscribed to it

+ by including the value <tt>"HIGHLIGHTS"</tt> in the list of services

+ passed in an analysis.setSubscriptions request.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the highlight regions.

+

+ </field>

+ <field name="regions">

+ <list>

+ <ref>HighlightRegion</ref>

+ </list>

+

+ The highlight regions contained in the file.

+

+ </field>

+ </params>

+ </notification>

+ <notification event="navigation">

+

+ Used to report the navigation regions associated with a given file. 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 should not overlap other navigation

+ regions.

+

+

+ Navigation regions that overlap a navigation region computed by the

+ server, or by one of the other plugins that are currently running, might

+ be dropped or modified by the server in order to present a consistent view

+ to the client.

+

+

+ This notification should only be sent if the server has subscribed to it

+ by including the value <tt>"NAVIGATION"</tt> in the list of services

+ passed in an analysis.setSubscriptions request.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the navigation regions.

+

+ </field>

+ <field name="regions">

+ <list>

+ <ref>NavigationRegion</ref>

+ </list>

+

+ The navigation regions contained in the file.

+

+ </field>

+ <field name="targets">

+ <list>

+ <ref>NavigationTarget</ref>

+ </list>

+

+ The navigation targets referenced in the file. They are referenced by

+ <a href="#type_NavigationRegion">NavigationRegion</a>s by their index

+ in this array.

+

+ </field>

+ <field name="files">

+ <list>

+ <ref>FilePath</ref>

+ </list>

+

+ The files containing navigation targets referenced in the file. They

+ are referenced by

+ <a href="#type_NavigationTarget">NavigationTarget</a>s by their index

+ in this array.

+

+ </field>

+ </params>

+ </notification>

+ <notification event="occurrences">

+

+ Used to report the occurrences of references to elements within a single

+ file. None of the occurrence regions should overlap.

+

+

+ Occurrence regions that overlap an occurrence region computed by the

+ server, or by one of the other plugins that are currently running, might

+ be dropped or modified by the server in order to present a consistent view

+ to the client.

+

+

+ This notification should only be sent if the server has subscribed to it

+ by including the value <tt>"OCCURRENCES"</tt> in the list of services

+ passed in an analysis.setSubscriptions request.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file in which the references occur.

+

+ </field>

+ <field name="occurrences">

+ <list>

+ <ref>Occurrences</ref>

+ </list>

+

+ The occurrences of references to elements within the file.

+

+ </field>

+ </params>

+ </notification>

+ <notification event="outline">

+

+ Used to report the outline fragments associated with a single file.

+

+

+ The outline fragments will be merged with any outline produced by the

+ server and with any fragments produced by other plugins. If the server

+ cannot create a coherent outline, some fragments might be dropped.

+

+

+ This notification should only be sent if the server has subscribed to it

+ by including the value <tt>"OUTLINE"</tt> in the list of services

+ passed in an analysis.setSubscriptions request.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file with which the outline is associated.

+

+ </field>

+ <field name="outline">

+ <list>

+ <ref>Outline</ref>

+ </list>

+

+ The outline fragments associated with the file.

+

+ </field>

+ </params>

+ </notification>

+</domain>

+<domain name="completion">

+

+ The code completion domain contains API's related to getting code completion

+ suggestions.

+

+ <request method="getSuggestions">

+

+ Used to request that completion suggestions for the given offset in the

+ given file be returned.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the point at which suggestions are to be made.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset within the file at which suggestions are to be made.

+

+ </field>

+ </params>

+ <result>

+ <field name="replacementOffset">

+ <ref>int</ref>

+

+ 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.

+

+ </field>

+ <field name="replacementLength">

+ <ref>int</ref>

+

+ 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).

+

+ </field>

+ <field name="results">

+ <list>

+ <ref>CompletionSuggestion</ref>

+ </list>

+

+ 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.

+

+ </field>

+ </result>

+ </request>

+</domain>

+<domain name="edit">

+

+ The edit domain contains API's related to edits that can be applied to the

+ code.

+

+ <request method="getAssists">

+

+ Used to request the set of assists that are available at the given

+ location. An assist is distinguished from a refactoring primarily by the

+ fact that it affects a single file and does not require user input in

+ order to be performed.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the code for which assists are being requested.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the code for which assists are being requested.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the code for which assists are being requested.

+

+ </field>

+ </params>

+ <result>

+ <field name="assists">

+ <list>

+ <ref>SourceChange</ref>

+ </list>

+

+ The assists that are available at the given location.

+

+ </field>

+ </result>

+ </request>

+ <request method="getAvailableRefactorings">

+

+ Used to request a list of the kinds of refactorings that are valid for the

+ given selection in the given file.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the code on which the refactoring would be based.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the code on which the refactoring would be based.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the code on which the refactoring would be based.

+

+ </field>

+ </params>

+ <result>

+ <field name="kinds">

+ <list>

+ <ref>RefactoringKind</ref>

+ </list>

+

+ The kinds of refactorings that are valid for the given selection.

+

+

+ The list of refactoring kinds is currently limited to those defined by

+ the server API, preventing plugins from adding their own refactorings.

+ However, plugins can support pre-defined refactorings, such as a

+ rename refactoring, at locations not supported by server.

+

+ </field>

+ </result>

+ </request>

+ <request method="getFixes">

+

+ Used to request the set of fixes that are available for the errors at a

+ given offset in a given file.

+

+ <params>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the errors for which fixes are being requested.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset used to select the errors for which fixes will be returned.

+

+ </field>

+ </params>

+ <result>

+ <field name="fixes">

+ <list>

+ <ref>AnalysisErrorFixes</ref>

+ </list>

+

+ The fixes that are available for the errors at the given offset.

+

+ </field>

+ </result>

+ </request>

+ <request method="getRefactoring">

+

+ Used to request the changes required to perform a refactoring.

+

+ <params>

+ <field name="kind">

+ <ref>RefactoringKind</ref>

+

+ The kind of refactoring to be performed.

+

+ </field>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the code involved in the refactoring.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region involved in the refactoring.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region involved in the refactoring.

+

+ </field>

+ <field name="validateOnly">

+ <ref>bool</ref>

+

+ True if the client is only requesting that the values of the options

+ be validated and no change be generated.

+

+ </field>

+ <field name="options" optional="true">

+ <ref>RefactoringOptions</ref>

+

+ Data used to provide values provided by the user. The structure of the

+ data is dependent on the kind of refactoring being performed. The data

+ that is expected is documented in the section titled

+ <a href="#refactorings">Refactorings</a>, labeled as "Options". This

+ field can be omitted if the refactoring does not require any options

+ or if the values of those options are not known.

+

+ </field>

+ </params>

+ <result>

+ <field name="initialProblems">

+ <list>

+ <ref>RefactoringProblem</ref>

+ </list>

+

+ The initial status of the refactoring, that is, problems related to

+ the context in which the refactoring is requested. The list should be

+ empty if there are no known problems.

+

+ </field>

+ <field name="optionsProblems">

+ <list>

+ <ref>RefactoringProblem</ref>

+ </list>

+

+ The options validation status, that is, problems in the given options,

+ such as light-weight validation of a new name, flags compatibility,

+ etc. The list should be empty if there are no known problems.

+

+ </field>

+ <field name="finalProblems">

+ <list>

+ <ref>RefactoringProblem</ref>

+ </list>

+

+ The final status of the refactoring, that is, problems identified in

+ the result of a full, potentially expensive validation and / or change

+ creation. The list should be empty if there are no known problems.

+

+ </field>

+ <field name="feedback" optional="true">

+ <ref>RefactoringFeedback</ref>

+

+ Data used to provide feedback to the user. The structure of the data

+ is dependent on the kind of refactoring being created. The data that

+ is returned is documented in the section titled

+ <a href="#refactorings">Refactorings</a>, labeled as "Feedback".

+

+ </field>

+ <field name="change" optional="true">

+ <ref>SourceChange</ref>

+

+ The changes that are to be applied to affect the refactoring. This

+ field can be omitted if there are problems that prevent a set of

+ changes from being computed, such as having no options specified for a

+ refactoring that requires them, or if only validation was requested.

+

+ </field>

+ <field name="potentialEdits" optional="true">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ The ids of source edits that are not known to be valid. An edit is not

+ known to be valid if there was insufficient type information for the

+ plugin to be able to determine whether or not the code needs to be

+ modified, such as when a member is being renamed and there is a

+ reference to a member from an unknown type. This field can be omitted

+ if the change field is omitted or if there are no potential edits for

+ the refactoring.

+

+ </field>

+ </result>

+ </request>

+</domain>

+<types>

+ <h2 class="domain"><a name="types">Types</a></h2>

+

+ This section contains descriptions of the data types referenced in the API’s

+ of the various domains.

+

+ <type name="AddContentOverlay">

+

+ A directive to begin overlaying the contents of a file. The supplied

+ content will be used for analysis in place of the file contents in the

+ filesystem.

+

+

+ If this directive is used on a file that already has a file content

+ overlay, the old overlay is discarded and replaced with the new one.

+

+ <object>

+ <field name="type" value="add"><ref>String</ref></field>

+ <field name="content">

+ <ref>String</ref>

+

+ The new content of the file.

+

+ </field>

+ </object>

+ </type>

+ <type name="AnalysisError">

+

+ An indication of an error, warning, or hint that was produced by the

+ analysis.

+

+ <object>

+ <field name="severity">

+ <ref>AnalysisErrorSeverity</ref>

+

+ The severity of the error.

+

+ </field>

+ <field name="type">

+ <ref>AnalysisErrorType</ref>

+

+ The type of the error.

+

+ </field>

+ <field name="location">

+ <ref>Location</ref>

+

+ The location associated with the error.

+

+ </field>

+ <field name="message">

+ <ref>String</ref>

+

+ The message to be displayed for this error. The message should

+ indicate what is wrong with the code and why it is wrong.

+

+ </field>

+ <field name="correction" optional="true">

+ <ref>String</ref>

+

+ The correction message to be displayed for this error. The correction

+ message should indicate how the user can fix the error. The field is

+ omitted if there is no correction message associated with the error

+ code.

+

+ </field>

+ <field name="code">

+ <ref>String</ref>

+

+ The name, as a string, of the error code associated with this error.

+

+ </field>

+ <field name="hasFix" optional="true">

+ <ref>bool</ref>

+

+ A hint to indicate to interested clients that this error has an

+ associated fix (or fixes). The absence of this field implies there

+ are not known to be fixes. Note that since the operation to calculate

+ whether fixes apply needs to be performant it is possible that

+ complicated tests will be skipped and a false negative returned. For

+ this reason, this attribute should be treated as a "hint". Despite the

+ possibility of false negatives, no false positives should be returned.

+ If a client sees this flag set they can proceed with the confidence

+ that there are in fact associated fixes.

+

+ </field>

+ </object>

+ </type>

+ <type name="AnalysisErrorFixes">

+

+ A list of fixes associated with a specific error

+

+ <object>

+ <field name="error">

+ <ref>AnalysisError</ref>

+

+ The error with which the fixes are associated.

+

+ </field>

+ <field name="fixes">

+ <list><ref>SourceChange</ref></list>

+

+ The fixes associated with the error.

+

+ </field>

+ </object>

+ </type>

+ <type name="AnalysisErrorSeverity">

+

+ An enumeration of the possible severities of analysis errors.

+

+ <enum>

+ <value><code>INFO</code></value>

+ <value><code>WARNING</code></value>

+ <value><code>ERROR</code></value>

+ </enum>

+ </type>

+ <type name="AnalysisErrorType">

+

+ An enumeration of the possible types of analysis errors.

+

+ <enum>

+ <value><code>CHECKED_MODE_COMPILE_TIME_ERROR</code></value>

+ <value><code>COMPILE_TIME_ERROR</code></value>

+ <value><code>HINT</code></value>

+ <value><code>LINT</code></value>

+ <value><code>STATIC_TYPE_WARNING</code></value>

+ <value><code>STATIC_WARNING</code></value>

+ <value><code>SYNTACTIC_ERROR</code></value>

+ <value><code>TODO</code></value>

+ </enum>

+ </type>

+ <type name="AnalysisService">

+

+ An enumeration of the services provided by the analysis domain that are

+ related to a specific list of files.

+

+ <enum>

+ <value><code>FOLDING</code></value>

+ <value><code>HIGHLIGHTS</code></value>

+ <value><code>NAVIGATION</code></value>

+ <value><code>OCCURRENCES</code></value>

+ <value><code>OUTLINE</code></value>

+ </enum>

+ </type>

+ <type name="ChangeContentOverlay">

+

+ A directive to modify an existing file content overlay. One or more ranges

+ of text are deleted from the old file content overlay and replaced with

+ new text.

+

+

+ The edits are applied in the order in which they occur in the list. This

+ means that the offset of each edit must be correct under the assumption

+ that all previous edits have been applied.

+

+

+ It is an error to use this overlay on a file that does not yet have a file

+ content overlay or that has had its overlay removed via

+ <a href="#type_RemoveContentOverlay">RemoveContentOverlay</a>.

+

+

+ If any of the edits cannot be applied due to its offset or length being

+ out of range, an <tt>INVALID_OVERLAY_CHANGE</tt> error will be reported.

+

+ <object>

+ <field name="type" value="change"><ref>String</ref></field>

+ <field name="edits">

+ <list><ref>SourceEdit</ref></list>

+

+ The edits to be applied to the file.

+

+ </field>

+ </object>

+ </type>

+ <type name="CompletionSuggestion">

+

+ A suggestion for how to complete partially entered text. Many of the

+ fields are optional, depending on the kind of element being suggested.

+

+ <object>

+ <field name="kind">

+ <ref>CompletionSuggestionKind</ref>

+

+ The kind of element being suggested.

+

+ </field>

+ <field name="relevance">

+ <ref>int</ref>

+

+ The relevance of this completion suggestion where a higher number

+ indicates a higher relevance.

+

+ </field>

+ <field name="completion">

+ <ref>String</ref>

+

+ The identifier to be inserted if the suggestion is selected. If the

+ suggestion is for a method or function, the client might want to

+ additionally insert a template for the parameters. The information

+ required in order to do so is contained in other fields.

+

+ </field>

+ <field name="selectionOffset">

+ <ref>int</ref>

+

+ The offset, relative to the beginning of the completion, of where the

+ selection should be placed after insertion.

+

+ </field>

+ <field name="selectionLength">

+ <ref>int</ref>

+

+ The number of characters that should be selected after insertion.

+

+ </field>

+ <field name="isDeprecated">

+ <ref>bool</ref>

+

+ True if the suggested element is deprecated.

+

+ </field>

+ <field name="isPotential">

+ <ref>bool</ref>

+

+ True if the element is not known to be valid for the target. This

+ happens if the type of the target is dynamic.

+

+ </field>

+ <field name="docSummary" optional="true">

+ <ref>String</ref>

+

+ An abbreviated version of the Dartdoc associated with the element

+ being suggested, This field is omitted if there is no Dartdoc

+ associated with the element.

+

+ </field>

+ <field name="docComplete" optional="true">

+ <ref>String</ref>

+

+ The Dartdoc associated with the element being suggested. This field is

+ omitted if there is no Dartdoc associated with the element.

+

+ </field>

+ <field name="declaringType" optional="true">

+ <ref>String</ref>

+

+ The class that declares the element being suggested. This field is

+ omitted if the suggested element is not a member of a class.

+

+ </field>

+ <field name="element" optional="true">

+ <ref>Element</ref>

+

+ Information about the element reference being suggested.

+

+ </field>

+ <field name="returnType" optional="true">

+ <ref>String</ref>

+

+ The return type of the getter, function or method or the type of the

+ field being suggested. This field is omitted if the suggested element

+ is not a getter, function or method.

+

+ </field>

+ <field name="parameterNames" optional="true">

+ <list><ref>String</ref></list>

+

+ The names of the parameters of the function or method being suggested.

+ This field is omitted if the suggested element is not a setter,

+ function or method.

+

+ </field>

+ <field name="parameterTypes" optional="true">

+ <list><ref>String</ref></list>

+

+ The types of the parameters of the function or method being suggested.

+ This field is omitted if the parameterNames field is omitted.

+

+ </field>

+ <field name="requiredParameterCount" optional="true">

+ <ref>int</ref>

+

+ The number of required parameters for the function or method being

+ suggested. This field is omitted if the parameterNames field is

+ omitted.

+

+ </field>

+ <field name="hasNamedParameters" optional="true">

+ <ref>bool</ref>

+

+ True if the function or method being suggested has at least one named

+ parameter. This field is omitted if the parameterNames field is

+ omitted.

+

+ </field>

+ <field name="parameterName" optional="true">

+ <ref>String</ref>

+

+ The name of the optional parameter being suggested. This field is

+ omitted if the suggestion is not the addition of an optional argument

+ within an argument list.

+

+ </field>

+ <field name="parameterType" optional="true">

+ <ref>String</ref>

+

+ The type of the options parameter being suggested. This field is

+ omitted if the parameterName field is omitted.

+

+ </field>

+ <field name="importUri" optional="true">

+ <ref>String</ref>

+

+ The import to be added if the suggestion is out of scope and needs

+ an import to be added to be in scope.

+

+ </field>

+ </object>

+ </type>

+ <type name="CompletionSuggestionKind">

+

+ An enumeration of the kinds of elements that can be included in a

+ completion suggestion.

+

+ <enum>

+ <value>

+ <code>ARGUMENT_LIST</code>

+

+ A list of arguments for the method or function that is being

+ invoked. For this suggestion kind, the completion field is a

+ textual representation of the invocation and the parameterNames,

+ parameterTypes, and requiredParameterCount attributes are defined.

+

+ </value>

+ <value><code>IMPORT</code></value>

+ <value>

+ <code>IDENTIFIER</code>

+

+ The element identifier should be inserted at the completion

+ location. For example "someMethod" in <tt>import 'myLib.dart' show

+ someMethod;</tt>. For suggestions of this kind, the element

+ attribute is defined and the completion field is the element's

+ identifier.

+

+ </value>

+ <value>

+ <code>INVOCATION</code>

+

+ The element is being invoked at the completion location. For

+ example, 'someMethod' in <tt>x.someMethod();</tt>. For suggestions

+ of this kind, the element attribute is defined and the completion

+ field is the element's identifier.

+

+ </value>

+ <value>

+ <code>KEYWORD</code>

+

+ A keyword is being suggested. For suggestions of this kind, the

+ completion is the keyword.

+

+ </value>

+ <value>

+ <code>NAMED_ARGUMENT</code>

+

+ A named argument for the current call site is being suggested. For

+ suggestions of this kind, the completion is the named argument

+ identifier including a trailing ':' and a space.

+

+ </value>

+ <value><code>OPTIONAL_ARGUMENT</code></value>

+ <value><code>PARAMETER</code></value>

+ </enum>

+ </type>

+ <type name="ContextBuilderOptions">

+

+ The options used to build an analysis context.

+

+ <object>

+ <field name="dartSdkSummaryPath" optional="true">

+ <ref>String</ref>

+

+ The file path of the file containing the summary of the SDK that

+ should be used to "analyze" the SDK. The field will be omitted if the

+ summary should be found in the SDK.

+

+ </field>

+ <field name="defaultAnalysisOptionsFilePath" optional="true">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ The file path of the analysis options file that should be used in

+ place of any file in the root directory or a parent of the root

+ directory. The field will be omitted if the normal lookup mechanism

+ should be used.

+

+ </field>

+ <field name="declaredVariables" optional="true">

+ <map>

+ <key>

+ <ref>String</ref>

+ </key>

+ <value>

+ <ref>String</ref>

+ </value>

+ </map>

+

+ A table mapping variable names to values for the declared variables.

+ The field will be omitted if no additional variables need to be

+ declared.

+

+ </field>

+ <!--

+ TODO(brianwilkerson) Figure out how to handle analysis options.

+ <field name="defaultOptions" optional="true">

+ <ref>AnalysisOptions</ref>

+

+ The default analysis options that should be used unless some or all of

+ them are overridden in the analysis options file. The field will be

+ omitted if the default defaults should be used.

+

+ </field>

+ -->

+ <field name="defaultPackageFilePath" optional="true">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ The file path of the .packages file that should be used in place of

+ any file found using the normal (Package Specification DEP) lookup

+ mechanism. The field will be omitted if the normal lookup mechanism

+ should be used.

+

+ </field>

+ <field name="defaultPackagesDirectoryPath" optional="true">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ The file path of the packages directory that should be used in place

+ of any file found using the normal (Package Specification DEP) lookup

+ mechanism. The field will be omitted if the normal lookup mechanism

+ should be used.

+

+ </field>

+ </object>

+ </type>

+ <type name="ContextRoot">

+

+ A description of an analysis context.

+

+ <object>

+ <field name="root">

+ <ref>String</ref>

+

+ The absolute path of the root directory containing the files to be

+ analyzed.

+

+ </field>

+ <field name="exclude">

+ <list>

+ <ref>String</ref>

+ </list>

+

+ A list of the absolute paths of files and directories within the root

+ directory that should not be analyzed.

+

+ </field>

+ </object>

+ </type>

+ <type name="Element">

+

+ Information about an element (something that can be declared in code).

+

+ <object>

+ <field name="kind">

+ <ref>ElementKind</ref>

+

+ The kind of the element.

+

+ </field>

+ <field name="name">

+ <ref>String</ref>

+

+ The name of the element. This is typically used as the label in the outline.

+

+ </field>

+ <field name="location" optional="true">

+ <ref>Location</ref>

+

+ The location of the name in the declaration of the element.

+

+ </field>

+ <field name="flags">

+ <ref>int</ref>

+

+ A bit-map containing the following flags:

+

+ <ul>

+ <li>

+ 0x01 - set if the element is explicitly or implicitly abstract

+ </li>

+ <li>

+ 0x02 - set if the element was declared to be ‘const’

+ </li>

+ <li>

+ 0x04 - set if the element was declared to be ‘final’

+ </li>

+ <li>

+ 0x08 - set if the element is a static member of a class or is a

+ top-level function or field

+ </li>

+ <li>

+ 0x10 - set if the element is private

+ </li>

+ <li>

+ 0x20 - set if the element is deprecated

+ </li>

+ </ul>

+ </field>

+ <field name="parameters" optional="true">

+ <ref>String</ref>

+

+ The parameter list for the element. If the element is not a method or

+ function this field will not be defined. If the element doesn't have

+ parameters (e.g. getter), this field will not be defined. If the

+ element has zero parameters, this field will have a value of "()".

+

+ </field>

+ <field name="returnType" optional="true">

+ <ref>String</ref>

+

+ The return type of the element. If the element is not a method or

+ function this field will not be defined. If the element does not have

+ a declared return type, this field will contain an empty string.

+

+ </field>

+ <field name="typeParameters" optional="true">

+ <ref>String</ref>

+

+ The type parameter list for the element. If the element doesn't have

+ type parameters, this field will not be defined.

+

+ </field>

+ </object>

+ </type>

+ <type name="ElementKind">

+

+ An enumeration of the kinds of elements.

+

+ <enum>

+ <value><code>CLASS</code></value>

+ <value><code>CLASS_TYPE_ALIAS</code></value>

+ <value><code>COMPILATION_UNIT</code></value>

+ <value><code>CONSTRUCTOR</code></value>

+ <value><code>ENUM</code></value>

+ <value><code>ENUM_CONSTANT</code></value>

+ <value><code>FIELD</code></value>

+ <value><code>FILE</code></value>

+ <value><code>FUNCTION</code></value>

+ <value><code>FUNCTION_TYPE_ALIAS</code></value>

+ <value><code>GETTER</code></value>

+ <value><code>LABEL</code></value>

+ <value><code>LIBRARY</code></value>

+ <value><code>LOCAL_VARIABLE</code></value>

+ <value><code>METHOD</code></value>

+ <value><code>PARAMETER</code></value>

+ <value><code>PREFIX</code></value>

+ <value><code>SETTER</code></value>

+ <value><code>TOP_LEVEL_VARIABLE</code></value>

+ <value><code>TYPE_PARAMETER</code></value>

+ <value><code>UNKNOWN</code></value>

+ </enum>

+ </type>

+ <type name="FilePath">

+ <ref>String</ref>

+

+ The absolute, normalized path of a file.

+

+

+ If the format of a file path in a request is not valid, e.g. the path is

+ not absolute or is not normalized, then an error of type

+ <tt>INVALID_FILE_PATH_FORMAT</tt> will be generated.

+

+ </type>

+ <type name="FoldingKind">

+

+ An enumeration of the kinds of folding regions.

+

+ <enum>

+ <value><code>COMMENT</code></value>

+ <value><code>CLASS_MEMBER</code></value>

+ <value><code>DIRECTIVES</code></value>

+ <value><code>DOCUMENTATION_COMMENT</code></value>

+ <value><code>TOP_LEVEL_DECLARATION</code></value>

+ </enum>

+ </type>

+ <type name="FoldingRegion">

+

+ A description of a region that can be folded.

+

+ <object>

+ <field name="kind">

+ <ref>FoldingKind</ref>

+

+ The kind of the region.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region to be folded.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region to be folded.

+

+ </field>

+ </object>

+ </type>

+ <type name="HighlightRegion">

+

+ A description of a region that could have special highlighting associated

+ with it.

+

+ <object>

+ <field name="type">

+ <ref>HighlightRegionType</ref>

+

+ The type of highlight associated with the region.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region to be highlighted.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region to be highlighted.

+

+ </field>

+ </object>

+ </type>

+ <type name="HighlightRegionType">

+

+ An enumeration of the kinds of highlighting that can be applied to files.

+

+ <enum>

+ <value><code>ANNOTATION</code></value>

+ <value><code>BUILT_IN</code></value>

+ <value><code>CLASS</code></value>

+ <value><code>COMMENT_BLOCK</code></value>

+ <value><code>COMMENT_DOCUMENTATION</code></value>

+ <value><code>COMMENT_END_OF_LINE</code></value>

+ <value><code>CONSTRUCTOR</code></value>

+ <value><code>DIRECTIVE</code></value>

+ <value>

+ <code>DYNAMIC_TYPE</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>DYNAMIC_LOCAL_VARIABLE_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>DYNAMIC_LOCAL_VARIABLE_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>DYNAMIC_PARAMETER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>DYNAMIC_PARAMETER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value><code>ENUM</code></value>

+ <value><code>ENUM_CONSTANT</code></value>

+ <value>

+ <code>FIELD</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>FIELD_STATIC</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>FUNCTION</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>FUNCTION_DECLARATION</code>

+ Only for version 1 of highlight.

+ </value>

+ <value><code>FUNCTION_TYPE_ALIAS</code></value>

+ <value>

+ <code>GETTER_DECLARATION</code>

+ Only for version 1 of highlight.

+ </value>

+ <value><code>IDENTIFIER_DEFAULT</code></value>

+ <value><code>IMPORT_PREFIX</code></value>

+ <value>

+ <code>INSTANCE_FIELD_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_FIELD_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_GETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_GETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_METHOD_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_METHOD_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_SETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INSTANCE_SETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>INVALID_STRING_ESCAPE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value><code>KEYWORD</code></value>

+ <value><code>LABEL</code></value>

+ <value>

+ <code>LIBRARY_NAME</code>

+ Only for version 2 of highlight.

+ </value>

+ <value><code>LITERAL_BOOLEAN</code></value>

+ <value><code>LITERAL_DOUBLE</code></value>

+ <value><code>LITERAL_INTEGER</code></value>

+ <value><code>LITERAL_LIST</code></value>

+ <value><code>LITERAL_MAP</code></value>

+ <value><code>LITERAL_STRING</code></value>

+ <value>

+ <code>LOCAL_FUNCTION_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>LOCAL_FUNCTION_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>LOCAL_VARIABLE</code>

+ Only for version 1 of highlight.

+ </value>

+ <value><code>LOCAL_VARIABLE_DECLARATION</code></value>

+ <value>

+ <code>LOCAL_VARIABLE_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>METHOD</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>METHOD_DECLARATION</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>METHOD_DECLARATION_STATIC</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>METHOD_STATIC</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>PARAMETER</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>SETTER_DECLARATION</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_VARIABLE</code>

+ Only for version 1 of highlight.

+ </value>

+ <value>

+ <code>PARAMETER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>PARAMETER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_FIELD_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_GETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_GETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_METHOD_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_METHOD_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_SETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>STATIC_SETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_FUNCTION_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_FUNCTION_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_GETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_GETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_SETTER_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_SETTER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>TOP_LEVEL_VARIABLE_DECLARATION</code>

+ Only for version 2 of highlight.

+ </value>

+ <value><code>TYPE_NAME_DYNAMIC</code></value>

+ <value><code>TYPE_PARAMETER</code></value>

+ <value>

+ <code>UNRESOLVED_INSTANCE_MEMBER_REFERENCE</code>

+ Only for version 2 of highlight.

+ </value>

+ <value>

+ <code>VALID_STRING_ESCAPE</code>

+ Only for version 2 of highlight.

+ </value>

+ </enum>

+ </type>

+ <type name="LinkedEditGroup">

+

+ A collection of positions that should be linked (edited simultaneously)

+ for the purposes of updating code after a source change. For example, if a

+ set of edits introduced a new variable name, the group would contain all

+ of the positions of the variable name so that if the client wanted to let

+ the user edit the variable name after the operation, all occurrences of

+ the name could be edited simultaneously.

+

+ <object>

+ <field name="positions">

+ <list><ref>Position</ref></list>

+

+ The positions of the regions that should be edited simultaneously.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the regions that should be edited simultaneously.

+

+ </field>

+ <field name="suggestions">

+ <list><ref>LinkedEditSuggestion</ref></list>

+

+ Pre-computed suggestions for what every region might want to be

+ changed to.

+

+ </field>

+ </object>

+ </type>

+ <type name="LinkedEditSuggestion">

+

+ A suggestion of a value that could be used to replace all of the linked

+ edit regions in a <a href="#type_LinkedEditGroup">LinkedEditGroup</a>.

+

+ <object>

+ <field name="value">

+ <ref>String</ref>

+

+ The value that could be used to replace all of the linked edit

+ regions.

+

+ </field>

+ <field name="kind">

+ <ref>LinkedEditSuggestionKind</ref>

+

+ The kind of value being proposed.

+

+ </field>

+ </object>

+ </type>

+ <type name="LinkedEditSuggestionKind">

+

+ An enumeration of the kind of values that can be suggested for a linked

+ edit.

+

+ <enum>

+ <value><code>METHOD</code></value>

+ <value><code>PARAMETER</code></value>

+ <value><code>TYPE</code></value>

+ <value><code>VARIABLE</code></value>

+ </enum>

+ </type>

+ <type name="Location">

+

+ A location (character range) within a file.

+

+ <object>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the range.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the range.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the range.

+

+ </field>

+ <field name="startLine">

+ <ref>int</ref>

+

+ The one-based index of the line containing the first character of the

+ range.

+

+ </field>

+ <field name="startColumn">

+ <ref>int</ref>

+

+ The one-based index of the column containing the first character of

+ the range.

+

+ </field>

+ </object>

+ </type>

+ <type name="NavigationRegion">

+

+ A description of a region from which the user can navigate to the

+ declaration of an element.

+

+ <object>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region from which the user can navigate.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region from which the user can navigate.

+

+ </field>

+ <field name="targets">

+ <list><ref>int</ref></list>

+

+ The indexes of the targets (in the enclosing navigation response) to

+ which the given region is bound. By opening the target, clients can

+ implement one form of navigation. This list cannot be empty.

+

+ </field>

+ </object>

+ </type>

+ <type name="NavigationTarget">

+

+ A description of a target to which the user can navigate.

+

+ <object>

+ <field name="kind">

+ <ref>ElementKind</ref>

+

+ The kind of the element.

+

+ </field>

+ <field name="fileIndex">

+ <ref>int</ref>

+

+ The index of the file (in the enclosing navigation response) to

+ navigate to.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region to which the user can navigate.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region to which the user can navigate.

+

+ </field>

+ <field name="startLine">

+ <ref>int</ref>

+

+ The one-based index of the line containing the first character of the

+ region.

+

+ </field>

+ <field name="startColumn">

+ <ref>int</ref>

+

+ The one-based index of the column containing the first character of

+ the region.

+

+ </field>

+ </object>

+ </type>

+ <type name="Occurrences">

+

+ A description of the references to a single element within a single file.

+

+ <object>

+ <field name="element">

+ <ref>Element</ref>

+

+ The element that was referenced.

+

+ </field>

+ <field name="offsets">

+ <list><ref>int</ref></list>

+

+ The offsets of the name of the referenced element within the file.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the name of the referenced element.

+

+ </field>

+ </object>

+ </type>

+ <type name="Outline">

+

+ An node in the outline structure of a file.

+

+ <object>

+ <field name="element">

+ <ref>Element</ref>

+

+ A description of the element represented by this node.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the first character of the element. This is different

+ than the offset in the Element, which is the offset of the name of the

+ element. It can be used, for example, to map locations in the file

+ back to an outline.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the element.

+

+ </field>

+ <field name="children" optional="true">

+ <list><ref>Outline</ref></list>

+

+ The children of the node. The field will be omitted if the node has no

+ children.

+

+ </field>

+ </object>

+ </type>

+ <type name="Position">

+

+ A position within a file.

+

+ <object>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the position.

+

+ </field>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the position.

+

+ </field>

+ </object>

+ </type>

+ <type name="RefactoringFeedback">

+

+ An abstract superclass of all refactoring feedbacks.

+

+ <object>

+ </object>

+ </type>

+ <type name="RefactoringKind">

+

+ An enumeration of the kinds of refactorings that can be created.

+

+ <enum>

+ <value><code>CONVERT_GETTER_TO_METHOD</code></value>

+ <value><code>CONVERT_METHOD_TO_GETTER</code></value>

+ <value><code>EXTRACT_LOCAL_VARIABLE</code></value>

+ <value><code>EXTRACT_METHOD</code></value>

+ <value><code>INLINE_LOCAL_VARIABLE</code></value>

+ <value><code>INLINE_METHOD</code></value>

+ <value><code>MOVE_FILE</code></value>

+ <value><code>RENAME</code></value>

+ <value><code>SORT_MEMBERS</code></value>

+ </enum>

+ </type>

+ <type name="RefactoringMethodParameter">

+

+

+ A description of a parameter in a method refactoring.

+

+ <object>

+ <field name="id" optional="true">

+ <ref>String</ref>

+

+ The unique identifier of the parameter. Clients may omit this field

+ for the parameters they want to add.

+

+ </field>

+ <field name="kind">

+ <ref>RefactoringMethodParameterKind</ref>

+

+ The kind of the parameter.

+

+ </field>

+ <field name="type">

+ <ref>String</ref>

+

+ The type that should be given to the parameter, or the return type of

+ the parameter's function type.

+

+ </field>

+ <field name="name">

+ <ref>String</ref>

+

+ The name that should be given to the parameter.

+

+ </field>

+ <field name="parameters" optional="true">

+ <ref>String</ref>

+

+ The parameter list of the parameter's function type. If the parameter

+ is not of a function type, this field will not be defined. If the

+ function type has zero parameters, this field will have a value of

+ '()'.

+

+ </field>

+ </object>

+ </type>

+ <type name="RefactoringOptions">

+

+ An abstract superclass of all refactoring options.

+

+ <object>

+ </object>

+ </type>

+ <type name="RefactoringMethodParameterKind">

+

+ An enumeration of the kinds of parameters.

+

+ <enum>

+ <value><code>REQUIRED</code></value>

+ <value><code>POSITIONAL</code></value>

+ <value><code>NAMED</code></value>

+ </enum>

+ </type>

+ <type name="RefactoringProblem">

+

+ A description of a problem related to a refactoring.

+

+ <object>

+ <field name="severity">

+ <ref>RefactoringProblemSeverity</ref>

+

+ The severity of the problem being represented.

+

+ </field>

+ <field name="message">

+ <ref>String</ref>

+

+ A human-readable description of the problem being represented.

+

+ </field>

+ <field name="location" optional="true">

+ <ref>Location</ref>

+

+ The location of the problem being represented. This field is omitted

+ unless there is a specific location associated with the problem (such

+ as a location where an element being renamed will be shadowed).

+

+ </field>

+ </object>

+ </type>

+ <type name="RefactoringProblemSeverity">

+

+ An enumeration of the severities of problems that can be returned by the

+ refactoring requests.

+

+ <enum>

+ <value>

+ <code>INFO</code>

+

+ A minor code problem. No example, because it is not used yet.

+

+ </value>

+ <value>

+ <code>WARNING</code>

+

+ A minor code problem. For example names of local variables should be

+ camel case and start with a lower case letter. Staring the name of a

+ variable with an upper case is OK from the language point of view, but

+ it is nice to warn the user.

+

+ </value>

+ <value>

+ <code>ERROR</code>

+

+ The refactoring technically can be performed, but there is a logical

+ problem. For example the name of a local variable being extracted

+ conflicts with another name in the scope, or duplicate parameter names

+ in the method being extracted, or a conflict between a parameter name

+ and a local variable, etc. In some cases the location of the problem

+ is also provided, so the IDE can show user the location and the

+ problem, and let the user decide whether they want to perform the

+ refactoring. For example the name conflict might be expected, and the

+ user wants to fix it afterwards.

+

+ </value>

+ <value>

+ <code>FATAL</code>

+

+ A fatal error, which prevents performing the refactoring. For example

+ the name of a local variable being extracted is not a valid

+ identifier, or selection is not a valid expression.

+

+ </value>

+ </enum>

+ </type>

+ <type name="RemoveContentOverlay">

+

+ A directive to remove an existing file content overlay. After processing

+ this directive, the file contents will once again be read from the file

+ system.

+

+

+ If this directive is used on a file that doesn't currently have a content

+ overlay, it has no effect.

+

+ <object>

+ <field name="type" value="remove"><ref>String</ref></field>

+ </object>

+ </type>

+ <type name="RequestError">

+

+ An indication of a problem with the execution of the server,

+ typically in response to a request.

+

+ <object>

+ <field name="code">

+ <ref>RequestErrorCode</ref>

+

+ A code that uniquely identifies the error that occurred.

+

+ </field>

+ <field name="message">

+ <ref>String</ref>

+

+ A short description of the error.

+

+ </field>

+ <field name="stackTrace" optional="true">

+ <ref>String</ref>

+

+ The stack trace associated with processing the request, used for

+ debugging the plugin.

+

+ </field>

+ </object>

+ </type>

+ <type name="RequestErrorCode">

+

+ An enumeration of the types of errors that can occur in the execution of

+ the plugin.

+

+ <enum>

+ <value>

+ <code>INVALID_OVERLAY_CHANGE</code>

+

+ An "analysis.updateContent" request contained a

+ <a href="#type_ChangeContentOverlay">ChangeContentOverlay</a> object

+ that can't be applied. This can happen for two reasons:

+

+ <ul>

+ <li>

+ there was no preceding

+ <a href="#type_AddContentOverlay">AddContentOverlay</a> and hence no

+ content to which the edits could be applied, or

+ </li>

+ <li>

+ one or more of the specified edits have an offset or length that is

+ out of range.

+ </li>

+ </ul>

+ </value>

+ <value>

+ <code>INVALID_PARAMETER</code>

+

+ One of the method parameters was invalid.

+

+ </value>

+ <value>

+ <code>PLUGIN_ERROR</code>

+

+ An internal error occurred in the plugin while attempting to respond

+ to a request. Also see the plugin.error notification for errors that

+ occur outside of handling a request.

+

+ </value>

+ <value>

+ <code>UNKNOWN_REQUEST</code>

+

+ A request was received that the plugin does not recognize, or cannot

+ handle in its current configuration.

+

+ </value>

+ <!--

+ <value>

+ <code>CONTENT_MODIFIED</code>

+

+ An "analysis.getErrors" or "analysis.getNavigation" request could

+ not be satisfied because the content of the file changed before

+ the requested results could be computed.

+

+ </value>

+ <value>

+ <code>FILE_NOT_ANALYZED</code>

+

+ A request specified a FilePath which does not match a file in

+ an analysis root, or the requested operation is not available

+ for the file.

+

+ </value>

+ <value>

+ <code>FORMAT_WITH_ERRORS</code>

+

+ An "edit.format" request specified a file that contains syntax

+ errors.

+

+ </value>

+ <value>

+ <code>GET_ERRORS_INVALID_FILE</code>

+

+ An "analysis.getErrors" request specified a FilePath

+ which does not match a file currently subject to

+ analysis.

+

+ </value>

+ <value>

+ <code>GET_NAVIGATION_INVALID_FILE</code>

+

+ An "analysis.getNavigation" request specified a FilePath

+ which does not match a file currently subject to

+ analysis.

+

+ </value>

+ <value>

+ <code>GET_REACHABLE_SOURCES_INVALID_FILE</code>

+

+ An "analysis.getReachableSources" request specified a FilePath

+ which does not match a file currently subject to

+ analysis.

+

+ </value>

+ <value>

+ <code>INVALID_ANALYSIS_ROOT</code>

+

+ A path passed as an argument to a request (such as

+ analysis.reanalyze) is required to be an analysis root, but isn't.

+

+ </value>

+ <value>

+ <code>INVALID_EXECUTION_CONTEXT</code>

+

+ The context root used to create an execution context does not

+ exist.

+

+ </value>

+ <value>

+ <code>INVALID_FILE_PATH_FORMAT</code>

+

+ The format of the given file path is invalid, that is, it is not

+ absolute and normalized.

+

+ </value>

+ <value>

+ <code>INVALID_REQUEST</code>

+

+ A malformed request was received.

+

+ </value>

+ <value>

+ <code>REFACTORING_REQUEST_CANCELLED</code>

+

+ Another refactoring request was received during processing of

+ this one.

+

+ </value>

+ <value>

+ <code>UNANALYZED_PRIORITY_FILES</code>

+

+ An "analysis.setPriorityFiles" request includes one or

+ more files that are not being analyzed.

+

+

+ This is a legacy error; it will be removed before the

+ API reaches version 1.0.

+

+ </value>

+ <value>

+ <code>UNKNOWN_SOURCE</code>

+

+ The analysis server was requested to perform an action

+ on a source that does not exist.

+

+ </value>

+ <value>

+ <code>UNSUPPORTED_FEATURE</code>

+

+ The plugin received a requested to perform an action that is not

+ supported.

+

+ </value>

+ -->

+ </enum>

+ </type>

+ <type name="SourceChange">

+

+ A description of a set of edits that implement a single conceptual change.

+

+ <object>

+ <field name="message">

+ <ref>String</ref>

+

+ A human-readable description of the change to be applied.

+

+ </field>

+ <field name="edits">

+ <list><ref>SourceFileEdit</ref></list>

+

+ A list of the edits used to effect the change, grouped by file.

+

+ </field>

+ <field name="linkedEditGroups">

+ <list><ref>LinkedEditGroup</ref></list>

+

+ A list of the linked editing groups used to customize the changes that

+ were made.

+

+ </field>

+ <field name="selection" optional="true">

+ <ref>Position</ref>

+

+ The position that should be selected after the edits have been

+ applied.

+

+ </field>

+ </object>

+ </type>

+ <type name="SourceEdit">

+

+ A description of a single change to a single file.

+

+ <object>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset of the region to be modified.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the region to be modified.

+

+ </field>

+ <field name="replacement">

+ <ref>String</ref>

+

+ The code that is to replace the specified region in the original code.

+

+ </field>

+ <field name="id" optional="true">

+ <ref>String</ref>

+

+ An identifier that uniquely identifies this source edit from other

+ edits in the same response. This field is omitted unless a containing

+ structure needs to be able to identify the edit for some reason.

+

+

+ For example, some refactoring operations can produce edits that might

+ not be appropriate (referred to as potential edits). Such edits will

+ have an id so that they can be referenced. Edits in the same response

+ that do not need to be referenced will not have an id.

+

+ </field>

+ </object>

+ </type>

+ <type name="SourceFileEdit">

+

+ A description of a set of changes to a single file.

+

+ <object>

+ <field name="file">

+ <ref>FilePath</ref>

+

+ The file containing the code to be modified.

+

+ </field>

+ <field name="fileStamp">

+ <ref>long</ref>

+

+ The modification stamp of the file at the moment when the change was

+ created, in milliseconds since the "Unix epoch". Will be -1 if the

+ file did not exist and should be created. The client may use this

+ field to make sure that the file was not changed since then, so it is

+ safe to apply the change.

+

+ </field>

+ <field name="edits">

+ <list><ref>SourceEdit</ref></list>

+

+ A list of the edits used to effect the change.

+

+ </field>

+ </object>

+ </type>

+ <type name="WatchEvent">

+

+ A watch event sent by the server when the file system has been modified.

+

+ <object>

+ <field name="type">

+ <ref>WatchEventType</ref>

+

+ The type of change represented by this event.

+

+ </field>

+ <field name="path">

+ <ref>String</ref>

+

+ The absolute path of the file or directory that changed.

+

+ </field>

+ </object>

+ </type>

+ <type name="WatchEventType">

+

+ An indication of the type of change associated with a watch event.

+

+ <enum>

+ <value>

+ <code>ADD</code>

+

+ An indication that the file or directory was added.

+

+ </value>

+ <value>

+ <code>MODIFY</code>

+

+ An indication that the file was modified.

+

+ </value>

+ <value>

+ <code>REMOVE</code>

+

+ An indication that the file or directory was removed.

+

+ </value>

+ </enum>

+ </type>

+</types>

+<refactorings>

+ <h2><a name="refactorings">Refactorings</a></h2>

+

+ This section contains additional information for each kind of refactoring.

+ In addition to a brief description of the refactoring, there is a

+ specification of the feedback that is provided when a refactoring is

+ requested using the

+ <a href="request_edit.getRefactoring">edit.getRefactoring</a> request

+ (designed to improve the UX) and the options that may be provided to

+ <a href="request_edit.getRefactoring">edit.getRefactoring</a>.

+

+ <refactoring kind="CONVERT_GETTER_TO_METHOD">

+

+ Convert a getter into a method by removing the keyword get and adding an

+ empty parameter list.

+

+

+ It is an error if the range contains anything other than all or part of

+ the name of a single getter.

+

+ </refactoring>

+ <refactoring kind="CONVERT_METHOD_TO_GETTER">

+

+ Convert a method into a getter by adding the keyword get and removing the

+ parameter list.

+

+

+ It is an error if the range contains anything other than all or part of

+ the name of a single method or if the method has a non-empty parameter

+ list.

+

+ </refactoring>

+ <refactoring kind="EXTRACT_LOCAL_VARIABLE">

+

+ Create a local variable initialized by the expression that covers the

+ specified selection.

+

+

+ It is an error if the selection range is not covered by a complete

+ expression.

+

+ <feedback>

+ <field name="coveringExpressionOffsets" optional="true">

+ <list><ref>int</ref></list>

+

+ The offsets of the expressions that cover the specified selection,

+ from the down most to the up most.

+

+ </field>

+ <field name="coveringExpressionLengths" optional="true">

+ <list><ref>int</ref></list>

+

+ The lengths of the expressions that cover the specified selection,

+ from the down most to the up most.

+

+ </field>

+ <field name="names">

+ <list><ref>String</ref></list>

+

+ The proposed names for the local variable.

+

+ </field>

+ <field name="offsets">

+ <list><ref>int</ref></list>

+

+ The offsets of the expressions that would be replaced by a reference

+ to the variable.

+

+ </field>

+ <field name="lengths">

+ <list><ref>int</ref></list>

+

+ The lengths of the expressions that would be replaced by a reference

+ to the variable. The lengths correspond to the offsets. In other

+ words, for a given expression, if the offset of that expression is

+ offsets[i], then the length of that expression is lengths[i].

+

+ </field>

+ </feedback>

+ <options>

+ <field name="name">

+ <ref>String</ref>

+

+ The name that the local variable should be given.

+

+ </field>

+ <field name="extractAll">

+ <ref>bool</ref>

+

+ True if all occurrences of the expression within the scope in which

+ the variable will be defined should be replaced by a reference to the

+ local variable. The expression used to initiate the refactoring will

+ always be replaced.

+

+ </field>

+ </options>

+ </refactoring>

+ <refactoring kind="EXTRACT_METHOD">

+

+ Create a method whose body is the specified expression or list of

+ statements, possibly augmented with a return statement.

+

+

+ It is an error if the range contains anything other than a complete

+ expression (no partial expressions are allowed) or a complete sequence of

+ statements.

+

+ <feedback>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset to the beginning of the expression or statements that will

+ be extracted.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the expression or statements that will be extracted.

+

+ </field>

+ <field name="returnType">

+ <ref>String</ref>

+

+ The proposed return type for the method. If the returned element does

+ not have a declared return type, this field will contain an empty

+ string.

+

+ </field>

+ <field name="names">

+ <list><ref>String</ref></list>

+

+ The proposed names for the method.

+

+ </field>

+ <field name="canCreateGetter">

+ <ref>bool</ref>

+

+ True if a getter could be created rather than a method.

+

+ </field>

+ <field name="parameters">

+ <list><ref>RefactoringMethodParameter</ref></list>

+

+ The proposed parameters for the method.

+

+ </field>

+ <field name="offsets">

+ <list><ref>int</ref></list>

+

+ The offsets of the expressions or statements that would be replaced by

+ an invocation of the method.

+

+ </field>

+ <field name="lengths">

+ <list><ref>int</ref></list>

+

+ The lengths of the expressions or statements that would be replaced by

+ an invocation of the method. The lengths correspond to the offsets. In

+ other words, for a given expression (or block of statements), if the

+ offset of that expression is offsets[i], then the length of that

+ expression is lengths[i].

+

+ </field>

+ </feedback>

+ <options>

+ <field name="returnType">

+ <ref>String</ref>

+

+ The return type that should be defined for the method.

+

+ </field>

+ <field name="createGetter">

+ <ref>bool</ref>

+

+ True if a getter should be created rather than a method. It is an

+ error if this field is true and the list of parameters is non-empty.

+

+ </field>

+ <field name="name">

+ <ref>String</ref>

+

+ The name that the method should be given.

+

+ </field>

+ <field name="parameters">

+ <list><ref>RefactoringMethodParameter</ref></list>

+

+ The parameters that should be defined for the method.

+

+

+ It is an error if a REQUIRED or NAMED parameter follows a POSITIONAL

+ parameter. It is an error if a REQUIRED or POSITIONAL parameter

+ follows a NAMED parameter.

+

+ <ul>

+ <li>

+ To change the order and/or update proposed parameters, add

+ parameters with the same identifiers as proposed.

+ </li>

+ <li>

+ To add new parameters, omit their identifier.

+ </li>

+ <li>

+ To remove some parameters, omit them in this list.

+ </li>

+ </ul>

+ </field>

+ <field name="extractAll">

+ <ref>bool</ref>

+

+ True if all occurrences of the expression or statements should be

+ replaced by an invocation of the method. The expression or statements

+ used to initiate the refactoring will always be replaced.

+

+ </field>

+ </options>

+ </refactoring>

+ <refactoring kind="INLINE_LOCAL_VARIABLE">

+

+ Inline the initializer expression of a local variable in place of any

+ references to that variable.

+

+

+ It is an error if the range contains anything other than all or part of

+ the name of a single local variable.

+

+ <feedback>

+ <field name="name">

+ <ref>String</ref>

+

+ The name of the variable being inlined.

+

+ </field>

+ <field name="occurrences">

+ <ref>int</ref>

+

+ The number of times the variable occurs.

+

+ </field>

+ </feedback>

+ </refactoring>

+ <refactoring kind="INLINE_METHOD">

+

+ Inline a method in place of one or all references to that method.

+

+

+ It is an error if the range contains anything other than all or part of

+ the name of a single method.

+

+ <feedback>

+ <field name="className" optional="true">

+ <ref>String</ref>

+

+ The name of the class enclosing the method being inlined. If not a

+ class member is being inlined, this field will be absent.

+

+ </field>

+ <field name="methodName">

+ <ref>String</ref>

+

+ The name of the method (or function) being inlined.

+

+ </field>

+ <field name="isDeclaration">

+ <ref>bool</ref>

+

+ True if the declaration of the method is selected and all references

+ should be inlined.

+

+ </field>

+ </feedback>

+ <options>

+ <field name="deleteSource">

+ <ref>bool</ref>

+

+ True if the method being inlined should be removed. It is an error if

+ this field is true and inlineAll is false.

+

+ </field>

+ <field name="inlineAll">

+ <ref>bool</ref>

+

+ True if all invocations of the method should be inlined, or false if

+ only the invocation site used to create this refactoring should be

+ inlined.

+

+ </field>

+ </options>

+ </refactoring>

+ <refactoring kind="MOVE_FILE">

+

+ Move the given file and update all of the references to that file and from

+ it. The move operation is supported in general case - for renaming a file

+ in the same folder, moving it to a different folder or both.

+

+

+ The refactoring must be activated before an actual file moving operation

+ is performed.

+

+

+ The "offset" and "length" fields from the request are ignored, but the

+ file specified in the request specifies the file to be moved.

+

+ <options>

+ <field name="newFile">

+ <ref>FilePath</ref>

+

+ The new file path to which the given file is being moved.

+

+ </field>

+ </options>

+ </refactoring>

+ <refactoring kind="RENAME">

+

+ Rename a given element and all of the references to that element.

+

+

+ It is an error if the range contains anything other than all or part of

+ the name of a single function (including methods, getters and setters),

+ variable (including fields, parameters and local variables), class or

+ function type.

+

+ <feedback>

+ <field name="offset">

+ <ref>int</ref>

+

+ The offset to the beginning of the name selected to be renamed.

+

+ </field>

+ <field name="length">

+ <ref>int</ref>

+

+ The length of the name selected to be renamed.

+

+ </field>

+ <field name="elementKindName">

+ <ref>String</ref>

+

+ The human-readable description of the kind of element being renamed

+ (such as “class” or “function type alias”).

+

+ </field>

+ <field name="oldName">

+ <ref>String</ref>

+

+ The old name of the element before the refactoring.

+

+ </field>

+ </feedback>

+ <options>

+ <field name="newName">

+ <ref>String</ref>

+

+ The name that the element should have after the refactoring.

+

+ </field>

+ </options>

+ </refactoring>

+</refactorings>

+<h2 class="domain"><a name="index">Index</a></h2>

+<index></index>

+</body>

+</html>

« no previous file with comments | « pkg/analyzer_plugin/tool/spec/implied_types.dart ('k') | pkg/analyzer_plugin/tool/spec/to_html.dart » ('j') | no next file with comments »