From d111f58db624778f543716e7ac5bd348e7da54d2 Mon Sep 17 00:00:00 2001 From: Amit Choudhary Date: Mon, 21 Sep 2015 16:24:31 -0400 Subject: [PATCH 1/2] Initial update (In-Progress) for ReadMe.md --- README => README.md | 142 +++++++++++++++++++++----------------------- 1 file changed, 69 insertions(+), 73 deletions(-) rename README => README.md (65%) diff --git a/README b/README.md similarity index 65% rename from README rename to README.md index 5fcaf41b5..cf9877261 100644 --- a/README +++ b/README.md @@ -1,67 +1,62 @@ -Overview of the NRefactory library: - -Introductory documentation: - http://www.codeproject.com/Articles/408663/Using-NRefactory-for-analyzing-Csharp-code - -How to download: - - Binaries are provided as a NuGet package (http://nuget.org/packages/ICSharpCode.NRefactory) - - Sourcecode is available on GitHub (https://github.com/icsharpcode/NRefactory) - -How to compile: - 1. Get Mono.Cecil - Get Cecil from https://github.com/jbevain/cecil ('git clone git://github.com/jbevain/cecil.git') - or download Cecil from https://github.com/jbevain/cecil/ and unzip it into a directory named "cecil" - next to the directory containing NRefactory. - 2. If you need the IKVM binding get it from https://github.com/mono/ikvm-fork and put it next to the NRefactory directory - like Mono.Cecil - name it "ikvm". - 3. Open NRefactory.sln in your favorite .NET IDE and compile. - -Features: - - C# Parser - - Abstract Syntax Tree with pattern-matching support - - Semantic Analysis for C# (supports C# 5.0) - - Code Completion for C# - - Pretty Printer for C# - - Lots of C# refactorings - -Non-Features: - - VB support is not implemented yet. - - NRefactory cannot generate IL code -- it's a compiler frontend, not a full compiler - -Dependencies: - .NET 4.0 - Mono.Cecil 0.9.5 - NRefactory contains a modified copy of mcs (Mono's C# compiler) for the C# parser. - - -Namespace overview: - -ICSharpCode.NRefactory assembly - ICSharpCode.NRefactory.Editor: - Interfaces that abstract from the text editor control used. +# Overview of the NRefactory library + +### Introductory documentation +>[Documentation on CodeProject](http://www.codeproject.com/Articles/408663/Using-NRefactory-for-analyzing-Csharp-code) + +### How to download +- Binaries are provided as a [NuGet package](http://nuget.org/packages/ICSharpCode.NRefactory, NRefactory Nuget) +- Sourcecode is available on [GitHub respository](https://github.com/icsharpcode/NRefactory, github repository of NRefactory) + +### How to compile: +1. [Get Mono.Cecil](https://github.com/jbevain/cecil, 'git clone git://github.com/jbevain/cecil.git') +or [Download Cecil](https://github.com/jbevain/cecil/) and unzip it into a directory named "cecil" +next to the directory containing NRefactory. +2. If you need the IKVM binding [get it](https://github.com/mono/ikvm-fork, 'download ikvm fork') and put it next to the NRefactory directory like Mono.Cecil - name it "ikvm". +3. Open NRefactory.sln in your favorite .NET IDE and compile. + +#### Features +- C# Parser +- Abstract Syntax Tree with pattern-matching support +- Semantic Analysis for C# (supports C# 5.0) +- Code Completion for C# +- Pretty Printer for C# +- Lots of C# refactorings + +#### Non-Features +- VB support is not implemented yet. +- NRefactory cannot generate IL code -- it's a compiler frontend, not a full compiler + +#### Dependencies +- .NET 4.0 +- Mono.Cecil 0.9.5 +- NRefactory contains a modified copy of mcs (Mono's C# compiler) for the C# parser. + + +### Namespace overview + +**ICSharpCode.NRefactory assembly** + + *ICSharpCode.NRefactory.Editor*: Interfaces that abstract from the text editor control used. Maybe future AvalonEdit versions will directly implement these interfaces, but you could also write adapters for other editors. - ICSharpCode.NRefactory.TypeSystem: - Contains a language-independent representation of the .NET type system. - The type system is divided into two portions: unresolved and resolved type systems. +*ICSharpCode.NRefactory.TypeSystem*: Contains a language-independent representation of the .NET type system. +The type system is divided into two portions: unresolved and resolved type systems. - ICSharpCode.NRefactory.TypeSystem.Implementation: - Contains default implementations for the type system interfaces. +..* *ICSharpCode.NRefactory.TypeSystem.Implementation*: Contains default implementations for the type system interfaces. - ICSharpCode.NRefactory.Semantics: - Contains classes (ResolveResults) used to represent the semantics of a language element. - ResolveResults can have child results, thus forming semantic trees. +..* *ICSharpCode.NRefactory.Semantics*: Contains classes (ResolveResults) used to represent the semantics of a language element. +...ResolveResults can have child results, thus forming semantic trees. - ICSharpCode.NRefactory.Documentation: - Classes for working with .xml documentation files. - See "doc/XML Documentation.html" for details. +..* *ICSharpCode.NRefactory.Documentation*: +...Classes for working with .xml documentation files. +...See "doc/XML Documentation.html" for details. - ICSharpCode.NRefactory.PatternMatching: - Provides classes for pattern matching over the C# and VB ASTs. - See "doc/Pattern Matching.html" for details. +..* *ICSharpCode.NRefactory.PatternMatching*: +...Provides classes for pattern matching over the C# and VB ASTs. +...See "doc/Pattern Matching.html" for details. - ICSharpCode.NRefactory.Util: - Various helper classes. +..* *ICSharpCode.NRefactory.Util*: +...Various helper classes. ICSharpCode.NRefactory.CSharp assembly @@ -117,22 +112,23 @@ Null-Object pattern: child node with that role exists. Check the IsNull property to test whether a node is a null node. Null nodes are not considered to be part of the AST (e.g. they don't have a parent). -FAQ: -Q: What is the difference between NRefactory and Roslyn? - - NRefactory is ready and stable, Roslyn is only a CTP at this point of time. - - NRefactory does not have VB support. - - NRefactory cannot compile code to IL; it's not a full compiler, just a frontend. - - NRefactory C# AST is mutable and supports pattern matching; Roslyn is immutable and does not have built-in pattern matching. - -Q: What is the difference between types and type definitions? - -A: Basically, a type (IType) is any type in the .NET type system: - - an array (ArrayType) - - a pointer (PointerType) - - a managed reference (ByReferenceType) - - a parameterized type (ParameterizedType, e.g. List) - - a type parameter (ITypeParameter, e.g. T) - - or a type definition (ITypeDefiniton) +#### FAQ: +**Q: What is the difference between NRefactory and Roslyn?** + +- NRefactory is ready and stable, Roslyn is only a CTP at this point of time. +- NRefactory does not have VB support. +- NRefactory cannot compile code to IL; it's not a full compiler, just a frontend. +- NRefactory C# AST is mutable and supports pattern matching; Roslyn is immutable and does not have built-in pattern matching. + +**Q: What is the difference between types and type definitions?** + +**A:** Basically, a type (IType) is any type in the .NET type system: +- an array (ArrayType) +- a pointer (PointerType) +- a managed reference (ByReferenceType) +- a parameterized type (ParameterizedType, e.g. List) +- a type parameter (ITypeParameter, e.g. T) +- or a type definition (ITypeDefiniton) Type definitions are only classes, structs, enums and delegates. Every type definition is a type, but not every type is a type definition. From 63ca6b99963a1debda279eb38fa9690ab0925937 Mon Sep 17 00:00:00 2001 From: Amit Choudhary Date: Mon, 21 Sep 2015 17:17:49 -0400 Subject: [PATCH 2/2] Updated Readme.md with markdown to increase the readability. --- README.md | 233 +++++++++++++++++++++++------------------------------- 1 file changed, 100 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index cf9877261..d22493ffc 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # Overview of the NRefactory library ### Introductory documentation ->[Documentation on CodeProject](http://www.codeproject.com/Articles/408663/Using-NRefactory-for-analyzing-Csharp-code) +[Documentation on CodeProject](http://www.codeproject.com/Articles/408663/Using-NRefactory-for-analyzing-Csharp-code) -### How to download -- Binaries are provided as a [NuGet package](http://nuget.org/packages/ICSharpCode.NRefactory, NRefactory Nuget) -- Sourcecode is available on [GitHub respository](https://github.com/icsharpcode/NRefactory, github repository of NRefactory) +#### How to download +- Binaries are provided as a [NuGet package](http://nuget.org/packages/ICSharpCode.NRefactory, NRefactory Nuget). +- Sourcecode is available on [GitHub respository](https://github.com/icsharpcode/NRefactory, github repository of NRefactory). -### How to compile: +#### How to compile: 1. [Get Mono.Cecil](https://github.com/jbevain/cecil, 'git clone git://github.com/jbevain/cecil.git') or [Download Cecil](https://github.com/jbevain/cecil/) and unzip it into a directory named "cecil" next to the directory containing NRefactory. @@ -32,97 +32,86 @@ next to the directory containing NRefactory. - NRefactory contains a modified copy of mcs (Mono's C# compiler) for the C# parser. -### Namespace overview +Namespace overview +---- +>**ICSharpCode.NRefactory assembly** -**ICSharpCode.NRefactory assembly** + *`ICSharpCode.NRefactory.Editor`* - *ICSharpCode.NRefactory.Editor*: Interfaces that abstract from the text editor control used. +Interfaces that abstract from the text editor control used. Maybe future AvalonEdit versions will directly implement these interfaces, but you could also write adapters for other editors. -*ICSharpCode.NRefactory.TypeSystem*: Contains a language-independent representation of the .NET type system. -The type system is divided into two portions: unresolved and resolved type systems. +*`ICSharpCode.NRefactory.TypeSystem`* + +Contains a language-independent representation of the .NET type system. +The type system is divided into two portions: **unresolved** and **resolved** type systems. -..* *ICSharpCode.NRefactory.TypeSystem.Implementation*: Contains default implementations for the type system interfaces. + * _`ICSharpCode.NRefactory.TypeSystem.Implementation`_ - Contains default implementations for the type system interfaces. -..* *ICSharpCode.NRefactory.Semantics*: Contains classes (ResolveResults) used to represent the semantics of a language element. -...ResolveResults can have child results, thus forming semantic trees. + * _`ICSharpCode.NRefactory.Semantics`_ - Contains classes (ResolveResults) used to represent the semantics of a language element.ResolveResults can have child results, thus forming semantic trees. -..* *ICSharpCode.NRefactory.Documentation*: -...Classes for working with .xml documentation files. -...See "doc/XML Documentation.html" for details. + * _`ICSharpCode.NRefactory.Documentation`_ - Classes for working with .xml documentation files. + See "doc/XML Documentation.html" for details. -..* *ICSharpCode.NRefactory.PatternMatching*: -...Provides classes for pattern matching over the C# and VB ASTs. -...See "doc/Pattern Matching.html" for details. + * _`ICSharpCode.NRefactory.PatternMatching`_ - Provides classes for pattern matching over the C# and VB ASTs. + See "doc/Pattern Matching.html" for details. -..* *ICSharpCode.NRefactory.Util*: -...Various helper classes. + * _`ICSharpCode.NRefactory.Util`_ - Various helper classes. + +>**ICSharpCode.NRefactory.CSharp assembly** -ICSharpCode.NRefactory.CSharp assembly - ICSharpCode.NRefactory.CSharp: - Abstract Syntax Tree for C# + * _`ICSharpCode.NRefactory.CSharp`_ - Abstract Syntax Tree for C# - ICSharpCode.NRefactory.CSharp.Completion: - Code completion (IntelliSense) for C# + * _`ICSharpCode.NRefactory.CSharp.Completion`_ - Code completion (IntelliSense) for C# - ICSharpCode.NRefactory.CSharp.Resolver: - Semantic analysis for C# (resolving the meaning of expressions) + * _`ICSharpCode.NRefactory.CSharp.Resolver`_ - Semantic analysis for C# (resolving the meaning of expressions) - ICSharpCode.NRefactory.CSharp.Analysis: - Semantic analysis for C# (additional analysis functionality) + * _`ICSharpCode.NRefactory.CSharp.Analysis`_ - Semantic analysis for C# (additional analysis functionality) - ICSharpCode.NRefactory.CSharp.TypeSystem: - Contains type system implementations specific to C#. + * _`ICSharpCode.NRefactory.CSharp.TypeSystem`_ - Contains type system implementations specific to C#. - ICSharpCode.NRefactory.CSharp.Refactoring: - Infrastructure for refactorings; and several built-in refactorings. + * _`ICSharpCode.NRefactory.CSharp.Refactoring`_ - Infrastructure for refactorings; and several built-in refactorings. + +>**ICSharpCode.NRefactory.VB assembly** -ICSharpCode.NRefactory.VB assembly - ICSharpCode.NRefactory.VB: - Abstract Syntax Tree for VB +* _`ICSharpCode.NRefactory.VB`_ - Abstract Syntax Tree for VB -ICSharpCode.NRefactory.Xml assembly - ICSharpCode.NRefactory.Xml: - Error-tolerant XML parser. Supports incremental parsing. - When tags don't match correctly, the parser uses a heuristic to guess the parse tree. - The heuristic tries to minimize the edit distance from the erroneous document to - the fixed document, and it also considers the indentation. +>**ICSharpCode.NRefactory.Xml assembly** +* _`ICSharpCode.NRefactory.Xml`_ - Error-tolerant XML parser. Supports incremental parsing. +When tags don't match correctly, the parser uses a heuristic to guess the parse tree. The heuristic tries to minimize the edit distance from the erroneous document to the fixed document, and it also considers the indentation. -Null-Object pattern: +>**Null-Object pattern** - The NRefactory library makes extensive use of the null object pattern. - As a result, NullReferenceExceptions should be very rare when working with this library. - In the type system, both ITypeReference and IType use SpecialType.UnknownType to represent - unknown types. - Unless the XML documentation says otherwise, no method or property returning a ITypeReference - or IType will return null. - - Note that the null object pattern is not used for ITypeDefinition: - IProjectContent.GetClass() returns null when a type is not found. Take care to abort your - operation or substitute UnknownType instead of passing the null to code expecting an IType. - - The pattern also extends to the C# resolver, which always produces a ResolveResult, even in - error cases. Use ResolveResult.IsError to detect resolver errors. - Also note that many resolver errors still have a meaningful type attached, this allows code - completion to work in the presence of minor semantic errors. - - The C# AST makes use of special null nodes when accessing the getter of an AST property and no - child node with that role exists. Check the IsNull property to test whether a node is a null node. - Null nodes are not considered to be part of the AST (e.g. they don't have a parent). + As a result, `NullReferenceExceptions` should be very rare when working with this library. In the type system, both `ITypeReference` and `IType` use `SpecialType.UnknownType` to represent unknown types. Unless the XML documentation says otherwise, no method or property returning a `ITypeReference` or `IType` will return null. + +>**_Note** that the null object pattern is not used for `ITypeDefinition`. + `IProjectContent.GetClass()` returns null when a type is not found. Take care to abort your operation or substitute UnknownType instead of passing the null to code expecting an `IType`._ + +>_The pattern also extends to the C# resolver, which always produces a `ResolveResult`, even in +error cases. Use `ResolveResult.IsError` to detect resolver errors. +Also note that many resolver errors still have a meaningful type attached, this allows code +completion to work in the presence of minor semantic errors._ -#### FAQ: -**Q: What is the difference between NRefactory and Roslyn?** +>_The C# AST makes use of special null nodes when accessing the getter of an AST property and no +child node with that role exists. Check the IsNull property to test whether a node is a null node.Null nodes are not considered to be part of the AST (e.g. they don't have a parent)._ + +FAQ +---- +**Q: What is the difference between NRefactory and Roslyn?** +**A:** - NRefactory is ready and stable, Roslyn is only a CTP at this point of time. - NRefactory does not have VB support. - NRefactory cannot compile code to IL; it's not a full compiler, just a frontend. - NRefactory C# AST is mutable and supports pattern matching; Roslyn is immutable and does not have built-in pattern matching. -**Q: What is the difference between types and type definitions?** +**Q: What is the difference between types and type definitions?** + +**A:** Basically, a type `IType` is any type in the .NET type system: -**A:** Basically, a type (IType) is any type in the .NET type system: - an array (ArrayType) - a pointer (PointerType) - a managed reference (ByReferenceType) @@ -130,97 +119,75 @@ Null-Object pattern: - a type parameter (ITypeParameter, e.g. T) - or a type definition (ITypeDefiniton) - Type definitions are only classes, structs, enums and delegates. - Every type definition is a type, but not every type is a type definition. - NRefactory's ITypeDefinition derives from IType, so you can directly use any type definition - as a type. - In the other direction, you could try to cast a type to ITypeDefinition, or you can call the - GetDefinition() method. The GetDefinition() method will also return the underlying - ITypeDefinition if given a parameterized type, so "List".GetDefinition() is "List". +Type definitions are only classes, structs, enums and delegates. +Every type definition is a type, but not every type is a type definition. +NRefactory's `ITypeDefinition` derives from `IType`, so you can directly use any type definition +as a type. In the other direction, you could try to cast a type to ITypeDefinition, or you can call the `GetDefinition()` method. The `GetDefinition()` method will also return the underlying +ITypeDefinition if given a parameterized type, so `List.GetDefinition()` is `List`. -Q: What is the difference between types and type references? - I've seen lots of duplicated classes (ArrayType vs. ArrayTypeReference, etc.) +**Q: What is the difference between types and type references?** _I've seen lots of duplicated classes (ArrayType vs. ArrayTypeReference, etc.)_ -A: If you've previously used the .NET Reflection API, the concept of type references will be new - to you. - - NRefactory has the concept of the "unresolved type system": every assembly/project is stored - in unresolved form. - It is possible to load some source code into a project which contains the type reference - "int[]" without having to load mscorlib into NRefactory. - So inside the entities stored for the project, the array type is only referenced using an - ITypeReference. - This interface has a single method: +**A:** If you've previously used the .NET Reflection API, the concept of type references will be new to you. NRefactory has the concept of the "unresolved type system": every assembly/project is stored in unresolved form. It is possible to load some source code into a project which contains the type reference `int[]` without having to load mscorlib into NRefactory. So inside the entities stored for the project, the array type is only referenced using an `ITypeReference`. +This interface has a single method: + +```csharp interface ITypeReference { IType Resolve(ITypeResolutionContext context); } - By calling the Resolve()-method, you will get back the actual ArrayType. - - Not only type references are split up this way; pretty much every class in the type system - comes in unresolved and resolved forms. +``` +By calling the `Resolve()` method, you will get back the actual ArrayType. +Not only type references are split up this way; pretty much every class in the type system comes in unresolved and resolved forms. -Q: What is a compilation (ICompilation)? +**Q: What is a compilation (ICompilation)?** -A: A compilation serves as the root object of the resolved type system. +**A:** A compilation serves as the root object of the resolved type system. It consists of a main assembly and multiple referenced assemblies, and may also contain additional information like compiler options. -Q: What's in an ITypeResolveContext? +**Q: What's in an ITypeResolveContext?** -A: An ITypeResolveContext is an environment for looking up namespaces and types. +**A:** An ITypeResolveContext is an environment for looking up namespaces and types. It consists of the current compilation, the current type definition, - and language-specific implementations may add additional information (e.g. the list of usings). - - Generally, you cannot resolve a type reference without knowing what kind of context is expected. + and language-specific implementations may add additional information (e.g. the list of usings).Generally, you cannot resolve a type reference without knowing what kind of context is expected. -Q: How do I get the IType or ITypeReference for a primitive type such as string or int? - -A: To get an IType for a primitive type, use: - compilation.FindType(KnownTypeCode.Int32) +**Q: How do I get the IType or ITypeReference for a primitive type such as string or int?** - To get an ITypeReference, use: - KnownTypeReference.Int32 - - It is also possible to use a System.Type for retrieving a type: - compilation.FindType(typeof(int)) - or - typeof(int).ToTypeReference(). +**A:** To get an IType for a primitive type, use: +```csharp +compilation.FindType(KnownTypeCode.Int32) +``` +To get an ITypeReference, use: +```csharp +KnownTypeReference.Int32 +``` +It is also possible to use a System.Type for retrieving a type: +```csharp +compilation.FindType(typeof(int)) +// or +typeof(int).ToTypeReference() +``` -Q: Is it thread-safe? +**Q: Is it thread-safe?** -A: This question is a bit difficult to answer. - NRefactory was designed to be usable in a multi-threaded IDE. - But of course, this does not mean that everything is thread-safe. - - First off, there's no hidden static state, so any two operations working on independent data - can be executed concurrently. - [Actually, sometimes static state is used for caches, but those uses are thread-safe.] - TODO: what about the C# parser? gmcs is full of static state... - -> this is being worked on; for the time being, NRefactory uses a global lock during parsing; +**A:** This question is a bit difficult to answer. NRefactory was designed to be usable in a multi-threaded IDE. But of course, this does not mean that everything is thread-safe. First off, there's no hidden static state, so any two operations working on independent data can be executed concurrently. [_Actually, sometimes static state is used for caches, but those uses are thread-safe._] + + **_TODO:** what about the C# parser? gmcs is full of static state..._ +-> this is being worked on; for the time being, NRefactory uses a global lock during parsing; so it's thread-safe but slow. - Some instance methods may use hidden instance state, so it is not safe to e.g. use an instance - of the CSharp.Resolver.TypeInference class concurrently. - Instead, you need to create an instance on every thread. - - The type system itself is thread-safe. Both the unresolved and the resolved type systems are - immutable. - - When you add to an IProjectContent, the existing project content isn't modified, - but a new project content is created instead. All implementations of the type system interfaces - are either immutable or freezable. +Some instance methods may use hidden instance state, so it is not safe to e.g. use an instance +of the CSharp.Resolver.TypeInference class concurrently. Instead, you need to create an instance on every thread. The type system itself is thread-safe. Both the unresolved and the resolved type systems are immutable. - And on the resolved type system side, ICompilation is immutable as well. - Internally, the resolved type system will resolve elements only on demand, but this is done - in a thread-safe manner. +When you add to an IProjectContent, the existing project content isn't modified, but a new project content is created instead. All implementations of the type system interfaces are either immutable or freezable. And on the resolved type system side, ICompilation is immutable as well. +Internally, the resolved type system will resolve elements only on demand, but this is done in a thread-safe manner. -Q: What format do the .ToString() methods use? +**Q: What format do the `ToString()` methods use?** -A: They don't use any particular format. They're merely intended as a debugging aid. - Currently .ToString() usually matches .ReflectionName, but that may change in the future. +**A:** They don't use any particular format. They're merely intended as a debugging aid. + Currently `ToString()` usually matches .ReflectionName, but that may change in the future.