← Back to branch summary

~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

« back to all changes in this revision

Viewing changes to src/addins/MonoDevelop.Refactoring/MonoDevelop.AnalysisCore/README.txt

  • Committer: Package Import Robot
  • Author(s): Jo Shields
  • Date: 2013-05-12 09:46:03 UTC
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20130512094603-mad323bzcxvmcam0
Tags: upstream-4.0.5+dfsg
Import upstream version 4.0.5+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/addins/MonoDevelop.Refactoring/MonoDevelop.AnalysisCore/README.txt
 
1
AnalysisCore currently provides several services -
 
2
 
 
3
* The AnalysisService, a service for analyzing arbitrary input objects 
 
4
  based on extensible rules.
 
5
  
 
6
* a TextEditorExtension that uses the AnalysisService to process the
 
7
  editor's ParsedDocument when it's updated by the ProjectDomService,
 
8
  and shows any resulting errors or warnings as underlines in the editor.
 
9
 
 
10
== The AnalysisService ==
 
11
 
 
12
AnalysisService is fundamentally based on the idea of an "Analyzer tree". 
 
13
This is a tree where each node contains a "rule". Each rule is a Func<T,TRet>
 
14
that transforms an input object to an output object. The tree is constructed 
 
15
in such a way that the output type of each node's rule matches the input type 
 
16
of its children, and leaf nodes always output IEnumerable<Result>. Thus, when
 
17
Analyze (someInputObject) is called on the root node, the intermediates 
 
18
objects propagate down the tree, and the Results are aggregated and returned.
 
19
 
 
20
The trees are constructed based on rule nodes registered in the addin file. 
 
21
Each node had an input and output "type", which is a string alias for a real 
 
22
CLR type. Multiple aliases can be registered for one real type - the aliases 
 
23
specify how the rule nodes can be connected, and the CLR types simply allow
 
24
strongly typing the rule functions.
 
25
 
 
26
== Extension Points ==
 
27
 
 
28
The is an extension point "/MonoDevelop/AnalysisCore/Type" where type aliases 
 
29
must be registered before use. Although aliases may only be registered once, 
 
30
they may be used by any number of rules.
 
31
 
 
32
There are two kinds of rule extension nodes, <Adaptor> and <Rule>. Both may be
 
33
registered at the same extension point, "/MonoDevelop/AnalysisCore/Rules". 
 
34
Both kinds of node must specify an input alias and a function name, which
 
35
must correspond to a static method in the addin assembly. The static method's
 
36
argument and return type must match the CLR types to which the input and 
 
37
output aliases map.
 
38
 
 
39
== Rules ==
 
40
 
 
41
Rules always have an implicit output type of "Results", which is the built-in 
 
42
alias for IEnumerable<Result>, and they also have a user-readable, localizable 
 
43
name value, so that they may be displayed in UI for configuring which rules 
 
44
are enabled.
 
45
 
 
46
== Adaptors ==
 
47
 
 
48
Adaptors must specify an output type, but are not user-visible so are not named.
 
49
Their purpose is to do processing work that can be shared by multiple rules - 
 
50
for example, an adaptor can generate a special type that is known to several 
 
51
rules and includes additional preprocessing result, so that the rules so not 
 
52
have to repeat the work. Adaptors may also be used to map input types to types 
 
53
that are known by existing rules - for example, an adaptor could process the 
 
54
output of the ASP.NET parser to prodice input known to existing C# rules.
 
55
Adaptors may also be used to make branches conditional - if they output null, 
 
56
then none of their children will be executed.
 
57
 
 
58
When building the tree, the possible extension nodes used are filtered using
 
59
optional filenames on the extension nodes. If an adaptor is filtered out, 
 
60
then none of the nodes that consume its output can be used, so they need not 
 
61
be filtered explicitly. For example, if there were an adaptor that cast an
 
62
ICompilationUnit input to a CSharpCompilationUnit output, then it should be 
 
63
filtered on the .cs file extension, and any rules with a CSharpCompilationUnit
 
64
input would not be used.
 
65
 
 
66
Adaptors can produce more than one output quite easily. If the outputs are
 
67
a collection, then simply make the collection type the output type. If there
 
68
are several different output objects, they can be aggregated on properties of
 
69
a new type which can be used as the output type. Consumers may consume this
 
70
type directly, or multiple additional adaptor rules may be used to pick off 
 
71
the individual objects.
 
 
b'\\ No newline at end of file'